Alat pencarian web memberikan Claude akses langsung ke konten web real-time, memungkinkannya menjawab pertanyaan dengan informasi terkini melampaui batas pengetahuannya. Claude secara otomatis mengutip sumber dari hasil pencarian sebagai bagian dari jawabannya.

Silakan hubungi kami melalui formulir umpan balik untuk berbagi pengalaman Anda dengan alat pencarian web.

​
Model yang didukung

Pencarian web tersedia di:

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (baru) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Cara kerja pencarian web

Ketika Anda menambahkan alat pencarian web ke permintaan API Anda:

  1. Claude memutuskan kapan harus mencari berdasarkan prompt.
  2. API mengeksekusi pencarian dan memberikan Claude hasil-hasilnya. Proses ini mungkin berulang beberapa kali sepanjang satu permintaan.
  3. Di akhir gilirannya, Claude memberikan respons akhir dengan sumber yang dikutip.

​
Cara menggunakan pencarian web

Administrator organisasi Anda harus mengaktifkan pencarian web di Console.

Berikan alat pencarian web dalam permintaan API Anda:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Bagaimana cara memperbarui aplikasi web ke TypeScript 5.5?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
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 dari yang diizinkan, web_search_tool_result akan menjadi error dengan kode error max_uses_exceeded.

​
Penyaringan domain

Ketika menggunakan filter domain:

  • Domain tidak boleh menyertakan skema HTTP/HTTPS (gunakan example.com alih-alih https://example.com)
  • Subdomain secara otomatis disertakan (example.com mencakup docs.example.com)
  • Subpath didukung (example.com/blog)
  • Anda dapat menggunakan allowed_domains atau blocked_domains, tetapi tidak keduanya dalam permintaan yang sama.

​
Lokalisasi

Parameter user_location memungkinkan Anda 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:

{
  "role": "assistant",
  "content": [
    // 1. Keputusan Claude untuk mencari
    {
      "type": "text",
      "text": "Saya akan mencari kapan Claude Shannon lahir."
    },
    // 2. Query 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": "Berdasarkan hasil pencarian, ",
      "type": "text"
    },
    // 4. Respons Claude dengan kutipan
    {
      "text": "Claude Shannon lahir pada 30 April 1916, di 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 meliputi:

  • 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 meliputi:

  • 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 dari konten yang dikutip

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

Ketika menampilkan hasil web atau informasi yang terkandung dalam hasil web kepada pengguna akhir, kutipan inline harus dibuat terlihat jelas dan dapat diklik dalam antarmuka pengguna Anda.

​
Error

Jika terjadi error selama pencarian web, Anda akan menerima respons yang berbentuk sebagai berikut:

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

Berikut adalah kode error yang mungkin:

  • too_many_requests: Batas laju terlampaui
  • invalid_input: Parameter query pencarian tidak valid
  • max_uses_exceeded: Penggunaan alat pencarian web maksimum terlampaui
  • query_too_long: Query melebihi panjang maksimum
  • unavailable: Terjadi error internal

​
Alasan stop pause_turn

Respons mungkin menyertakan alasan stop pause_turn, yang menunjukkan bahwa API menjeda giliran yang berjalan lama. Anda dapat memberikan respons kembali apa adanya dalam permintaan berikutnya untuk membiarkan Claude melanjutkan gilirannya, atau memodifikasi konten jika Anda ingin mengganggu percakapan.

​
Prompt caching

Pencarian web bekerja dengan prompt caching. Untuk mengaktifkan prompt caching, tambahkan setidaknya satu breakpoint cache_control dalam permintaan Anda. Sistem akan secara otomatis menyimpan cache hingga blok web_search_tool_result terakhir ketika mengeksekusi alat.

Untuk percakapan multi-turn, atur breakpoint cache_control pada atau setelah blok web_search_tool_result terakhir untuk menggunakan kembali konten yang di-cache.

Misalnya, untuk menggunakan prompt caching dengan pencarian web untuk percakapan multi-turn:

import anthropic

client = anthropic.Anthropic()

# Permintaan pertama dengan pencarian web dan breakpoint cache
messages = [
    {
        "role": "user",
        "content": "Bagaimana cuaca saat ini di San Francisco hari ini?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# Tambahkan respons Claude ke percakapan
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Permintaan kedua dengan breakpoint cache setelah hasil pencarian
messages.append({
    "role": "user",
    "content": "Apakah saya harus mengharapkan hujan akhir minggu ini?",
    "cache_control": {"type": "ephemeral"}  # Cache hingga titik ini
})

response2 = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# Respons kedua akan mendapat manfaat dari hasil pencarian yang di-cache
# sambil tetap dapat melakukan pencarian baru jika diperlukan
print(f"Token baca cache: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

Dengan streaming diaktifkan, Anda akan menerima event pencarian sebagai bagian dari stream. Akan ada jeda saat pencarian dieksekusi:

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

// Query pencarian di-stream
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 dieksekusi

// Hasil pencarian di-stream
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 biasa.

​
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 Anthropic 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.