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 di recupero web (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 i 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 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 recupero di base) restano disponibili.

Il web fetch (con e senza filtraggio dinamico) è disponibile sulla Claude API, su Claude Platform on AWS e su Microsoft Foundry. Su Microsoft Foundry, i deployment ospitati su Azure supportano solo lo strumento web fetch di base (web_fetch_20250910, senza filtraggio dinamico). I deployment ospitati su Anthropic supportano tutte le versioni. Il web fetch non è attualmente disponibile su Amazon Bedrock o Google Cloud.

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

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

Come funziona il web fetch

Il web fetch è un server tool (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 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 determina 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 di strumento precedente)
• L'utente nomina una risorsa specifica (un particolare articolo, README, pagina dei prezzi o sezione di documentazione) senza un URL, e anche lo strumento web search è abilitato, così Claude può prima localizzarla (vedi 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 servono 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 dei 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

Fornisci lo strumento web fetch nella tua richiesta API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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 successiva (vedi Cache bypass), e response_inclusion richiede web_fetch_20260318 o successiva (vedi Response inclusion).

Max uses

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.

Su Claude Managed Agents, imposta questi campi nella voce web_fetch del toolset dell'agente, dove ogni dominio elencato deve essere un semplice hostname senza percorso; consulta Limitare i domini di web search e web fetch.

Limiti di contenuto

Il parametro max_content_tokens limita la quantità di contenuto incluso 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 si applica al contenuto testuale, non al contenuto binario come i PDF.

Su Claude Managed Agents, la voce web_fetch del toolset dell'agente accetta anche max_content_tokens; consulta Limitare i domini di web search e web fetch.

Cache bypass

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

Response inclusion

Il parametro response_inclusion controlla come i blocchi dei risultati di fetch appaiono nella risposta 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 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 delle chiamate dirette, o delle chiamate di esecuzione del codice che si sono messe in pausa prima del completamento, vengono sempre restituiti per intero in modo che possano essere rinviati al turno successivo.

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

Citazioni

A differenza del web search, dove le citazioni sono sempre abilitate, le citazioni sono opzionali per il 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 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 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, robots.txt e URL che sembrano contenere una credenziale che non hai fornito
• url_not_in_prior_context: L'URL non è apparso in precedenza nella conversazione (vedi Validazione degli URL)
• url_not_accessible: Impossibile recuperare il contenuto (errore HTTP)
• too_many_requests: "Rate limit" (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 provenienti da risultati precedenti di web search 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 degli strumenti, sono una fonte consentita. 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 è sufficiente. Il risultato è un errore url_not_allowed. Per recuperare un URL di questo tipo, includilo in un messaggio dell'utente.

Ricerca e fetch combinati

Quando sia lo strumento web search sia 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 il web search per localizzarlo, quindi esegue il fetch del 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:

1. Usa il web search per trovare articoli rilevanti.
2. Seleziona i risultati più promettenti.
3. Usa il 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 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