Strumento web fetch
Recupera e leggi contenuti da URL specifici per arricchire il contesto di Claude con contenuti web in tempo reale.
L’utilizzo varia in base al prodotto
web_fetch ai tools della richiesta.max_uses, citations o cache_control.Lo strumento di web fetch consente a Claude di recuperare il contenuto completo da pagine web e documenti PDF specificati.
L’ultima versione dello strumento di web fetch (web_fetch_20260318) supporta il dynamic filtering (filtraggio dinamico): 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à delle risposte. Il filtraggio dinamico è disponibile con Claude 4.6 e modelli successivi e con Claude Mythos Preview. web_fetch_20260318 aggiunge inoltre il controllo dell’inclusione nella risposta per i flussi di lavoro agentici. Le altre versioni (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) sono disponibili.
Il web fetch (con e senza filtraggio dinamico) è disponibile sulla Claude API, su Claude Platform on AWS, su Claude Models on Google Cloud (Anthropic managed) e su Microsoft Foundry. Su Microsoft Foundry, i deployment ospitati su Azure supportano solo lo strumento di web fetch di base (web_fetch_20250910, senza filtraggio dinamico). I deployment ospitati su Anthropic supportano tutte le versioni.
Per l’idoneità alla conservazione zero dei dati e la soluzione alternativa con allowed_callers, consulta Strumenti server.
Per il supporto dei modelli, consulta il Riferimento agli strumenti.
Come funziona il web fetch
Il 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 il web fetch e uno dei tuoi strumenti client nello stesso gruppo di chiamate di strumenti parallele: l’API restituisce la risposta con stop_reason: "tool_use" prima che quel fetch sia stato eseguito, quindi esegue il fetch quando rinvii i blocchi tool_result del client. Consulta Combinare strumenti server e strumenti client in un unico turno.
Quando aggiungi lo strumento di web fetch alla tua richiesta API:
- Claude determina quando recuperare il contenuto in base al prompt e agli URL disponibili.
- L’API recupera il contenuto testuale completo dall’URL specificato.
- Per i PDF, l’API restituisce il contenuto come dati codificati in base64 e lo elabora come un documento PDF allegato direttamente.
- Claude analizza il contenuto recuperato e fornisce una risposta con citazioni facoltative.
Quando Claude esegue il fetch
Claude esegue il fetch quando la richiesta punta a una pagina o a un documento specifico:
- Un URL è fornito nella conversazione (o in un precedente risultato di uno strumento)
- L’utente nomina una risorsa specifica (un particolare articolo, README, pagina dei prezzi o sezione della documentazione) senza un URL, e anche lo strumento di ricerca web è abilitato in modo che Claude possa prima individuarla (consulta Ricerca e fetch combinati)
Claude non esegue il fetch per domande di cultura 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, soprattutto quando da documenti di grandi dimensioni servono solo informazioni specifiche. 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_20260318:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
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_20260318", "name": "web_fetch"}],
)
print(response)Come usare il web fetch
Per sapere come le impostazioni di web fetch della tua organizzazione si applicano nelle sessioni di Claude Managed Agents, consulta Limitare i domini di ricerca web e web fetch.
Fornisci lo strumento di web fetch nella tua richiesta API:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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 di web fetch supporta i seguenti parametri:
{
"type": "web_fetch_20250910",
"name": "web_fetch",
// Optional: Limit the number of fetches
"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: Don't fetch URLs that appear only in client-side tool results
"url_sources": {
"client_tool_results": { "type": "none" }
},
// 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 facoltativi: 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 nella risposta).
Utilizzi massimi
Il parametro max_uses limita il numero di web fetch in un singolo turno. I fetch non riusciti vengono conteggiati nel limite. Se Claude chiama direttamente il web fetch più volte di quanto consentito, il web_fetch_tool_result è un errore con il codice di errore max_uses_exceeded. Se Claude chiama il web fetch dall’esecuzione del codice più volte di quanto consentito, l’esecuzione del codice termina con un errore. Non esiste un limite predefinito.
Un turno può estendersi su più richieste. Una richiesta continua un turno quando riprende dopo pause_turn o quando il suo ultimo messaggio contiene solo blocchi tool_result. I fetch delle richieste precedenti in quel turno vengono conteggiati nel limite, a meno che Claude non li abbia eseguiti dall’esecuzione del codice tramite il filtraggio dinamico.
Filtraggio dei domini
Per il filtraggio dei domini con allowed_domains e blocked_domains, consulta Strumenti server.
Su Claude Managed Agents, imposta questi campi nella voce web_fetch del toolset dell’agente; consulta Limitare i domini di ricerca web e web fetch.
Limiti del 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’uso dei token quando si recuperano documenti di grandi dimensioni. Il limite è approssimativo: il numero effettivo di token di input utilizzati può variare leggermente. Il limite si applica al contenuto testuale, non al contenuto binario come i PDF.
Se un PDF recuperato fa superare alla richiesta i limiti di pagine o di dimensione dei PDF, il web_fetch_tool_result è un errore con il codice di errore content_too_large. I PDF e le immagini già presenti nella conversazione vengono conteggiati in questi limiti, quindi rimuoverli può consentire al fetch di riuscire.
Su Claude Managed Agents, anche la voce web_fetch del toolset dell’agente accetta max_content_tokens; consulta le impostazioni degli strumenti web.
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 latenza.
{
"tools": [
{
"type": "web_fetch_20260309",
"name": "web_fetch",
"use_cache": false
}
]
}Inclusione nella risposta
Il parametro response_inclusion controlla come i blocchi dei risultati del fetch compaiono nella risposta dell’API quando il risultato è stato utilizzato da una chiamata di esecuzione del codice completata nella stessa risposta. Imposta "response_inclusion": "excluded" per rimuovere completamente dalla risposta quelle coppie annidate di blocchi server_tool_use e di risultato, per i flussi di lavoro agentici che non hanno bisogno del contenuto grezzo della pagina. L’utilizzo dei token non cambia, perché Claude legge l’output del codice anziché questi blocchi. Il valore predefinito è "full". L’API restituisce sempre per intero i risultati delle chiamate dirette, o delle chiamate di esecuzione del codice che si sono messe in pausa prima di essere completate, in modo che tu possa rinviarli nella richiesta successiva.
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"response_inclusion": "excluded"
}
]
}Citazioni
A differenza della ricerca web, in cui le citazioni sono sempre abilitate, per il web fetch le citazioni sono facoltative 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 recuperatocontent: Un blocco documento contenente il contenuto recuperatoretrieved_at: Timestamp del momento in cui 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 di web fetch riscontra un errore, la Claude API restituisce una risposta 200 (successo) con l’errore rappresentato nel corpo della risposta. Claude riceve il risultato dell’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,robots.txte URL che sembrano contenere una credenziale che non hai fornitourl_not_in_prior_context: L’URL non è comparso in precedenza nella conversazione, oppure è comparso solo in fonti escluse daurl_sources(consulta Convalida degli URL)url_not_accessible: Impossibile recuperare il contenuto (errore HTTP)too_many_requests: Limite di velocità superatounsupported_content_type: Tipo di contenuto non supportato (solo testo, HTML e PDF)content_too_large: Il PDF recuperato farebbe superare alla richiesta i limiti di pagine o di dimensione dei PDF (consulta Limiti del contenuto)max_uses_exceeded: Numero massimo di utilizzi dello strumento di web fetch superatounavailable: Si è verificato un errore interno
Convalida degli URL
Per motivi di sicurezza, lo strumento di web fetch può recuperare solo URL che sono già comparsi nel contesto della conversazione. Ciò include:
- URL nei messaggi dell’utente
- URL nei risultati degli strumenti lato client
- URL provenienti da precedenti risultati di ricerca web o web fetch
Lo strumento non può recuperare URL che compaiono solo nell’output di Claude o solo nel prompt di sistema. Per rendere recuperabile un URL presente nel prompt di sistema, includilo anche in un messaggio dell’utente. Nemmeno i risultati di altri strumenti lato server, come l’esecuzione del codice, il connettore MCP o la ricerca di strumenti, sono una fonte consentita. Per impostazione predefinita, i risultati degli strumenti lato client sono una fonte consentita anche quando riportano testo prodotto da Claude (ad esempio, un comando che stampa il proprio input o un messaggio di errore che lo cita).
Lo strumento rifiuta inoltre un URL che sembra contenere una credenziale, come una chiave API o una password, a meno che tale credenziale non compaia nel prompt di sistema o nel testo di un messaggio dell’utente. Una credenziale che compare solo nel risultato di uno strumento non viene considerata. Il risultato è un errore url_not_allowed. Per recuperare un URL di questo tipo, includilo in un messaggio dell’utente.
Fonti degli URL
Il parametro facoltativo url_sources ti consente di disattivare una qualsiasi delle tre fonti consentite, oppure di limitare i risultati degli strumenti a determinati strumenti. Ha una chiave per ciascuna fonte, e ogni chiave ha come valore predefinito {"type": "all"}:
user_input: URL nei messaggi dell’utente. Il suotypeè"all"o"none".client_tool_results: URL nei risultati degli strumenti lato client. Il suotypeè"all","none", oppure un filtro"only"o"except"che nomina degli strumenti, come nell’esempio seguente.server_tool_results: URL provenienti da precedenti risultati di ricerca web o web fetch. Accetta gli stessi valori, e i suoi filtri nominanoweb_searchoweb_fetch.
Ad esempio, uno strumento che esegue codice scritto da Claude restituisce tutto ciò che quel codice stampa, incluso qualsiasi URL che Claude vi abbia inserito. Per impedire che i risultati di quello strumento vengano considerati come fonte, nominalo in un filtro "except":
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"url_sources": {
"client_tool_results": {
"type": "except",
"tools": [{ "type": "tool_reference", "name": "run_code" }]
}
}
},
{
"name": "run_code",
"description": "Run Python code and return its output",
"input_schema": {
"type": "object",
"properties": { "code": { "type": "string" } },
"required": ["code"]
}
}
]
}Un filtro elenca gli strumenti come oggetti tool_reference. Ogni nome deve corrispondere a uno strumento nell’array tools della richiesta: uno strumento client per client_tool_results, o uno strumento server per server_tool_results. In caso contrario, la richiesta non riesce con un errore. Con "except", uno strumento che aggiungi a tools in seguito viene considerato come fonte. Con "only", non lo è.
Anche strumenti lato client diversi da run_code possono restituire testo scritto da Claude, ad esempio in un messaggio di errore che lo cita. Per escludere tutti i risultati degli strumenti lato client, imposta client_tool_results su {"type": "none"}.
Se un URL è comparso solo in fonti escluse da url_sources, il suo recupero restituisce l’errore url_not_in_prior_context.
Ricerca e fetch combinati
Quando sono abilitati sia lo strumento di ricerca web sia lo strumento di web fetch, e l’utente nomina una pagina o un documento specifico senza fornire un URL (ad esempio, “leggi il README del repository anthropics/anthropic-sdk-python”), Claude usa la ricerca web per individuarlo, 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-5-5",
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:
- Usa la ricerca web per trovare articoli pertinenti.
- Seleziona i risultati più promettenti.
- Usa il web fetch per recuperare il contenuto completo.
- 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 runs
// 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 di web fetch nella Message Batches API. Le chiamate allo strumento di web fetch tramite la Message Batches API hanno lo stesso prezzo di quelle nelle normali richieste alla Messages API.
Utilizzo e prezzi
L’utilizzo di web fetch non comporta costi aggiuntivi 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 sulla Claude API 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 una quantità eccessiva 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 dei 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
Esegui codice Python e Bash in un container isolato per analizzare dati, generare file e iterare sulle soluzioni.
Lavora con gli strumenti eseguiti da Anthropic: blocchi server_tool_use, continuazione con pause_turn e filtraggio dei domini.
Elenco degli strumenti forniti da Anthropic e riferimento per le proprietà facoltative della definizione degli strumenti.
Disponibilità
Claude API
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Microsoft Foundry (hosted on Azure)
- API
- Messages API
- Modelli
- Tutti i modelli
- Nota
I deployment ospitati su Azure supportano solo
web_fetch_20250910: niente filtro dinamico, inclusione della risposta o bypass della cache.
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Modelli
- Tutti i modelli
Gestione dei dati
Panoramica sulla gestione dei datiEndpoint applicabili
/v1/messagescon lo strumentoweb_fetch
Esclude Modelli coperti
Contenuto web recuperato restituito nella risposta dell’API. Il filtro dinamico per web fetch non è idoneo per ZDR o HIPAA. Gli editori dei siti web potrebbero conservare i dati delle richieste (come gli URL recuperati e i metadati delle richieste) secondo le proprie policy.
Questa pagina ti è stata utile?