Strumento web fetch

Lo strumento web fetch consente a Claude di recuperare il contenuto completo da pagine web e documenti PDF specificati.

La versione più recente dello strumento web fetch (web_fetch_20260318) supporta il filtraggio dinamico con Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6. Claude può scrivere ed eseguire codice per filtrare il contenuto recuperato prima che raggiunga la "context window" (finestra di contesto), mantenendo solo le informazioni rilevanti e scartando il resto. Questo riduce il consumo di token mantenendo la qualità della risposta. web_fetch_20260318 aggiunge anche il controllo di inclusione della risposta per i flussi di lavoro agentici. Le versioni precedenti (web_fetch_20260309 per il filtraggio dinamico e il bypass della cache, web_fetch_20260209 solo per il filtraggio dinamico, web_fetch_20250910 per il fetch di base) rimangono disponibili.

Web fetch (con e senza filtraggio dinamico) è disponibile sulla Claude API, Claude Platform su AWS e Microsoft Foundry. Su Microsoft Foundry, web fetch richiede una distribuzione Hosted on Anthropic. Attualmente non è disponibile su Amazon Bedrock o Google Cloud.

Per l'idoneità a Zero Data Retention e la soluzione alternativa allowed_callers, consulta Strumenti server.

Per il supporto dei modelli, consulta il Riferimento degli strumenti.



Come funziona web fetch

Web fetch è uno strumento server: l'API recupera il contenuto durante la richiesta e inserisce i risultati nella conversazione. Non devi eseguire nulla né restituire un tool_result. L'eccezione si verifica quando Claude chiama web fetch e uno dei tuoi strumenti client nello stesso gruppo di chiamate parallele agli strumenti: l'API restituisce la risposta con stop_reason: "tool_use" prima che quel fetch sia stato eseguito, quindi esegue il fetch quando invii i blocchi tool_result del client. Consulta Combinare strumenti server e strumenti client in un unico turno.

Quando aggiungi lo strumento web fetch alla tua richiesta API:

1. Claude decide quando recuperare contenuti in base al prompt e agli URL disponibili.
2. L'API recupera il contenuto testuale completo dall'URL specificato.
3. Per i PDF, l'API restituisce il contenuto come dati codificati in base64 e lo elabora come un documento PDF allegato direttamente.
4. Claude analizza il contenuto recuperato e fornisce una risposta con citazioni opzionali.



Quando Claude esegue il fetch

Claude esegue il fetch quando la richiesta punta a una pagina o un documento specifico:

• Un URL è fornito nella conversazione (o in un risultato precedente di uno strumento)
• L'utente nomina una risorsa specifica (un particolare articolo, README, pagina dei prezzi o sezione di documentazione) senza un URL, e lo strumento web search è anch'esso abilitato in modo che Claude possa prima localizzarla (consulta Ricerca e fetch combinati)

Claude non esegue il fetch per domande di conoscenza generale o aperte che non fanno riferimento a una pagina specifica. "Riassumi questo articolo: <url>" attiva un fetch. "Quali sono le best practice per la progettazione di API REST?" riceve una risposta diretta.



Filtraggio dinamico

Recuperare pagine web e PDF completi può consumare rapidamente token, specialmente quando sono necessarie solo informazioni specifiche da documenti di grandi dimensioni. Con web_fetch_20260209 o versioni successive, Claude può scrivere ed eseguire codice per filtrare il contenuto recuperato prima di caricarlo nel contesto.

Questo filtraggio dinamico è particolarmente utile per:

• Estrarre sezioni specifiche da documenti lunghi
• Elaborare dati strutturati da pagine web
• Filtrare informazioni rilevanti dai PDF
• Ridurre i costi in token quando si lavora con documenti di grandi dimensioni

Per abilitare il filtraggio dinamico, usa web_fetch_20260209 o qualsiasi versione successiva. Gli esempi seguenti usano 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)



Come usare web fetch

Fornisci lo strumento web fetch nella tua richiesta API:

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)



Definizione dello strumento

Lo strumento web fetch supporta i seguenti parametri:

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

Le versioni successive dello strumento aggiungono altri due parametri opzionali: use_cache richiede web_fetch_20260309 o versioni successive (consulta Bypass della cache), e response_inclusion richiede web_fetch_20260318 o versioni successive (consulta Inclusione della risposta).



Utilizzi massimi

Il parametro max_uses limita il numero di web fetch eseguiti. I fetch non riusciti vengono conteggiati nel limite. Se Claude tenta più fetch di quelli consentiti, il web_fetch_tool_result è un errore con il codice di errore max_uses_exceeded. Attualmente non esiste un limite predefinito.



Filtraggio dei domini

Per il filtraggio dei domini con allowed_domains e blocked_domains, consulta Strumenti server.



Limiti di contenuto

Il parametro max_content_tokens limita la quantità di contenuto inclusa nel contesto. Se il contenuto recuperato supera questo limite, lo strumento lo tronca. Questo aiuta a controllare l'utilizzo dei token quando si recuperano documenti di grandi dimensioni. Il limite si applica al contenuto testuale, non al contenuto binario come i PDF.



Bypass della cache

Il parametro use_cache controlla se può essere restituito contenuto memorizzato nella cache. Imposta "use_cache": false per bypassare la cache e recuperare contenuto aggiornato. Il valore predefinito è true. Disabilita la cache solo quando l'utente richiede esplicitamente contenuto aggiornato o quando recuperi fonti che cambiano rapidamente, perché bypassare la cache aumenta la "latency" (latenza).

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



Inclusione della risposta

Il parametro response_inclusion controlla come i blocchi di risultato del fetch appaiono nella risposta dell'API quando il risultato è stato consumato da una chiamata di esecuzione del codice completata nello stesso turno. Imposta "response_inclusion": "excluded" per eliminare completamente dalla risposta quelle coppie annidate di blocchi server_tool_use e di risultato, riducendo i costi dei token di output per i flussi di lavoro agentici che non hanno bisogno di restituire al client il contenuto grezzo della pagina. Il valore predefinito è "full". I risultati provenienti da chiamate dirette, o da chiamate di esecuzione del codice che si sono interrotte prima del completamento, vengono sempre restituiti per intero in modo da poter essere inviati nuovamente al turno successivo.

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



Citazioni

A differenza di web search, dove le citazioni sono sempre abilitate, le citazioni sono opzionali per web fetch e disabilitate per impostazione predefinita. Imposta "citations": {"enabled": true} per consentire a Claude di citare passaggi specifici dai documenti recuperati.



Risposta

Ecco un esempio di struttura della risposta:

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



Risultati del fetch

I risultati del fetch includono:

• url: L'URL che è stato recuperato
• content: Un blocco documento contenente il contenuto recuperato
• retrieved_at: Timestamp di quando il contenuto è stato recuperato

Per i documenti PDF, il contenuto viene restituito come dati codificati in 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"
  }
}



Errori

Quando lo strumento web fetch incontra un errore, la Claude API restituisce una risposta 200 (successo) con l'errore rappresentato nel corpo della risposta. Claude vede il risultato di errore e continua il turno. Ad esempio:

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

Questi sono i possibili codici di errore:

• invalid_tool_input: Input dello strumento non valido, come un URL malformato o uno schema non HTTP(S)
• url_too_long: L'URL supera la lunghezza massima (250 caratteri)
• url_not_allowed: URL bloccato dalle regole di filtraggio dei domini (incluse le impostazioni della tua organizzazione) o da restrizioni lato Anthropic, come indirizzi privati e robots.txt
• url_not_in_prior_context: L'URL non è apparso in precedenza nella conversazione (consulta Validazione degli URL)
• url_not_accessible: Impossibile recuperare il contenuto (errore HTTP)
• too_many_requests: Limite di velocità superato
• unsupported_content_type: Tipo di contenuto non supportato (solo testo, HTML e PDF)
• max_uses_exceeded: Numero massimo di utilizzi dello strumento web fetch superato
• unavailable: Si è verificato un errore interno



Validazione degli URL

Per motivi di sicurezza, lo strumento web fetch può recuperare solo URL che sono apparsi in precedenza nel contesto della conversazione. Questo include:

• URL nei messaggi dell'utente
• URL nei risultati degli strumenti lato client
• URL da risultati precedenti di web search o web fetch

Lo strumento non può recuperare URL arbitrari generati da Claude o URL provenienti da strumenti server basati su container (Code Execution, Bash, ecc.).



Ricerca e fetch combinati

Quando sia lo strumento web search che lo strumento web fetch sono abilitati, e l'utente nomina una pagina o un documento specifico senza fornire un URL (ad esempio, "leggi il README dal repository anthropics/anthropic-sdk-python"), Claude usa web search per localizzarlo, quindi recupera il risultato. L'esempio seguente richiede una ricerca e un'analisi in un'unica richiesta:

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)

In questo flusso di lavoro, Claude:

1. Usa web search per trovare articoli rilevanti.
2. Seleziona i risultati più promettenti.
3. Usa web fetch per recuperare il contenuto completo.
4. Fornisce un'analisi dettagliata con citazioni.



Cache dei prompt

Per memorizzare nella cache le definizioni degli strumenti tra i turni, consulta Uso degli strumenti con la cache dei prompt.



Streaming

Con lo streaming abilitato, gli eventi di fetch fanno parte dello stream con una pausa durante il recupero del contenuto:

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



Richieste batch

Puoi includere lo strumento web fetch nella Messages Batches API. Le chiamate allo strumento web fetch tramite la Messages Batches API hanno lo stesso prezzo di quelle nelle normali richieste della Messages API.



Utilizzo e prezzi

L'utilizzo di web fetch non comporta alcun costo aggiuntivo oltre ai costi standard dei token:

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

Lo strumento web fetch è disponibile sull'API di Claude senza costi aggiuntivi. Paghi solo i costi standard dei token per il contenuto recuperato che diventa parte del contesto della tua conversazione.

Per proteggerti dal recupero involontario di contenuti di grandi dimensioni che consumerebbero un numero eccessivo di token, usa il parametro max_content_tokens per impostare limiti appropriati in base al tuo caso d'uso e alle tue considerazioni di budget.

Esempio di utilizzo di token per contenuti tipici:

• Pagina web media (10 kB): ~2.500 token
• Pagina di documentazione di grandi dimensioni (100 kB): ~25.000 token
• PDF di un articolo di ricerca (500 kB): ~125.000 token



Passaggi successivi