Alat pencarian web

Alat pencarian web memberikan Claude akses langsung ke konten web real-time, memungkinkannya menjawab pertanyaan dengan informasi terkini di luar cutoff pengetahuannya. Respons mencakup kutipan untuk sumber yang diambil dari hasil pencarian.

Versi alat pencarian web terbaru (web_search_20260209) mendukung penyaringan dinamis dengan Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, dan Claude Sonnet 4.6. Claude dapat menulis dan menjalankan kode untuk menyaring hasil pencarian sebelum mencapai jendela konteks, hanya menyimpan informasi yang relevan dan membuang sisanya. Ini menghasilkan respons yang lebih akurat sambil mengurangi konsumsi token. Versi alat sebelumnya (web_search_20250305) tetap tersedia tanpa penyaringan dinamis.

Untuk Claude Mythos Preview, pencarian web didukung di Claude API, Microsoft Foundry, dan Google Vertex AI. Pencarian web tidak tersedia untuk Mythos Preview di Amazon Bedrock.

Untuk kelayakan Zero Data Retention dan solusi allowed_callers, lihat Server tools.

Untuk dukungan model, lihat Tool reference.

Cara kerja pencarian web

Ketika Anda menambahkan alat pencarian web ke permintaan API Anda:

Claude memutuskan kapan harus mencari berdasarkan prompt.
API menjalankan pencarian dan memberikan Claude dengan hasilnya. Proses ini dapat berulang beberapa kali selama satu permintaan.
Di akhir gilirannya, Claude memberikan respons akhir dengan sumber yang dikutip.

Penyaringan dinamis

Pencarian web adalah tugas yang intensif token. Dengan pencarian web dasar, Claude perlu menarik hasil pencarian ke dalam konteks, mengambil HTML lengkap dari beberapa situs web, dan bernalar atas semuanya sebelum sampai pada jawaban. Seringkali, banyak konten ini tidak relevan, yang dapat menurunkan kualitas respons.

Dengan versi alat web_search_20260209, Claude dapat menulis dan menjalankan kode untuk memproses ulang hasil kueri. Alih-alih bernalar atas file HTML lengkap, Claude secara dinamis menyaring hasil pencarian sebelum memuatnya ke dalam konteks, hanya menyimpan apa yang relevan dan membuang sisanya.

Penyaringan dinamis sangat efektif untuk:

Pencarian melalui dokumentasi teknis
Tinjauan literatur dan verifikasi kutipan
Penelitian teknis
Grounding respons dan verifikasi

Penyaringan dinamis memerlukan code execution tool untuk diaktifkan. Alat pencarian web yang ditingkatkan tersedia di Claude API dan Microsoft Azure. Di Google Vertex AI, alat pencarian web dasar (tanpa penyaringan dinamis) tersedia.

Untuk mengaktifkan penyaringan dinamis, gunakan versi alat web_search_20260209:

Cara menggunakan pencarian web

Administrator organisasi Anda harus mengaktifkan pencarian web di Claude Console.

Sediakan alat pencarian web dalam permintaan API Anda:

Definisi alat

Alat pencarian web mendukung parameter berikut:

JSON

{
  "type": "web_search_20250305",
  "name": "web_search",

  // Opsional: Batasi jumlah pencarian per permintaan
  "max_uses": 5,

  // Opsional: Hanya sertakan hasil dari domain ini
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Opsional: Jangan pernah sertakan hasil dari domain ini
  "blocked_domains": ["untrustedsource.com"],

  // Opsional: Lokalisasi hasil pencarian
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

Max uses

Parameter max_uses membatasi jumlah pencarian yang dilakukan. Jika Claude mencoba lebih banyak pencarian daripada yang diizinkan, web_search_tool_result adalah kesalahan dengan kode kesalahan max_uses_exceeded.

Penyaringan domain

Untuk penyaringan domain dengan allowed_domains dan blocked_domains, lihat Server tools.

Lokalisasi

Parameter user_location memungkinkan Anda untuk melokalisasi hasil pencarian berdasarkan lokasi pengguna.

type: Jenis lokasi (harus approximate)
city: Nama kota
region: Wilayah atau negara bagian
country: Negara
timezone: ID zona waktu IANA.

Respons

Berikut adalah contoh struktur respons:

Output

{
  "role": "assistant",
  "content": [
    // 1. Keputusan Claude untuk mencari
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. Kueri pencarian yang digunakan
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Hasil pencarian
    {
      "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. Respons Claude dengan kutipan
    {
      "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"
}

Hasil pencarian

Hasil pencarian mencakup:

url: URL halaman sumber
title: Judul halaman sumber
page_age: Kapan situs terakhir diperbarui
encrypted_content: Konten terenkripsi yang harus diteruskan kembali dalam percakapan multi-turn untuk kutipan

Kutipan

Kutipan selalu diaktifkan untuk pencarian web, dan setiap web_search_result_location mencakup:

url: URL sumber yang dikutip
title: Judul sumber yang dikutip
encrypted_index: Referensi yang harus diteruskan kembali untuk percakapan multi-turn.
cited_text: Hingga 150 karakter konten yang dikutip

Bidang kutipan pencarian web cited_text, title, dan url tidak dihitung terhadap penggunaan token input atau output.

Saat menampilkan output API secara langsung kepada pengguna akhir, kutipan harus disertakan ke sumber asli. Jika Anda membuat modifikasi pada output API, termasuk dengan memproses ulang dan/atau menggabungkannya dengan materi Anda sendiri sebelum menampilkannya kepada pengguna akhir, tampilkan kutipan sesuai kebutuhan berdasarkan konsultasi dengan tim hukum Anda.

Kesalahan

Ketika alat pencarian web mengalami kesalahan (seperti mencapai batas laju), Claude API masih mengembalikan respons 200 (sukses). Kesalahan direpresentasikan dalam badan respons menggunakan struktur berikut:

Output

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

Ini adalah kode kesalahan yang mungkin:

too_many_requests: Batas laju terlampaui
invalid_input: Parameter kueri pencarian tidak valid
max_uses_exceeded: Penggunaan alat pencarian web maksimal terlampaui
query_too_long: Kueri melebihi panjang maksimal
unavailable: Kesalahan internal terjadi

Alasan penghentian `pause_turn`

Untuk melanjutkan setelah alasan penghentian pause_turn, lihat Server tools.

Prompt caching

Untuk caching definisi alat di seluruh turn, lihat Tool use with prompt caching.

Streaming

Dengan streaming diaktifkan, Anda akan menerima peristiwa pencarian sebagai bagian dari aliran. Akan ada jeda saat pencarian dijalankan:

Output

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": ""}}

// Keputusan Claude untuk mencari

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// Kueri pencarian dialirkan
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Jeda saat pencarian dijalankan

// Hasil pencarian dialirkan
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"}]}}

// Respons Claude dengan kutipan (dihilangkan dalam contoh ini)

Permintaan batch

Anda dapat menyertakan alat pencarian web dalam Messages Batches API. Panggilan alat pencarian web melalui Messages Batches API dihargai sama dengan yang ada dalam permintaan Messages API reguler.

Penggunaan dan harga

Web search usage is charged in addition to token usage:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

Langkah berikutnya

Server tools

Mekanik bersama untuk alat yang dijalankan Anthropic.

Tool reference

Direktori semua alat yang disediakan Anthropic.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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_20260209", "name": "web_search"}],
)
print(response)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

Cara kerja pencarian web

Penyaringan dinamis

Cara menggunakan pencarian web

Definisi alat

Max uses

Penyaringan domain

Lokalisasi

Respons

Hasil pencarian

Kutipan

Kesalahan

Alasan penghentian pause_turn

Prompt caching

Streaming

Permintaan batch

Penggunaan dan harga

Langkah berikutnya

Alasan penghentian `pause_turn`