Blok konten hasil pencarian memungkinkan kutipan alami dengan atribusi sumber yang tepat, membawa kutipan berkualitas pencarian web ke aplikasi kustom Anda. Fitur ini sangat powerful untuk aplikasi RAG (Retrieval-Augmented Generation) di mana Anda perlu Claude mengutip sumber secara akurat.

Fitur hasil pencarian tersedia pada model-model berikut:

  • Claude 3.5 Haiku (claude-3-5-haiku-20241022)
  • Claude 3.5 Sonnet (claude-3-5-sonnet-20241022)
  • Claude 3.7 Sonnet (claude-3-7-sonnet-20250219)
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)

​
Manfaat utama

  • Kutipan alami - Mencapai kualitas kutipan yang sama dengan pencarian web untuk konten apa pun
  • Integrasi fleksibel - Gunakan dalam return tool untuk RAG dinamis atau sebagai konten tingkat atas untuk data yang sudah diambil sebelumnya
  • Atribusi sumber yang tepat - Setiap hasil mencakup informasi sumber dan judul untuk atribusi yang jelas
  • Tidak perlu workaround dokumen - Menghilangkan kebutuhan untuk workaround berbasis dokumen
  • Format kutipan yang konsisten - Sesuai dengan kualitas dan format kutipan dari fungsionalitas pencarian web Claude

​
Cara kerjanya

Hasil pencarian dapat disediakan dalam dua cara:

  1. Dari panggilan tool - Tool kustom Anda mengembalikan hasil pencarian, memungkinkan aplikasi RAG dinamis
  2. Sebagai konten tingkat atas - Anda menyediakan hasil pencarian langsung dalam pesan pengguna untuk konten yang sudah diambil sebelumnya atau di-cache

Dalam kedua kasus, Claude dapat secara otomatis mengutip informasi dari hasil pencarian dengan atribusi sumber yang tepat.

​
Skema hasil pencarian

Hasil pencarian menggunakan struktur berikut:

{
  "type": "search_result",
  "source": "https://example.com/article",  // Wajib: URL sumber atau identifier
  "title": "Article Title",                  // Wajib: Judul hasil
  "content": [ // Wajib: Array blok teks
    {
      "type": "text",
      "text": "The actual content of the search result..."
    }
  ],
  "citations": {                             // Opsional: Konfigurasi kutipan
    "enabled": true                          // Aktifkan/nonaktifkan kutipan untuk hasil ini
  }
}

​
Field wajib

FieldTypeDeskripsi
typestringHarus "search_result"
sourcestringURL sumber atau identifier untuk konten
titlestringJudul deskriptif untuk hasil pencarian
contentarrayArray blok teks yang berisi konten aktual

​
Field opsional

FieldTypeDeskripsi
citationsobjectKonfigurasi kutipan dengan field boolean enabled
cache_controlobjectPengaturan kontrol cache (misalnya, {"type": "ephemeral"})

Setiap item dalam array content harus berupa blok teks dengan:

  • type: Harus "text"
  • text: Konten teks aktual (string non-kosong)

​
Metode 1: Hasil pencarian dari panggilan tool

Kasus penggunaan paling powerful adalah mengembalikan hasil pencarian dari tool kustom Anda. Ini memungkinkan aplikasi RAG dinamis di mana tool mengambil dan mengembalikan konten yang relevan dengan kutipan otomatis.

​
Contoh: Tool knowledge base

from anthropic import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam,
    ToolResultBlockParam
)

client = Anthropic()

# Definisikan tool pencarian knowledge base
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Search the company knowledge base for information",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The search query"
            }
        },
        "required": ["query"]
    }
}

# Fungsi untuk menangani panggilan tool
def search_knowledge_base(query):
    # Logika pencarian Anda di sini
    # Mengembalikan hasil pencarian dalam format yang benar
    return [
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Product Configuration Guide",
            content=[
                TextBlockParam(
                    type="text",
                    text="To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs."
                )
            ],
            citations={"enabled": True}
        ),
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Troubleshooting Guide",
            content=[
                TextBlockParam(
                    type="text",
                    text="If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Buat pesan dengan tool
response = client.messages.create(
    model="claude-sonnet-4-20250514",  # Bekerja dengan semua model yang didukung
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content="How do I configure the timeout settings?"
        )
    ]
)

# Ketika Claude memanggil tool, berikan hasil pencarian
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Kirim hasil tool kembali
    final_response = client.messages.create(
        model="claude-sonnet-4-20250514",  # Bekerja dengan semua model yang didukung
        max_tokens=1024,
        messages=[
            MessageParam(role="user", content="How do I configure the timeout settings?"),
            MessageParam(role="assistant", content=response.content),
            MessageParam(
                role="user",
                content=[
                    ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # Hasil pencarian masuk ke sini
                    )
                ]
            )
        ]
    )

​
Metode 2: Hasil pencarian sebagai konten tingkat atas

Anda juga dapat menyediakan hasil pencarian langsung dalam pesan pengguna. Ini berguna untuk:

  • Konten yang sudah diambil sebelumnya dari infrastruktur pencarian Anda
  • Hasil pencarian yang di-cache dari query sebelumnya
  • Konten dari layanan pencarian eksternal
  • Testing dan development

​
Contoh: Hasil pencarian langsung

from anthropic import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam
)

client = Anthropic()

# Berikan hasil pencarian langsung dalam pesan pengguna
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="API Reference - Authentication",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Getting Started Guide",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."
                        )
                    ],
                    citations={"enabled": True}
                ),
                TextBlockParam(
                    type="text",
                    text="Based on these search results, how do I authenticate API requests and what are the rate limits?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

​
Respons Claude dengan kutipan

Terlepas dari bagaimana hasil pencarian disediakan, Claude secara otomatis menyertakan kutipan saat menggunakan informasi dari mereka:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "To authenticate API requests, you need to include an API key in the Authorization header",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "All API requests must include an API key in the Authorization header",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". You can generate API keys from your dashboard",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "Keys can be generated from the dashboard",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". The rate limits are 1,000 requests per hour for the standard tier and 10,000 requests per hour for the premium tier.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "Rate limits: 1000 requests per hour for standard tier, 10000 for premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

​
Field kutipan

Setiap kutipan mencakup:

FieldTypeDeskripsi
typestringSelalu "search_result_location" untuk kutipan hasil pencarian
sourcestringSumber dari hasil pencarian asli
titlestring atau nullJudul dari hasil pencarian asli
cited_textstringTeks yang tepat yang dikutip
search_result_indexintegerIndeks hasil pencarian (berbasis 0)
start_block_indexintegerPosisi awal dalam array konten
end_block_indexintegerPosisi akhir dalam array konten

Catatan: search_result_index merujuk pada indeks blok konten hasil pencarian (berbasis 0), terlepas dari bagaimana hasil pencarian disediakan (panggilan tool atau konten tingkat atas).

​
Beberapa blok konten

Hasil pencarian dapat berisi beberapa blok teks dalam array content:

{
  "type": "search_result",
  "source": "https://docs.company.com/api-guide",
  "title": "API Documentation",
  "content": [
    {
      "type": "text",
      "text": "Authentication: All API requests require an API key."
    },
    {
      "type": "text",
      "text": "Rate Limits: The API allows 1000 requests per hour per key."
    },
    {
      "type": "text",
      "text": "Error Handling: The API returns standard HTTP status codes."
    }
  ]
}

Claude dapat mengutip blok spesifik menggunakan field start_block_index dan end_block_index.

​
Penggunaan lanjutan

​
Menggabungkan kedua metode

Anda dapat menggunakan hasil pencarian berbasis tool dan tingkat atas dalam percakapan yang sama:

# Pesan pertama dengan hasil pencarian tingkat atas
messages = [
    MessageParam(
        role="user",
        content=[
            SearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Product Overview",
                content=[
                    TextBlockParam(type="text", text="Our product helps teams collaborate...")
                ],
                citations={"enabled": True}
            ),
            TextBlockParam(
                type="text",
                text="Tell me about this product and search for pricing information"
            )
        ]
    )
]

# Claude mungkin merespons dan memanggil tool untuk mencari informasi harga
# Kemudian Anda menyediakan hasil tool dengan lebih banyak hasil pencarian

​
Menggabungkan dengan jenis konten lain

Kedua metode mendukung pencampuran hasil pencarian dengan konten lain:

# Dalam hasil tool
tool_result = [
    SearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="User Guide",
        content=[TextBlockParam(type="text", text="Configuration details...")],
        citations={"enabled": True}
    ),
    TextBlockParam(
        type="text",
        text="Additional context: This applies to version 2.0 and later."
    )
]

# Dalam konten tingkat atas
user_content = [
    SearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Research Paper",
        content=[TextBlockParam(type="text", text="Key findings...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    TextBlockParam(
        type="text",
        text="How does the chart relate to the research findings?"
    )
]

​
Kontrol cache

Tambahkan kontrol cache untuk performa yang lebih baik:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

​
Kontrol kutipan

Secara default, kutipan dinonaktifkan untuk hasil pencarian. Anda dapat mengaktifkan kutipan dengan secara eksplisit mengatur konfigurasi citations:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{"type": "text", "text": "Important documentation..."}],
  "citations": {
    "enabled": true  // Aktifkan kutipan untuk hasil ini
  }
}

Ketika citations.enabled diatur ke true, Claude akan menyertakan referensi kutipan saat menggun informasi dari hasil pencarian. Ini memungkinkan:

  • Kutipan alami untuk aplikasi RAG kustom Anda
  • Atribusi sumber saat berinteraksi dengan knowledge base proprietary
  • Kutipan berkualitas pencarian web untuk tool kustom apa pun yang mengembalikan hasil pencarian

Jika field citations dihilangkan, kutipan dinonaktifkan secara default.

Kutipan bersifat all-or-nothing: baik semua hasil pencarian dalam permintaan harus memiliki kutipan yang diaktifkan, atau semua harus dinonaktifkan. Mencampur hasil pencarian dengan pengaturan kutipan yang berbeda akan menghasilkan error. Jika Anda perlu menonaktifkan kutipan untuk beberapa sumber, Anda harus menonaktifkannya untuk semua hasil pencarian dalam permintaan tersebut.

​
Best practices

​
Untuk pencarian berbasis tool (Metode 1)

  • Konten dinamis: Gunakan untuk pencarian real-time dan aplikasi RAG dinamis
  • Error handling: Kembalikan pesan yang sesuai ketika pencarian gagal
  • Batas hasil: Kembalikan hanya hasil yang paling relevan untuk menghindari overflow konteks

​
Untuk pencarian tingkat atas (Metode 2)

  • Konten yang sudah diambil sebelumnya: Gunakan ketika Anda sudah memiliki hasil pencarian
  • Batch processing: Ideal untuk memproses beberapa hasil pencarian sekaligus
  • Testing: Bagus untuk menguji perilaku kutipan dengan konten yang diketahui

​
Best practices umum

  1. Struktur hasil secara efektif

    • Gunakan URL sumber yang jelas dan permanen
    • Berikan judul yang deskriptif
    • Pecah konten panjang menjadi blok teks yang logis

  2. Pertahankan konsistensi

    • Gunakan format sumber yang konsisten di seluruh aplikasi Anda
    • Pastikan judul secara akurat mencerminkan konten
    • Jaga formatting tetap konsisten

  3. Tangani error dengan baik

    def search_with_fallback(query):
    try:
        results = perform_search(query)
        if not results:
            return {"type": "text", "text": "No results found."}
        return format_as_search_results(results)
    except Exception as e:
        return {"type": "text", "text": f"Search error: {str(e)}"}

​
Keterbatasan

  • Blok konten hasil pencarian tersedia di Anthropic API dan Google Cloud’s Vertex AI
  • Hanya konten teks yang didukung dalam hasil pencarian (tidak ada gambar atau media lain)
  • Array content harus berisi setidaknya satu blok teks