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 RAG (Retrieval-Augmented Generation) di mana Claude perlu mengatribusikan jawaban ke dokumen Anda.
Semua model aktif mendukung hasil pencarian dengan sitasi, dengan pengecualian Claude Haiku 3. Tidak diperlukan header beta: hasil pencarian adalah bagian dari Messages API standar.
Hasil pencarian dapat disediakan dengan dua cara:
Dalam kedua kasus tersebut, Claude mengutip hasil pencarian secara otomatis ketika sitasi diaktifkan. Tidak diperlukan prompting khusus: ajukan pertanyaan Anda, dan sitasi akan muncul pada blok teks yang mengambil dari konten Anda.
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 | Tipe | Deskripsi |
|---|---|---|
type | string | Harus "search_result" |
source | string | Sumber konten. String stabil apa pun dapat digunakan: URL, atau pengidentifikasi internal seperti kb://article-1234 |
title | string | Judul deskriptif untuk hasil pencarian |
content | array | Array blok teks yang berisi konten sebenarnya |
| 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 yang tidak kosong)Hasil pencarian hanya menampung teks. Gambar dan media lainnya tidak didukung di dalam array content.
Mengembalikan hasil pencarian dari alat kustom Anda memungkinkan aplikasi RAG dinamis: alat mengambil konten saat runtime, dan Claude mengutipnya dalam respons. Contoh berikut memaksa pemanggilan alat dengan tool_choice, sehingga langkah pengambilan berjalan setiap saat.
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)Anda juga dapat menyediakan hasil pencarian langsung dalam pesan pengguna. Ini berguna untuk:
from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Berikan hasil pencarian langsung di dalam pesan pengguna
response = client.messages.create(
model="claude-opus-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)Terlepas dari bagaimana hasil pencarian disediakan, Claude secara otomatis menyertakan sitasi saat 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
}
]
}
]
}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 digabungkan bersama. 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 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 sebuah blok. Untuk mendapatkan sitasi yang lebih terperinci, pecah konten hasil pencarian Anda menjadi blok-blok yang lebih kecil (lihat 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:
{
"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 yang dicakup oleh sitasi, dan cited_text berisi tepat teks dari blok-blok tersebut. Memecah konten menjadi blok-blok yang lebih kecil dan terfokus memberi Claude batas sitasi yang lebih terperinci; 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.
Anda dapat mencampur kedua metode dalam percakapan yang sama. Claude mengutip dari salah satu sumber, dan search_result_index menghitung semua blok search_result sesuai urutan permintaan, terlepas dari sumbernya.
Contoh berikut memutar ulang percakapan lengkap. Pesan pengguna pertama membawa hasil pencarian yang sudah 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"],
},
}
# Memutar ulang percakapan yang menyediakan hasil pencarian dengan dua cara: pesan pengguna
# pertama membawa hasil yang telah diambil sebelumnya, tool result mengembalikan hasil lainnya
response = client.messages.create(
model="claude-opus-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 sudah 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
}
]
}
]
}Dalam pesan pengguna, blok search_result dapat berdampingan dengan blok konten lainnya. 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 merupakan 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 tersebut juga menjadi dapat dikutip.
Tambahkan cache_control pada blok hasil pencarian untuk menyimpannya dalam cache agar dapat digunakan kembali di berbagai permintaan. Ini berada 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.
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 disetel ke true, Claude melampirkan referensi sitasi ke blok teks yang mengambil dari hasil pencarian.
Strukturkan hasil secara efektif:
Jaga konsistensi:
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.
search_result hanya dapat muncul dalam pesan pengguna (termasuk di dalam hasil alat). Pesan asisten dengan hasil pencarian akan ditolak.search_result.Deteksi dan tangani alasan berhenti berupa penolakan dalam respons streaming, dan coba ulang permintaan yang ditolak pada model cadangan.
Landaskan respons Claude pada dokumen sumber Anda. Sitasi mengembalikan bagian teks persis yang mendukung setiap klaim, sehingga Anda dapat memverifikasi jawaban dan menampilkan sumber kepada pengguna Anda.
Beri Claude akses ke konten web terkini dengan sumber yang dikutip, pemfilteran dinamis opsional, dan kontrol domain.
Lihat dokumentasi Messages API lengkap, termasuk tipe blok konten.
Simpan hasil pencarian dalam cache dengan cache_control untuk mengurangi biaya dan latensi pada permintaan berulang.
Was this page helpful?