Alat pencarian web
Berikan Claude akses ke konten web terkini dengan sumber yang dikutip, pemfilteran dinamis opsional, dan kontrol domain.
Penggunaan berbeda menurut produk
web_search ke tools permintaan. Pengaturan seperti max_uses, daftar domain, dan user_location ditempatkan pada alat tersebut.max_uses, citations, atau cache_control.Alat pencarian web memberi Claude akses langsung ke konten web real-time, memungkinkannya menjawab pertanyaan dengan informasi terkini di luar batas pengetahuannya. Respons mencakup kutipan untuk sumber yang diambil dari hasil pencarian.
Dengan web_search_20260209 dan versi yang lebih baru, Claude dapat menulis dan menjalankan kode yang memfilter hasil pencarian sebelum mencapai “context window” (jendela konteks) (“dynamic filtering” (pemfilteran dinamis)), sehingga hanya informasi yang relevan yang dipertahankan. Pemfilteran dinamis tersedia dengan Claude 4.6 dan model yang lebih baru serta Claude Mythos Preview.
Tiga versi alat pencarian web tersedia:
web_search_20250305: pencarian web dasarweb_search_20260209: menambahkan pemfilteran dinamisweb_search_20260318: menambahkan kontrol penyertaan respons untuk alur kerja agentik
Contoh-contoh di halaman ini menggunakan web_search_20250305 untuk pencarian dasar dan web_search_20260318 untuk pemfilteran dinamis.
Untuk kelayakan Zero Data Retention pencarian web dan konfigurasi allowed_callers terkait, lihat Alat server.
Untuk dukungan model, lihat Referensi alat.
Untuk memeriksa apakah suatu model menerima pencarian web sebelum Anda mengirim permintaan, baca nilai capabilities.server_tools.web_search.supported dari Models API. Menggunakan Models API menjelaskan field tersebut.
Cara kerja pencarian web
Saat Anda menambahkan alat pencarian web ke permintaan API Anda:
- Claude menentukan kapan harus mencari berdasarkan prompt.
- API menjalankan pencarian dan memberikan hasilnya kepada Claude. Proses ini dapat berulang beberapa kali dalam satu permintaan.
- Di akhir gilirannya, Claude memberikan respons akhir dengan sumber yang dikutip.
Kapan Claude melakukan pencarian
Claude melakukan pencarian ketika permintaan bergantung pada informasi yang terkini, berubah-ubah, atau berada di luar data pelatihannya:
- Peristiwa, berita, atau pengumuman terbaru
- Harga, tarif, skor, atau statistik terkini
- Informasi tentang organisasi, orang, atau produk tertentu yang mungkin telah berubah
- Permintaan eksplisit untuk mencari atau menelusuri sesuatu
Claude menjawab langsung tanpa mencari ketika permintaan mengandalkan pengetahuan yang stabil:
- Fakta yang sudah mapan, matematika, dasar-dasar sains, atau konsep pemrograman
- Penulisan kreatif atau brainstorming
- Analisis konten yang sudah diberikan dalam percakapan
- Giliran percakapan dan salam
Pemicuan dapat diarahkan melalui “system prompt” (prompt sistem) Anda: Anda dapat mendorong Claude untuk lebih mudah melakukan pencarian atau lebih memilih menjawab langsung. Untuk menerapkan batasan, gunakan max_uses untuk membatasi jumlah pencarian dalam satu giliran.
Pemfilteran dinamis
Dengan pencarian web dasar, setiap hasil pencarian dimuat ke dalam jendela konteks Claude, dan banyak dari konten tersebut bisa tidak relevan dengan permintaan. Dengan web_search_20260209 atau yang lebih baru, Claude justru menulis dan menjalankan kode yang memfilter hasil terlebih dahulu, sehingga hanya konten yang relevan yang mencapai jendela konteks. Ini mengurangi penggunaan token pada permintaan yang banyak melakukan pencarian.
Pemfilteran dinamis menjalankan pencarian web dari dalam eksekusi kode: pada web_search_20260209 dan yang lebih baru, field allowed_callers alat ini secara default bernilai ["code_execution_20260120"], dan ketika pemfilteran dinamis berjalan, API secara otomatis menyediakan eksekusi kode yang dibutuhkan untuk permintaan tersebut. Anda tidak perlu menambahkan alat eksekusi kode ke tools sendiri. Tidak ada biaya tambahan untuk panggilan eksekusi kode yang dilakukan dengan cara ini di luar biaya token standar.
Untuk memanggil pencarian web secara langsung, tanpa pemfilteran dinamis, atur allowed_callers: ["direct"]. Model yang tidak mendukung pemanggilan alat secara terprogram memerlukan pengaturan ini. Tanpanya, API mengembalikan error 400 yang memberi tahu Anda untuk mengaturnya.
Contoh-contoh berikut menggunakan web_search_20260318:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
}
],
tools=[{"type": "web_search_20260318", "name": "web_search"}],
)
print(response)Cara menggunakan pencarian web
Untuk cara pengaturan pencarian web organisasi Anda diterapkan dalam sesi Claude Managed Agents, lihat Membatasi domain pencarian web dan web fetch.
Sediakan alat pencarian web dalam permintaan API Anda:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[{"role": "user", "content": "What's the weather in NYC?"}],
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)Definisi alat
Alat pencarian web mendukung parameter berikut:
{
"type": "web_search_20250305",
"name": "web_search",
// Optional: Limit the number of searches
"max_uses": 5,
// Optional: Only include results from these domains.
// Use allowed_domains or blocked_domains, not both.
"allowed_domains": ["example.com", "trusteddomain.org"],
// Optional: Never include results from these domains
"blocked_domains": ["untrustedsource.com"],
// Optional: Localize search results
"user_location": {
"type": "approximate",
"city": "San Francisco",
"region": "California",
"country": "US",
"timezone": "America/Los_Angeles"
}
}Semua versi alat pencarian web menerima allowed_callers, yang mengontrol apakah Claude memanggil pencarian web secara langsung atau dari eksekusi kode melalui pemfilteran dinamis. Pada web_search_20260209 dan yang lebih baru, nilai default-nya adalah ["code_execution_20260120"], bukan ["direct"]. Lihat ZDR dan allowed_callers untuk cara mengonfigurasinya. web_search_20260318 dan yang lebih baru juga menerima response_inclusion.
Penggunaan maksimum
Parameter max_uses membatasi jumlah pencarian dalam satu giliran. Kueri tentang satu fakta biasanya menggunakan 1–3 pencarian; riset komparatif atau multi-entitas dapat menggunakan 10 atau lebih.
Pencarian yang gagal turut dihitung terhadap batas. Jika Claude memanggil pencarian web secara langsung lebih banyak dari yang diizinkan, web_search_tool_result berupa error dengan kode error max_uses_exceeded. Jika Claude memanggil pencarian web dari eksekusi kode lebih banyak dari yang diizinkan, proses eksekusi kode berakhir dengan error.
Satu giliran dapat mencakup beberapa permintaan. Sebuah permintaan melanjutkan giliran ketika permintaan tersebut dilanjutkan setelah pause_turn atau ketika pesan terakhirnya hanya berisi blok tool_result. Pencarian dari permintaan sebelumnya dalam giliran tersebut dihitung terhadap batas, kecuali Claude menjalankannya dari eksekusi kode melalui pemfilteran dinamis.
Pemfilteran domain
Berikan allowed_domains atau blocked_domains, bukan keduanya. Jika permintaan menyertakan keduanya, API mengembalikan error 400. Entri berupa domain polos dengan path opsional, misalnya example.com atau example.com/blog, tanpa skema.
Untuk aturan pemfilteran domain selengkapnya, lihat Pemfilteran domain di panduan Alat server.
Di Claude Managed Agents, atur field ini pada entri web_search dari toolset agen; lihat Membatasi domain pencarian web dan web fetch.
Lokalisasi
Parameter user_location memungkinkan Anda melokalkan hasil pencarian berdasarkan lokasi pengguna. Berikan setidaknya salah satu dari city, region, country, atau timezone.
type: Jenis lokasi (harusapproximate)city: Nama kotaregion: Wilayah atau negara bagiancountry: Kode negara dua huruf ISO 3166-1 alpha-2 (API menolak kode yang tidak didukung dengan error 400)timezone: ID zona waktu IANA
Di Claude Managed Agents, entri web_search dari toolset agen juga menerima user_location; lihat pengaturan alat web.
Penyertaan respons
Parameter response_inclusion mengontrol bagaimana blok hasil pencarian muncul dalam respons API ketika hasil tersebut dikonsumsi oleh panggilan eksekusi kode yang telah selesai dalam respons yang sama. Atur "response_inclusion": "excluded" untuk menghapus pasangan blok server_tool_use dan hasil bersarang tersebut sepenuhnya dari respons, untuk alur kerja agentik yang tidak memerlukan konten pencarian mentah. Penggunaan token tidak terpengaruh, karena Claude membaca output kode, bukan blok-blok ini. Nilai default-nya adalah "full". API selalu mengembalikan hasil dari panggilan langsung, atau dari panggilan eksekusi kode yang dijeda sebelum selesai, secara lengkap agar Anda dapat mengirimkannya kembali pada permintaan berikutnya.
{
"tools": [
{
"type": "web_search_20260318",
"name": "web_search",
"response_inclusion": "excluded"
}
]
}Respons
Berikut contoh struktur respons:
{
"role": "assistant",
"content": [
// 1. Claude's decision to search
{
"type": "text",
"text": "I'll search for when Claude Shannon was born."
},
// 2. The search query used
{
"type": "server_tool_use",
"id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
"name": "web_search",
"input": {
"query": "claude shannon birth date"
}
},
// 3. Search results
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
"content": [
{
"type": "web_search_result",
"url": "https://en.wikipedia.org/wiki/Claude_Shannon",
"title": "Claude Shannon - Wikipedia",
"encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
"page_age": "April 30, 2025"
}
]
},
{
"text": "Based on the search results, ",
"type": "text"
},
// 4. Claude's response with citations
{
"text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
"type": "text",
"citations": [
{
"type": "web_search_result_location",
"url": "https://en.wikipedia.org/wiki/Claude_Shannon",
"title": "Claude Shannon - Wikipedia",
"encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
"cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
}
]
}
],
"id": "msg_a930390d3a",
"usage": {
"input_tokens": 6039,
"output_tokens": 931,
"server_tool_use": {
"web_search_requests": 1
}
},
"stop_reason": "end_turn"
}Contoh ini menunjukkan pencarian langsung. Ketika pencarian berjalan melalui pemfilteran dinamis, respons juga berisi blok hasil dari alat eksekusi kode, dan setiap pasangan server_tool_use dan web_search_tool_result bersarang membawa field caller yang mengidentifikasi panggilan eksekusi kode yang membuatnya.
Hasil pencarian
Hasil pencarian mencakup:
url: URL halaman sumbertitle: Judul halaman sumberpage_age: Kapan situs terakhir diperbaruiencrypted_content: Konten terenkripsi yang harus Anda kirimkan kembali dalam percakapan multi-giliran
Untuk melanjutkan percakapan yang berisi hasil pencarian, kirim kembali blok konten asisten persis seperti yang Anda terima, termasuk encrypted_content dari setiap hasil. API mendekripsi konten tersebut pada permintaan berikutnya untuk memulihkan hasil pencarian dalam konteks Claude. Jika encrypted_content hilang atau dimodifikasi, permintaan gagal dengan error validasi 400.
Kutipan
Kutipan selalu diaktifkan untuk pencarian web, dan setiap web_search_result_location mencakup:
url: URL sumber yang dikutiptitle: Judul sumber yang dikutipencrypted_index: Referensi yang harus dikirimkan kembali untuk percakapan multi-gilirancited_text: Hingga 150 karakter dari konten yang dikutip
Field kutipan pencarian web cited_text, title, dan url tidak dihitung dalam penggunaan token input maupun output.
Error
Ketika alat pencarian web mengalami error (seperti mencapai “rate limit” (batas laju)), Claude API tetap mengembalikan respons 200 (sukses). Error direpresentasikan di dalam body respons menggunakan struktur berikut:
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_a93jad",
"content": {
"type": "web_search_tool_result_error",
"error_code": "max_uses_exceeded"
}
}Saat terjadi error, content berupa satu objek error, bukan daftar blok hasil. Pencarian yang berhasil tetapi tidak menemukan hasil yang cocok mengembalikan daftar content kosong, bukan error.
Berikut kode error yang mungkin muncul:
too_many_requests: Batas laju terlampauiinvalid_tool_input: Parameter kueri pencarian tidak validmax_uses_exceeded: Penggunaan maksimum alat pencarian web terlampauiquery_too_long: Kueri melebihi panjang maksimumrequest_too_large: Permintaan pencarian terlalu besar, biasanya karena daftar filter domain yang panjangunavailable: Terjadi error internal
Alasan berhenti pause_turn
API dapat menjeda giliran pencarian yang berjalan lama dan mengembalikan stop_reason: "pause_turn". Untuk melanjutkan, kirim kembali pesan asisten yang dijeda tanpa perubahan dalam permintaan baru.
Jika Claude memanggil pencarian web dan salah satu alat klien Anda dalam grup panggilan alat paralel yang sama, API justru mengembalikan stop_reason: "tool_use" dan belum menjalankan pencarian. Untuk melanjutkan, kembalikan hasil alat klien, dan API menjalankan pencarian pada permintaan berikutnya. Lihat Menggabungkan alat server dan alat klien dalam satu giliran.
Untuk loop sisi server dan penanganan pause_turn, lihat Loop sisi server dan pause_turn di panduan Alat server.
Caching prompt
Untuk melakukan cache definisi alat di seluruh giliran, lihat Penggunaan alat dengan caching prompt.
Streaming
Dengan streaming diaktifkan, Anda menerima event pencarian sebagai bagian dari stream. Ada jeda saat pencarian berjalan:
event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
// Claude's decision to search
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}
// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}
// Pause while search runs
// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}
// Claude's response with citations (omitted in this example)Permintaan batch
Anda dapat menyertakan alat pencarian web dalam Message Batches API. Panggilan alat pencarian web melalui Message Batches API dikenakan harga yang sama dengan yang ada di permintaan Messages API biasa.
Untuk melindungi kapasitas bersama, Batches API membatasi permintaan pencarian web untuk setiap organisasi, sehingga batch besar dengan banyak pencarian mungkin membutuhkan waktu lebih lama untuk selesai. Anda dapat melihat batas laju pencarian web organisasi Anda di halaman Batas laju di Claude Console. Untuk meminta batas yang lebih tinggi, hubungi tim penjualan dari halaman tersebut.
Penggunaan dan harga
Penggunaan web search (pencarian web) dikenakan biaya di luar penggunaan token:
{
"usage": {
"input_tokens": 105,
"output_tokens": 6039,
"cache_read_input_tokens": 7123,
"cache_creation_input_tokens": 7345,
"server_tool_use": {
"web_search_requests": 1
}
}
}Pencarian web tersedia di Claude API seharga $10 USD per 1.000 pencarian, ditambah biaya token standar untuk konten yang dihasilkan pencarian. Hasil pencarian web yang diambil sepanjang percakapan dihitung sebagai token input, baik dalam iterasi pencarian yang dijalankan selama satu giliran maupun dalam giliran percakapan berikutnya.
Setiap pencarian web dihitung sebagai satu penggunaan, terlepas dari jumlah hasil yang dikembalikan. Pencarian web yang gagal karena kesalahan tidak ditagih.
Langkah selanjutnya
Ambil dan baca konten dari URL tertentu untuk memperkaya konteks Claude dengan konten web langsung.
Bekerja dengan alat yang dijalankan Anthropic: blok server_tool_use, kelanjutan pause_turn, dan pemfilteran domain.
Direktori alat yang disediakan Anthropic dan referensi untuk properti definisi alat opsional.
Ketersediaan
Claude API
- API
- Messages API
- Managed Agents
- Model
- Semua model
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Model
- Semua model
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Model
- Semua model
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Model
- Semua model
- Catatan
Hanya alat pencarian web dasar (
web_search_20250305), tanpa pemfilteran dinamis.
Microsoft Foundry (hosted on Azure)
- API
- Messages API
- Model
- Semua model
- Catatan
Hanya alat pencarian web dasar (
web_search_20250305), tanpa pemfilteran dinamis.
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Model
- Semua model
Penanganan data
Ikhtisar penanganan dataEndpoint yang berlaku
/v1/messagesdengan alatweb_search
Tidak termasuk Model yang dicakup
Hasil pencarian web real-time dikembalikan dalam respons API. Pemfilteran dinamis untuk pencarian web tidak memenuhi syarat kelayakan ZDR atau HIPAA.
Pemfilteran dinamis untuk pencarian web tidak memenuhi syarat kelayakan ZDR atau HIPAA.
Apakah halaman ini membantu?