Alat web fetch

Alat pengambilan web

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

Versi alat web fetch terbaru (web_fetch_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 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 penyaringan dinamis.

Untuk Claude Mythos Preview, web fetch didukung di Claude API dan Microsoft Foundry saja. Tidak tersedia untuk Mythos Preview di Amazon Bedrock atau Google Vertex AI.

Gunakan formulir umpan balik untuk memberikan umpan balik tentang kualitas respons model, API itu sendiri, atau kualitas dokumentasi.

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

Mengaktifkan alat web fetch di lingkungan di mana Claude memproses input yang tidak terpercaya bersama data sensitif menimbulkan risiko eksfiltrasi data. Hanya gunakan alat ini di lingkungan terpercaya atau saat menangani data non-sensitif.

Untuk meminimalkan risiko eksfiltrasi, Claude tidak diizinkan untuk secara dinamis membangun URL. Claude hanya dapat mengambil URL yang telah secara eksplisit disediakan oleh pengguna atau yang berasal dari hasil pencarian web atau web fetch sebelumnya. Namun, masih ada risiko sisa yang harus dipertimbangkan dengan hati-hati saat menggunakan alat ini.

Jika eksfiltrasi data menjadi perhatian, pertimbangkan:

Menonaktifkan alat web fetch sepenuhnya
Menggunakan parameter max_uses untuk membatasi jumlah permintaan
Menggunakan parameter allowed_domains untuk membatasi ke domain yang dikenal aman

Untuk dukungan model, lihat Tool reference.

Cara kerja web fetch

Saat Anda menambahkan alat web fetch ke permintaan API Anda:

Claude memutuskan kapan harus mengambil konten berdasarkan prompt dan URL yang tersedia.
API mengambil konten teks lengkap dari URL yang ditentukan.
Untuk PDF, ekstraksi teks otomatis dilakukan.
Claude menganalisis konten yang diambil dan memberikan respons dengan kutipan opsional.

Alat web fetch saat ini tidak mendukung situs web yang dirender secara dinamis melalui JavaScript.

Penyaringan dinamis

Mengambil halaman web dan PDF lengkap dapat dengan cepat mengonsumsi token, terutama ketika hanya informasi spesifik yang diperlukan dari dokumen besar. Dengan versi alat web_fetch_20260209, Claude dapat menulis dan menjalankan kode untuk menyaring konten yang diambil sebelum memuatnya ke dalam konteks.

Penyaringan dinamis ini sangat berguna untuk:

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

Penyaringan dinamis memerlukan alat eksekusi kode untuk diaktifkan. Alat web fetch (dengan dan tanpa penyaringan dinamis) tersedia di Claude API dan Microsoft Azure.

Untuk mengaktifkan penyaringan dinamis, gunakan versi alat web_fetch_20260209:

Cara menggunakan web fetch

Sediakan alat web fetch dalam permintaan API Anda:

Definisi alat

Alat web fetch mendukung parameter berikut:

JSON

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

  // Opsional: Batasi jumlah pengambilan per permintaan
  "max_uses": 10,

  // Opsional: Hanya ambil dari domain ini
  "allowed_domains": ["example.com", "docs.example.com"],

  // Opsional: Jangan pernah ambil dari domain ini
  "blocked_domains": ["private.example.com"],

  // Opsional: Aktifkan kutipan untuk konten yang diambil
  "citations": {
    "enabled": true
  },

  // Opsional: Panjang konten maksimum dalam token
  "max_content_tokens": 100000
}

Penggunaan maksimal

Parameter max_uses membatasi jumlah pengambilan web yang dilakukan. Jika Claude mencoba lebih banyak pengambilan daripada yang diizinkan, web_fetch_tool_result adalah kesalahan dengan kode kesalahan max_uses_exceeded. Saat ini tidak ada batas default.

Penyaringan domain

Untuk penyaringan 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 parameter max_content_tokens bersifat perkiraan. Jumlah token input aktual yang digunakan dapat bervariasi dalam jumlah kecil.

Kutipan

Tidak seperti pencarian web di mana kutipan selalu diaktifkan, kutipan bersifat opsional untuk web fetch. Atur "citations": {"enabled": true} untuk memungkinkan Claude mengutip bagian tertentu dari dokumen yang diambil.

Saat menampilkan output API 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.

Respons

Berikut adalah contoh struktur respons:

Output

{
  "role": "assistant",
  "content": [
    // 1. Keputusan Claude untuk mengambil
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. Permintaan pengambilan
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Hasil pengambilan
    {
      "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. Analisis Claude dengan kutipan (jika diaktifkan)
    {
      "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 pengambilan

Hasil pengambilan mencakup:

url: URL yang diambil
content: Blok dokumen yang berisi konten yang diambil
retrieved_at: Stempel waktu saat konten diambil

Alat web fetch menyimpan hasil dalam cache untuk meningkatkan kinerja dan mengurangi permintaan yang berlebihan. Konten yang dikembalikan mungkin tidak selalu mencerminkan versi terbaru yang tersedia di URL. Perilaku cache dikelola secara otomatis dan dapat berubah seiring waktu untuk mengoptimalkan berbagai jenis konten dan pola penggunaan.

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

Output

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

Kesalahan

Ketika alat web fetch mengalami kesalahan, Claude API mengembalikan respons 200 (sukses) dengan kesalahan yang diwakili dalam badan respons:

Output

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

Ini adalah kode kesalahan yang mungkin:

invalid_input: Format URL tidak valid
url_too_long: URL melebihi panjang maksimum (250 karakter)
url_not_allowed: URL diblokir oleh aturan penyaringan domain dan pembatasan model
url_not_accessible: Gagal mengambil konten (kesalahan HTTP)
too_many_requests: Batas laju terlampaui
unsupported_content_type: Jenis konten tidak didukung (hanya teks dan PDF)
max_uses_exceeded: Penggunaan alat web fetch maksimum terlampaui
unavailable: Kesalahan internal terjadi

Validasi URL

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

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

Alat tidak dapat mengambil URL arbitrer yang dihasilkan Claude atau URL dari alat server berbasis kontainer (Code Execution, Bash, dll.).

Pencarian dan pengambilan gabungan

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

Python

client = anthropic.Anthropic()

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

Dalam alur kerja ini, Claude akan:

Menggunakan pencarian web untuk menemukan artikel yang relevan
Memilih hasil yang paling menjanjikan
Menggunakan web fetch untuk mengambil konten lengkap
Memberikan analisis terperinci dengan kutipan

Penyimpanan cache prompt

Untuk menyimpan definisi alat dalam cache di seluruh putaran, lihat Tool use with prompt caching.

Streaming

Dengan streaming diaktifkan, acara pengambilan adalah bagian dari aliran dengan jeda selama pengambilan konten:

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

// 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 memiliki harga yang sama dengan permintaan Messages API biasa.

Penggunaan dan harga

Web fetch usage has no additional charges beyond standard token costs:

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

The web fetch tool is available on the Claude API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

Average web page (10 kB): ~2,500 tokens
Large documentation page (100 kB): ~25,000 tokens
Research paper PDF (500 kB): ~125,000 tokens

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": "Fetch the content at https://example.com/research-paper and extract the key findings.",
        }
    ],
    tools=[{"type": "web_fetch_20260209", "name": "web_fetch"}],
)
print(response)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)