Strumento di web fetch

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 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 finestra di contesto, mantenendo solo le informazioni rilevanti e scartando il resto. Questo riduce il consumo di token mantenendo la qualità delle risposte. web_fetch_20260318 aggiunge anche il controllo della 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.

Il web fetch (con e senza filtraggio dinamico) è disponibile sulla Claude API, su Claude Platform su AWS e su Microsoft Foundry. Su Microsoft Foundry, il web fetch richiede un deployment Hosted on Anthropic. 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 è 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 è 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, poi esegue il fetch quando invii indietro 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:

1. Claude determina quando recuperare il contenuto 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 a 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 della documentazione) senza un URL, e lo strumento di web search è anch'esso abilitato in modo che Claude possa prima individuarla (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 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-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_20260318", "name": "web_fetch"}],
)
print(response)



Come usare il web fetch

Fornisci lo strumento di 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 di 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).



Numero massimo di utilizzi

Il parametro max_uses limita il numero di web fetch eseguiti. I fetch falliti 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 si recuperano fonti che cambiano rapidamente, perché bypassare la cache aumenta la latenza.

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



Inclusione della risposta

Il parametro response_inclusion controlla come i blocchi dei risultati di 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 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 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 di 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 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 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 di web fetch superato
• unavailable: Si è verificato un errore interno



Validazione degli URL

Per motivi di sicurezza, lo strumento di 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 precedenti risultati 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 (come Code Execution e Bash).



Ricerca e fetch combinati

Quando sia lo strumento di web search sia quello di 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 individuarlo, poi 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 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 di web fetch nella Messages Batches API. Le chiamate allo strumento di web fetch tramite la Messages Batches API hanno lo stesso prezzo di quelle nelle normali richieste alla 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



Prossimi passi