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_20260209) 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, dan Claude Sonnet 4.6. Claude dapat menulis dan mengeksekusi kode untuk memfilter konten yang diambil sebelum mencapai jendela konteks, hanya menyimpan informasi yang relevan dan membuang sisanya. Ini mengurangi konsumsi token sambil mempertahankan kualitas respons. Versi alat sebelumnya (web_fetch_20250910) tetap tersedia tanpa pemfilteran dinamis.

Untuk kelayakan Zero Data Retention dan solusi allowed_callers, lihat Alat server.

Untuk dukungan model, lihat Referensi alat.



Cara kerja web fetch

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, ekstraksi teks otomatis dilakukan.
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 versi alat web_fetch_20260209, 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 versi alat 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
  "blocked_domains": ["private.example.com"],

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

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



Max uses

Parameter max_uses membatasi jumlah web fetch yang dilakukan. Jika Claude mencoba lebih banyak fetch dari 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 Alat server.



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.



Sitasi

Tidak seperti web search di mana sitasi selalu diaktifkan, sitasi bersifat opsional untuk web fetch. 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:

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

Berikut adalah kode error yang mungkin terjadi:

• invalid_input: Format URL tidak valid
• url_too_long: URL melebihi panjang maksimum (250 karakter)
• url_not_allowed: URL diblokir oleh aturan pemfilteran domain dan pembatasan model
• url_not_accessible: Gagal mengambil konten (error HTTP)
• too_many_requests: Batas laju terlampaui
• unsupported_content_type: Jenis konten tidak didukung (hanya teks 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 alat server berbasis container (Code Execution, Bash, dll.).



Gabungan search dan fetch

Web fetch bekerja secara mulus dengan web search untuk pengumpulan informasi yang komprehensif:

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 akan:

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

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 melakukan fetch pada hasilnya.



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