Alat web fetch

Alat web fetch memungkinkan Claude mengambil konten lengkap dari halaman web dan dokumen PDF yang ditentukan.

Versi alat web fetch terbaru (web_fetch_20260318) mendukung dynamic filtering (pemfilteran dinamis) dengan Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, dan Claude Sonnet 4.6. Claude dapat menulis dan mengeksekusi kode untuk memfilter konten yang diambil sebelum masuk ke jendela konteks, hanya menyimpan informasi yang relevan dan membuang sisanya. Ini mengurangi konsumsi token sambil mempertahankan kualitas respons. web_fetch_20260318 juga menambahkan kontrol penyertaan respons untuk alur kerja agentik. Versi sebelumnya (web_fetch_20260309 untuk pemfilteran dinamis dan cache bypass, web_fetch_20260209 untuk pemfilteran dinamis saja, web_fetch_20250910 untuk fetch dasar) tetap tersedia.

Web fetch (dengan dan tanpa pemfilteran dinamis) tersedia di Claude API, Claude Platform di AWS, dan Microsoft Foundry. Di Microsoft Foundry, web fetch memerlukan deployment Hosted on Anthropic. Saat ini tidak tersedia di Amazon Bedrock atau Google Cloud.

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

Untuk dukungan model, lihat Referensi alat.



Cara kerja web fetch

Web fetch adalah server tool (alat server): API mengambil konten selama permintaan dan menyisipkan hasilnya ke dalam percakapan. Anda tidak perlu menjalankan apa pun atau mengembalikan tool_result. Pengecualiannya adalah ketika Claude memanggil web fetch dan salah satu alat klien Anda dalam grup panggilan alat paralel yang sama: API mengembalikan respons dengan stop_reason: "tool_use" sebelum fetch tersebut dijalankan, kemudian menjalankan fetch saat Anda mengirim kembali blok tool_result klien. Lihat Menggabungkan server tools dan client tools dalam satu giliran.

Saat Anda menambahkan alat web fetch ke permintaan API Anda:

1. Claude memutuskan kapan harus mengambil konten berdasarkan prompt dan URL yang tersedia.
2. API mengambil konten teks lengkap dari URL yang ditentukan.
3. Untuk PDF, API mengembalikan konten sebagai data yang dikodekan base64 dan memprosesnya seperti dokumen PDF yang dilampirkan langsung.
4. Claude menganalisis konten yang diambil dan memberikan respons dengan sitasi opsional.



Kapan Claude melakukan fetch

Claude melakukan fetch ketika permintaan mengarah ke halaman atau dokumen tertentu:

• URL disediakan dalam percakapan (atau hasil alat sebelumnya)
• Pengguna menyebutkan sumber daya tertentu (artikel tertentu, README, halaman harga, atau bagian dokumentasi) tanpa URL, dan alat web search juga diaktifkan sehingga Claude dapat menemukannya terlebih dahulu (lihat Gabungan search dan fetch)

Claude tidak melakukan fetch untuk pertanyaan pengetahuan umum atau pertanyaan terbuka yang tidak merujuk ke halaman tertentu. "Ringkas artikel ini: <url>" memicu fetch. "Apa praktik terbaik untuk desain REST API?" dijawab secara langsung.



Pemfilteran dinamis

Mengambil halaman web dan PDF lengkap dapat dengan cepat menghabiskan token, terutama ketika hanya informasi tertentu yang dibutuhkan dari dokumen besar. Dengan web_fetch_20260209 atau yang lebih baru, Claude dapat menulis dan mengeksekusi kode untuk memfilter konten yang diambil sebelum memuatnya ke dalam konteks.

Pemfilteran dinamis ini sangat berguna untuk:

• Mengekstrak bagian tertentu dari dokumen panjang
• Memproses data terstruktur dari halaman web
• Memfilter informasi relevan dari PDF
• Mengurangi biaya token saat bekerja dengan dokumen besar

Untuk mengaktifkan pemfilteran dinamis, gunakan web_fetch_20260209 atau versi yang lebih baru. Contoh berikut menggunakan web_fetch_20260209:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Fetch the content at https://example.com/research-paper and extract the key findings.",
        }
    ],
    tools=[{"type": "web_fetch_20260209", "name": "web_fetch"}],
)
print(response)



Cara menggunakan web fetch

Sediakan alat web fetch dalam permintaan API Anda:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Please analyze the content at https://example.com/article",
        }
    ],
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}],
)
print(response)



Definisi alat

Alat web fetch mendukung parameter berikut:

{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Optional: Limit the number of fetches per request
  "max_uses": 10,

  // Optional: Only fetch from these domains
  "allowed_domains": ["example.com", "docs.example.com"],

  // Optional: Never fetch from these domains (cannot be combined with allowed_domains)
  "blocked_domains": ["private.example.com"],

  // Optional: Enable citations for fetched content
  "citations": {
    "enabled": true
  },

  // Optional: Maximum content length in tokens
  "max_content_tokens": 100000
}

Versi alat yang lebih baru menambahkan dua parameter opsional lagi: use_cache memerlukan web_fetch_20260309 atau yang lebih baru (lihat Cache bypass), dan response_inclusion memerlukan web_fetch_20260318 atau yang lebih baru (lihat Penyertaan respons).



Max uses

Parameter max_uses membatasi jumlah web fetch yang dilakukan. Fetch yang gagal tetap dihitung terhadap batas ini. Jika Claude mencoba lebih banyak fetch daripada yang diizinkan, web_fetch_tool_result akan berupa error dengan kode error max_uses_exceeded. Saat ini tidak ada batas default.



Pemfilteran domain

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



Batas konten

Parameter max_content_tokens membatasi jumlah konten yang disertakan dalam konteks. Jika konten yang diambil melebihi batas ini, alat akan memotongnya. Ini membantu mengontrol penggunaan token saat mengambil dokumen besar. Batas ini berlaku untuk konten teks, bukan untuk konten biner seperti PDF.



Cache bypass

Parameter use_cache mengontrol apakah konten yang di-cache dapat dikembalikan. Atur "use_cache": false untuk melewati cache dan mengambil konten terbaru. Nilai default adalah true. Hanya nonaktifkan caching ketika pengguna secara eksplisit meminta konten terbaru atau saat mengambil sumber yang berubah dengan cepat, karena melewati cache akan meningkatkan latensi.

{
  "tools": [
    {
      "type": "web_fetch_20260309",
      "name": "web_fetch",
      "use_cache": false
    }
  ]
}



Penyertaan respons

Parameter response_inclusion mengontrol bagaimana blok hasil fetch muncul dalam respons API ketika hasil tersebut dikonsumsi oleh panggilan code execution yang telah selesai dalam giliran yang sama. Atur "response_inclusion": "excluded" untuk menghapus pasangan blok server_tool_use dan blok hasil yang bersarang tersebut sepenuhnya dari respons, sehingga mengurangi biaya token output untuk alur kerja agentik yang tidak perlu mengirim kembali konten halaman mentah ke klien. Nilai default adalah "full". Hasil dari panggilan langsung, atau dari panggilan code execution yang dijeda sebelum selesai, selalu dikembalikan secara penuh sehingga dapat dikirim kembali pada giliran berikutnya.

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "response_inclusion": "excluded"
    }
  ]
}



Sitasi

Tidak seperti web search di mana sitasi selalu diaktifkan, sitasi bersifat opsional untuk web fetch dan dinonaktifkan secara default. Atur "citations": {"enabled": true} untuk memungkinkan Claude mengutip bagian tertentu dari dokumen yang diambil.



Respons

Berikut adalah contoh struktur respons:

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to fetch
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. The fetch request
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Fetch results
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01234567890abcdef",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          },
          "title": "Article Title",
          "citations": { "enabled": true }
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Claude's analysis with citations (if enabled)
    {
      "text": "Based on the article, ",
      "type": "text"
    },
    {
      "text": "the main argument presented is that artificial intelligence will transform healthcare",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Article Title",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  },
  "stop_reason": "end_turn"
}



Hasil fetch

Hasil fetch mencakup:

• url: URL yang diambil
• content: Blok dokumen yang berisi konten yang diambil
• retrieved_at: Timestamp saat konten diambil

Untuk dokumen PDF, konten dikembalikan sebagai data yang dikodekan base64:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_02",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/paper.pdf",
    "content": {
      "type": "document",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
      },
      "citations": { "enabled": true }
    },
    "retrieved_at": "2025-08-25T10:30:02Z"
  }
}



Error

Ketika alat web fetch mengalami error, Claude API mengembalikan respons 200 (sukses) dengan error yang direpresentasikan dalam body respons. Claude melihat hasil error tersebut dan melanjutkan gilirannya. Contohnya:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_result_error",
    "error_code": "url_not_accessible"
  }
}

Berikut adalah kode error yang mungkin muncul:

• invalid_tool_input: Input alat tidak valid, seperti URL yang salah format atau skema non-HTTP(S)
• url_too_long: URL melebihi panjang maksimum (250 karakter)
• url_not_allowed: URL diblokir oleh aturan pemfilteran domain (termasuk pengaturan organisasi Anda) atau oleh pembatasan di sisi Anthropic, seperti alamat privat dan robots.txt
• url_not_in_prior_context: URL tidak muncul sebelumnya dalam percakapan (lihat Validasi URL)
• url_not_accessible: Gagal mengambil konten (error HTTP)
• too_many_requests: Batas laju terlampaui
• unsupported_content_type: Jenis konten tidak didukung (hanya teks, HTML, dan PDF)
• max_uses_exceeded: Penggunaan maksimum alat web fetch terlampaui
• unavailable: Terjadi error internal



Validasi URL

Untuk alasan keamanan, alat web fetch hanya dapat mengambil URL yang sebelumnya telah muncul dalam konteks percakapan. Ini mencakup:

• URL dalam pesan pengguna
• URL dalam hasil alat sisi klien
• URL dari hasil web search atau web fetch sebelumnya

Alat ini tidak dapat mengambil URL sembarang yang dihasilkan Claude atau URL dari server tools berbasis container (Code Execution, Bash, dll.).



Gabungan search dan fetch

Ketika alat web search dan web fetch keduanya diaktifkan, dan pengguna menyebutkan halaman atau dokumen tertentu tanpa memberikan URL (misalnya, "baca README dari repositori anthropics/anthropic-sdk-python"), Claude menggunakan web search untuk menemukannya, lalu mengambil hasilnya. Contoh berikut meminta pencarian dan analisis dalam satu permintaan:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Find recent articles about quantum computing and analyze the most relevant one in detail",
        }
    ],
    tools=[
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
        {
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5,
            "citations": {"enabled": True},
        },
    ],
)
print(response)

Dalam alur kerja ini, Claude:

1. Menggunakan web search untuk menemukan artikel yang relevan.
2. Memilih hasil yang paling menjanjikan.
3. Menggunakan web fetch untuk mengambil konten lengkap.
4. Memberikan analisis terperinci dengan sitasi.



Caching prompt

Untuk melakukan caching definisi alat di seluruh giliran, lihat Penggunaan alat dengan caching prompt.



Streaming

Dengan streaming diaktifkan, event fetch menjadi bagian dari stream dengan jeda selama pengambilan konten:

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 fetch

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

// Fetch URL streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Pause while fetch executes

// Fetch results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}}

// Claude's response continues...



Permintaan batch

Anda dapat menyertakan alat web fetch dalam Messages Batches API. Panggilan alat web fetch melalui Messages Batches API dikenakan harga yang sama dengan panggilan dalam permintaan Messages API reguler.



Penggunaan dan harga

Penggunaan web fetch tidak dikenakan biaya tambahan di luar biaya token standar:

{
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}

Alat web fetch tersedia di Claude API tanpa biaya tambahan. Anda hanya membayar biaya token standar untuk konten yang diambil dan menjadi bagian dari konteks percakapan Anda.

Untuk melindungi dari pengambilan konten berukuran besar secara tidak sengaja yang akan menghabiskan token secara berlebihan, gunakan parameter max_content_tokens untuk menetapkan batas yang sesuai berdasarkan kasus penggunaan dan pertimbangan anggaran Anda.

Contoh penggunaan token untuk konten umum:

• Halaman web rata-rata (10 kB): ~2.500 token
• Halaman dokumentasi besar (100 kB): ~25.000 token
• PDF makalah penelitian (500 kB): ~125.000 token



Langkah selanjutnya