MessagesKemampuan model

Hasil pencarian

Aktifkan sitasi alami untuk aplikasi RAG dengan menyediakan hasil pencarian yang disertai atribusi sumber

Blok konten hasil pencarian memungkinkan Claude mengutip konten Anda sendiri dengan cara yang sama seperti mengutip hasil pencarian web: setiap sitasi membawa sumber dan judul yang Anda berikan. Gunakan blok ini dalam aplikasi "Retrieval-Augmented Generation" (generasi yang diperkaya pengambilan), atau RAG, di mana Claude perlu mengatribusikan jawaban ke dokumen Anda.

Semua model aktif mendukung hasil pencarian dengan sitasi, kecuali Claude Haiku 3. Tidak diperlukan header beta: hasil pencarian merupakan bagian dari Messages API standar.

Cara kerjanya

Hasil pencarian dapat disediakan dengan dua cara:

Dari pemanggilan alat: Alat kustom Anda mengembalikan hasil pencarian, memungkinkan aplikasi RAG yang dinamis
Sebagai konten tingkat atas: Anda menyediakan hasil pencarian langsung dalam pesan pengguna untuk konten yang telah diambil sebelumnya atau di-cache

Dalam kedua kasus, Claude mengutip hasil pencarian secara otomatis ketika sitasi diaktifkan. Tidak diperlukan prompt khusus: ajukan pertanyaan Anda, dan sitasi akan muncul pada blok teks yang mengambil dari konten Anda.

Skema hasil pencarian

Hasil pencarian menggunakan struktur berikut:

{
  "type": "search_result",
  "source": "https://example.com/article", // Required: Source URL or identifier
  "title": "Article Title", // Required: Title of the result
  "content": [
    // Required: Array of text blocks
    {
      "type": "text",
      "text": "The actual content of the search result..."
    }
  ],
  "citations": {
    // Optional: Citation configuration
    "enabled": true // Enable/disable citations for this result
  }
}

Field wajib

Field	Tipe	Deskripsi
`type`	string	Harus `"search_result"`
`source`	string	Sumber konten. String stabil apa pun dapat digunakan: URL, atau pengenal internal seperti `kb://article-1234`
`title`	string	Judul deskriptif untuk hasil pencarian
`content`	array	Array blok teks yang berisi konten sebenarnya

Field opsional

Field	Tipe	Deskripsi
`citations`	object	Konfigurasi sitasi dengan field Boolean `enabled`. Sitasi dinonaktifkan secara default; setiap contoh di halaman ini menetapkan `"enabled": true` secara eksplisit. Semua hasil pencarian dalam satu permintaan harus menggunakan pengaturan yang sama (lihat Kontrol sitasi)
`cache_control`	object	Pengaturan kontrol cache (misalnya, `{"type": "ephemeral"}`)

Setiap item dalam array content harus berupa blok teks dengan:

type: Harus "text"
text: Konten teks sebenarnya (string tidak kosong)

Hasil pencarian hanya memuat teks. Gambar dan media lain tidak didukung di dalam array content.

Metode 1: Hasil pencarian dari pemanggilan alat

Mengembalikan hasil pencarian dari alat kustom Anda memungkinkan aplikasi RAG yang dinamis: alat mengambil konten saat runtime, dan Claude mengutipnya dalam respons. Contoh berikut memaksa pemanggilan alat dengan tool_choice, sehingga langkah pengambilan berjalan setiap kali.

Contoh: Alat basis pengetahuan

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

client = Anthropic()

# Definisikan alat pencarian basis pengetahuan
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 pemanggilan alat
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},
        ),
    ]


# Bangun percakapan dalam sebuah list, dimulai dengan pertanyaan pengguna
messages = [
    MessageParam(role="user", content="How do I configure the timeout settings?")
]

# Buat pesan dengan alat tersebut
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    tool_choice={"type": "tool", "name": "search_knowledge_base"},
    messages=messages,
)

# Saat Claude memanggil alat, berikan hasil pencariannya.
# Blok tool_use tidak selalu berada di urutan pertama: lakukan iterasi untuk menemukannya.
tool_use = next((block for block in response.content if block.type == "tool_use"), None)
if tool_use is not None:
    tool_result = search_knowledge_base(tool_use.input["query"])

    # Tambahkan giliran Claude, lalu hasil alat, ke percakapan yang sedang berjalan
    messages.append(MessageParam(role="assistant", content=response.content))
    messages.append(
        MessageParam(
            role="user",
            content=[
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id=tool_use.id,
                    content=tool_result,  # Search results go here
                )
            ],
        )
    )

    # Kirim kembali hasil alat
    final_response = client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        messages=messages,
    )
    print(final_response)

Metode 2: Hasil pencarian sebagai konten tingkat atas

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

Konten yang telah diambil sebelumnya dari infrastruktur pencarian Anda
Hasil pencarian yang di-cache dari kueri sebelumnya
Konten dari layanan pencarian eksternal
Pengujian dan pengembangan

Contoh: Hasil pencarian langsung

from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam

client = Anthropic()

# Berikan hasil pencarian langsung di pesan pengguna
response = client.messages.create(
    model="claude-opus-5-5",
    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)

Respons Claude dengan sitasi

Terlepas dari bagaimana hasil pencarian disediakan, Claude secara otomatis menyertakan sitasi ketika menggunakan informasi dari hasil tersebut:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_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.",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    },
    {
      "type": "text",
      "text": "\n\nTo set this up from scratch, you'll need to "
    },
    {
      "type": "text",
      "text": "sign up for an account, generate an API key from the dashboard, install the SDK using `pip install company-sdk`, and initialize the client with your API key.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_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.",
          "source": "https://docs.company.com/quickstart",
          "title": "Getting Started Guide",
          "search_result_index": 1,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}

Field sitasi

Setiap sitasi mencakup:

Field	Tipe	Deskripsi
`type`	string	Selalu `"search_result_location"` untuk sitasi hasil pencarian
`source`	string	Sumber dari hasil pencarian asli
`title`	string atau null	Judul dari hasil pencarian asli
`cited_text`	string	Teks lengkap dari blok yang dikutip, digabungkan. Sama dengan isi `content[start_block_index:end_block_index]` yang disatukan. Tidak dihitung sebagai token output.
`search_result_index`	integer	Indeks berbasis 0 dari hasil pencarian yang dikutip di antara semua blok `search_result` dalam permintaan, sesuai urutan kemunculannya (di seluruh pesan dan hasil alat).
`start_block_index`	integer	Indeks berbasis 0 dari blok pertama yang dikutip dalam array `content` hasil pencarian.
`end_block_index`	integer	Indeks akhir eksklusif dari rentang blok yang dikutip dalam array `content` hasil pencarian. Selalu lebih besar dari `start_block_index`.

Indeks blok mengidentifikasi sebuah irisan dari array content hasil pencarian, dan cited_text adalah teks lengkap dari irisan tersebut. Blok teks adalah unit terkecil yang dapat dikutip: Claude mengutip blok secara utuh, bukan substring di dalam blok. Untuk mendapatkan sitasi yang lebih terperinci, pecah konten hasil pencarian Anda menjadi blok-blok yang lebih kecil (lihat Beberapa blok konten).

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."
    }
  ],
  "citations": { "enabled": true }
}

Sitasi yang merujuk pada blok batas laju terlihat seperti ini:

{
  "type": "search_result_location",
  "cited_text": "Rate Limits: The API allows 1000 requests per hour per key.",
  "source": "https://docs.company.com/api-guide",
  "title": "API Documentation",
  "search_result_index": 0,
  "start_block_index": 1,
  "end_block_index": 2
}

Ketika hasil pencarian ini dikutip, start_block_index dan end_block_index mengidentifikasi blok mana saja yang dicakup oleh sitasi, dan cited_text berisi persis teks dari blok-blok tersebut. Memecah konten menjadi blok yang lebih kecil dan terfokus memberi Claude batas sitasi yang lebih halus; menggabungkan konten menjadi satu blok berarti setiap sitasi mengembalikan teks lengkap. Ini adalah model yang sama yang digunakan oleh dokumen konten kustom dalam fitur Citations.

Penggunaan lanjutan

Menggabungkan kedua metode

Anda dapat mencampur kedua metode dalam percakapan yang sama. Claude mengutip dari sumber mana pun, dan search_result_index menghitung semua blok search_result sesuai urutan permintaan, terlepas dari sumbernya.

Contoh berikut memutar ulang sebuah percakapan lengkap. Pesan pengguna pertama membawa hasil pencarian yang telah diambil sebelumnya, giliran asisten memanggil alat basis pengetahuan, dan hasil alat mengembalikan hasil pencarian kedua. Jawaban Claude mengutip kedua sumber:

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

client = Anthropic()

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"],
    },
}

# Putar ulang percakapan yang memberikan hasil pencarian dengan dua cara: pesan
# pengguna pertama membawa hasil yang sudah diambil, hasil alat mengembalikan yang lain
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/overview",
                    title="Product Overview",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
                        )
                    ],
                    citations={"enabled": True},
                ),
                TextBlockParam(
                    type="text",
                    text="What does Acme Dashboard do, and what plans is it available on?",
                ),
            ],
        ),
        MessageParam(
            role="assistant",
            content=[
                TextBlockParam(
                    type="text", text="Let me check the pricing information."
                ),
                ToolUseBlockParam(
                    type="tool_use",
                    id="toolu_01A09q90qw90lq917835lq9",
                    name="search_knowledge_base",
                    input={"query": "Acme Dashboard pricing plans"},
                ),
            ],
        ),
        MessageParam(
            role="user",
            content=[
                ToolResultBlockParam(
                    type="tool_result",
                    tool_use_id="toolu_01A09q90qw90lq917835lq9",
                    content=[
                        SearchResultBlockParam(
                            type="search_result",
                            source="https://docs.company.com/pricing",
                            title="Pricing Plans",
                            content=[
                                TextBlockParam(
                                    type="text",
                                    text="Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
                                )
                            ],
                            citations={"enabled": True},
                        )
                    ],
                )
            ],
        ),
    ],
)

print(response)

Respons mengutip kedua sumber. Hasil yang telah diambil sebelumnya adalah search_result_index: 0 dan hasil yang dikembalikan alat adalah search_result_index: 1, sesuai dengan urutan kemunculan blok search_result dalam percakapan:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's what I found about Acme Dashboard:\n\n**What it does:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
          "source": "https://docs.company.com/overview",
          "title": "Product Overview",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    },
    {
      "type": "text",
      "text": "\n\n**Available plans:** "
    },
    {
      "type": "text",
      "text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
      "citations": [
        {
          "type": "search_result_location",
          "cited_text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
          "source": "https://docs.company.com/pricing",
          "title": "Pricing Plans",
          "search_result_index": 1,
          "start_block_index": 0,
          "end_block_index": 1
        }
      ]
    }
  ]
}

Mencampur dengan tipe konten lain

Dalam pesan pengguna, blok search_result dapat berdampingan dengan blok konten lain apa pun. Contoh Metode 2 memasangkan hasil pencarian dengan pertanyaan text, dan blok gambar atau dokumen dapat bergabung dengan cara yang sama.

Hasil alat lebih ketat: jika ada blok dalam array konten tool_result yang berupa search_result, semua bloknya harus berupa search_result. Mencampur hasil pencarian dengan tipe blok lain dalam hasil alat yang sama akan mengembalikan kesalahan validasi. Untuk mengembalikan teks pendukung bersama hasil pencarian yang bersumber dari alat, sertakan teks tersebut sebagai blok teks di dalam salah satu array content hasil pencarian, di mana teks itu juga menjadi dapat dikutip.

Kontrol cache

Tambahkan cache_control pada blok hasil pencarian untuk meng-cache-nya agar dapat digunakan kembali di berbagai permintaan. Pengaturan ini berdampingan dengan citations pada blok yang sama:

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

Lihat Caching prompt untuk panjang minimum yang dapat di-cache dan persyaratan lainnya.

Kontrol sitasi

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

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{ "type": "text", "text": "Important documentation..." }],
  "citations": {
    "enabled": true // Enable citations for this result
  }
}

Ketika citations.enabled diatur ke true, Claude melampirkan referensi sitasi pada blok teks yang mengambil dari hasil pencarian.

Praktik terbaik

Untuk pencarian berbasis alat (Metode 1)

Konten dinamis: Gunakan untuk pencarian real-time dan aplikasi RAG yang dinamis
Penanganan kesalahan: Kembalikan pesan yang sesuai ketika pencarian gagal
Batas hasil: Kembalikan hanya hasil yang paling relevan untuk menghindari luapan konteks

Untuk pencarian tingkat atas (Metode 2)

Konten yang telah diambil sebelumnya: Gunakan ketika Anda sudah memiliki hasil pencarian
Pemrosesan batch: Ideal untuk memproses beberapa hasil pencarian sekaligus
Pengujian: Sangat baik untuk menguji perilaku sitasi dengan konten yang sudah diketahui

Praktik terbaik umum

Susun hasil secara efektif:
- Gunakan URL sumber yang jelas dan permanen
- Berikan judul yang deskriptif
- Pecah konten panjang menjadi blok teks yang logis untuk memberi Claude batas sitasi yang lebih halus
Jaga konsistensi:
- Gunakan format sumber yang konsisten di seluruh aplikasi Anda
- Pastikan judul mencerminkan konten secara akurat
- Jaga konsistensi pemformatan
Tangani kesalahan dengan baik: ketika pencarian gagal atau tidak mengembalikan apa pun, kembalikan blok teks biasa yang menjelaskan hasilnya (misalnya, {"type": "text", "text": "No results found."}) alih-alih memunculkan kesalahan: Claude menjelaskan hasil kosong tersebut kepada pengguna, dan percakapan berlanjut.

Keterbatasan

Blok konten hasil pencarian tersedia di Claude API, Amazon Bedrock, dan Google Cloud.
Hanya konten teks yang didukung di dalam hasil pencarian (tanpa gambar atau media lain).
Blok search_result hanya dapat muncul dalam pesan pengguna (termasuk di dalam hasil alat). Pesan asisten dengan hasil pencarian akan ditolak.
Ketika alat pencarian web diaktifkan dalam permintaan yang sama, sitasi harus diaktifkan pada semua blok search_result.

Langkah selanjutnya

Penolakan streaming

Deteksi dan tangani alasan berhenti penolakan dalam respons streaming, dan coba ulang permintaan yang ditolak pada model cadangan.

Sitasi

Landaskan respons Claude pada dokumen sumber Anda. Sitasi mengembalikan kutipan persis yang mendukung setiap klaim, sehingga Anda dapat memverifikasi jawaban dan menampilkan sumber kepada pengguna Anda.

Alat pencarian web

Beri Claude akses ke konten web terkini dengan sumber yang dikutip, pemfilteran dinamis opsional, dan kontrol domain.

Referensi Messages API

Lihat dokumentasi lengkap Messages API, termasuk tipe blok konten.

Caching prompt

Cache hasil pencarian dengan cache_control untuk mengurangi biaya dan latensi pada permintaan berulang.

Cara kerjanya

Skema hasil pencarian

Field wajib

Field opsional

Metode 1: Hasil pencarian dari pemanggilan alat

Contoh: Alat basis pengetahuan

Metode 2: Hasil pencarian sebagai konten tingkat atas

Contoh: Hasil pencarian langsung

Respons Claude dengan sitasi

Field sitasi

Beberapa blok konten

Penggunaan lanjutan

Menggabungkan kedua metode

Mencampur dengan tipe konten lain

Kontrol cache

Kontrol sitasi

Praktik terbaik

Untuk pencarian berbasis alat (Metode 1)

Untuk pencarian tingkat atas (Metode 2)

Praktik terbaik umum

Keterbatasan

Langkah selanjutnya