Alat pencarian web memberi Claude akses langsung ke konten web real-time, memungkinkannya menjawab pertanyaan dengan informasi terbaru di luar batas pengetahuannya. Claude secara otomatis mencantumkan 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 pada:

  • 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)

​
Bagaimana pencarian web bekerja

Ketika Anda menambahkan alat pencarian web ke permintaan API Anda:

  1. Claude memutuskan kapan harus melakukan pencarian berdasarkan prompt.
  2. API menjalankan pencarian dan memberikan Claude hasilnya. Proses ini dapat berulang beberapa kali selama 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.

Sediakan 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": "How do I update a web app to 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"
  }
}

​
Penggunaan maksimum

Parameter max_uses membatasi jumlah pencarian yang dilakukan. Jika Claude mencoba melakukan pencarian lebih dari yang diizinkan, web_search_tool_result akan berupa error dengan kode error max_uses_exceeded.

​
Pemfilteran domain

Saat menggunakan filter domain:

  • Domain tidak boleh menyertakan skema HTTP/HTTPS (gunakan example.com bukan 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": "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 sebagai penggunaan token input atau output.

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

​
Error

Jika terjadi error selama pencarian web, Anda akan menerima respons dalam bentuk 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 rate terlampaui
  • invalid_input: Parameter kueri pencarian tidak valid
  • max_uses_exceeded: Penggunaan alat pencarian web maksimum terlampaui
  • query_too_long: Kueri melebihi panjang maksimum
  • unavailable: Terjadi error internal

​
Alasan berhenti pause_turn

Respons mungkin menyertakan alasan berhenti 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.

​
Caching prompt

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

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

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

import anthropic

client = anthropic.Anthropic()

# Permintaan pertama dengan pencarian web dan titik henti cache
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

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 titik henti cache setelah hasil pencarian
messages.append({
    "role": "user",
    "content": "Should I expect rain later this week?",
    "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"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

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

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 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 dijalankan

// 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 API Messages Batches. Panggilan alat pencarian web melalui API Messages Batches dihargai sama dengan yang ada dalam permintaan API Messages biasa.

​
Penggunaan dan harga

Penggunaan pencarian web dikenakan biaya selain 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 API Anthropic seharga $10 per 1.000 pencarian, ditambah biaya token standar untuk konten yang dihasilkan dari pencarian. Hasil pencarian web yang diambil selama percakapan dihitung sebagai token input, dalam iterasi pencarian yang dijalankan selama satu giliran dan dalam giliran percakapan berikutnya.

Setiap pencarian web dihitung sebagai satu penggunaan, terlepas dari jumlah hasil yang dikembalikan. Jika terjadi error selama pencarian web, pencarian web tidak akan ditagih.