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 l'idoneità alla Zero Data Retention e la soluzione alternativa allowed_callers, vedi Server tools.

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:

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

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

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

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)

Come usare il recupero web

Fornisci lo strumento di recupero web nella tua richiesta API:

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)

Definizione dello strumento

Lo strumento di recupero web supporta i seguenti parametri:

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

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.

Risposta

Ecco una struttura di risposta di esempio:

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

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 recupero web incontra un errore, l'API Claude restituisce una risposta 200 (successo) con l'errore rappresentato nel corpo della risposta:

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

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:

1. Userà la ricerca web per trovare articoli rilevanti
2. Selezionerà i risultati più promettenti
3. Userà il recupero web per recuperare il contenuto completo
4. 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:

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