Strumento di recupero web

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

L'ultima versione dello strumento di recupero web (web_fetch_20260209) supporta filtri dinamici con Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 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à della risposta. La versione precedente dello strumento (web_fetch_20250910) rimane disponibile senza filtri dinamici.

Per Claude Mythos Preview, il recupero web è supportato su Claude API e Microsoft Foundry solo. Non è disponibile per Mythos Preview su Amazon Bedrock o Google Vertex AI.

Usa il modulo di feedback per fornire feedback sulla qualità delle risposte del modello, sull'API stessa o sulla qualità della documentazione.

Per l'idoneità alla Zero Data Retention e la soluzione alternativa allowed_callers, vedi Server tools.

L'abilitazione dello strumento di recupero web in ambienti in cui Claude elabora input non attendibili insieme a dati sensibili comporta rischi di esfiltrazione dei dati. Usa questo strumento solo in ambienti attendibili o quando gestisci dati non sensibili.

Per ridurre al minimo i rischi di esfiltrazione, a Claude non è consentito costruire dinamicamente gli URL. Claude può recuperare solo gli URL che sono stati esplicitamente forniti dall'utente o che provengono da risultati precedenti di ricerca web o recupero web. Tuttavia, esiste ancora un rischio residuo che dovrebbe essere attentamente considerato quando si utilizza questo strumento.

Se l'esfiltrazione dei dati è una preoccupazione, considera:

Disabilitare completamente lo strumento di recupero web
Usare il parametro max_uses per limitare il numero di richieste
Usare il parametro allowed_domains per limitare a domini noti e sicuri

Per il supporto del modello, vedi il Tool reference.

Come funziona il recupero web

Quando aggiungi lo strumento di recupero web alla tua richiesta API:

Claude decide quando recuperare il contenuto in base al prompt e agli URL disponibili.
L'API recupera il contenuto di testo completo dall'URL specificato.
Per i PDF, viene eseguita l'estrazione automatica del testo.
Claude analizza il contenuto recuperato e fornisce una risposta con citazioni opzionali.

Lo strumento di recupero web attualmente non supporta i siti web renderizzati dinamicamente tramite JavaScript.

Filtri dinamici

Il recupero di pagine web e PDF complete può consumare rapidamente i token, soprattutto quando sono necessarie solo informazioni specifiche da documenti di grandi dimensioni. Con la versione dello strumento web_fetch_20260209, Claude può scrivere ed eseguire codice per filtrare il contenuto recuperato prima di caricarlo nel contesto.

Questo filtro 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

Il filtro dinamico richiede l'abilitazione dello strumento di esecuzione del codice. Lo strumento di recupero web (con e senza filtri dinamici) è disponibile su Claude API e Microsoft Azure.

Per abilitare il filtro dinamico, usa la versione dello strumento web_fetch_20260209:

Come usare il recupero web

Fornisci lo strumento di recupero web nella tua richiesta API:

Definizione dello strumento

Lo strumento di recupero web supporta i seguenti parametri:

JSON

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

  // Opzionale: Limita il numero di recuperi per richiesta
  "max_uses": 10,

  // Opzionale: Recupera solo da questi domini
  "allowed_domains": ["example.com", "docs.example.com"],

  // Opzionale: Non recuperare mai da questi domini
  "blocked_domains": ["private.example.com"],

  // Opzionale: Abilita citazioni per il contenuto recuperato
  "citations": {
    "enabled": true
  },

  // Opzionale: Lunghezza massima del contenuto in token
  "max_content_tokens": 100000
}

Max uses

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

Filtro dei domini

Per il filtro dei domini con allowed_domains e blocked_domains, vedi Server tools.

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'utilizzo dei token quando si recuperano documenti di grandi dimensioni.

Il limite del parametro max_content_tokens è approssimativo. Il numero effettivo di token di input utilizzati può variare di una piccola quantità.

Citazioni

A differenza della ricerca web dove le citazioni sono sempre abilitate, le citazioni sono opzionali per il recupero web. Imposta "citations": {"enabled": true} per consentire a Claude di citare passaggi specifici dai documenti recuperati.

Quando visualizzi gli output dell'API direttamente agli utenti finali, le citazioni devono essere incluse alla fonte originale. Se stai apportando modifiche agli output dell'API, incluso il rielaborazione e/o la combinazione con il tuo materiale prima di visualizzarli agli utenti finali, visualizza le citazioni come appropriato in base alla consultazione con il tuo team legale.

Risposta

Ecco una struttura di risposta di esempio:

Output

{
  "role": "assistant",
  "content": [
    // 1. Decisione di Claude di recuperare
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. La richiesta di recupero
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Risultati del recupero
    {
      "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. Analisi di Claude con citazioni (se abilitate)
    {
      "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 recupero

I risultati del recupero includono:

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

Lo strumento di recupero web memorizza nella cache i risultati per migliorare le prestazioni e ridurre le richieste ridondanti. Il contenuto restituito potrebbe non sempre riflettere la versione più recente disponibile all'URL. Il comportamento della cache è gestito automaticamente e potrebbe cambiare nel tempo per ottimizzare diversi tipi di contenuto e modelli di utilizzo.

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

Errori

Quando lo strumento di recupero web incontra un errore, l'API Claude restituisce una risposta 200 (successo) con l'errore rappresentato nel corpo della risposta:

Output

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

Questi sono i possibili codici di errore:

invalid_input: Formato URL non valido
url_too_long: L'URL supera la lunghezza massima (250 caratteri)
url_not_allowed: URL bloccato dalle regole di filtro dei domini e dalle restrizioni del modello
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 e PDF)
max_uses_exceeded: Utilizzi massimi dello strumento di recupero web superati
unavailable: Si è verificato un errore interno

Convalida dell'URL

Per motivi di sicurezza, lo strumento di recupero web può recuperare solo gli URL che sono stati precedentemente visualizzati nel contesto della conversazione. Questo include:

URL nei messaggi dell'utente
URL nei risultati degli strumenti lato client
URL dai risultati precedenti di ricerca web o recupero web

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

Ricerca e recupero combinati

Il recupero web funziona perfettamente con la ricerca web per una raccolta di informazioni completa:

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

In questo flusso di lavoro, Claude:

Userà la ricerca web per trovare articoli rilevanti
Selezionerà i risultati più promettenti
Userà il recupero web per recuperare il contenuto completo
Fornirà un'analisi dettagliata con citazioni

Memorizzazione nella cache dei prompt

Per la memorizzazione nella cache delle definizioni degli strumenti tra i turni, vedi Tool use with prompt caching.

Streaming

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

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

Richieste batch

Puoi includere lo strumento di recupero web nell'API Messages Batches. Le chiamate dello strumento di recupero web tramite l'API Messages Batches hanno lo stesso prezzo di quelle nelle richieste API Messages regolari.

Utilizzo e prezzi

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

Passaggi successivi

Server tools

Meccaniche condivise per gli strumenti eseguiti da Anthropic.

Tool reference

Directory di tutti gli strumenti forniti da 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)