Strumento di recupero web
Lo strumento di recupero web consente a Claude di recuperare il contenuto completo da pagine web e documenti PDF specificati.
Lo strumento di recupero web è attualmente in versione beta. Per abilitarlo, utilizza l'intestazione beta web-fetch-2025-09-10 nelle tue richieste API.
Utilizza questo modulo per fornire feedback sulla qualità delle risposte del modello, sull'API stessa o sulla qualità della documentazione.
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. Ti consigliamo di utilizzare 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 di ricerca web o recupero web precedenti. 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
- Utilizzare il parametro
max_usesper limitare il numero di richieste - Utilizzare il parametro
allowed_domainsper limitare i domini noti e sicuri
Modelli supportati
Il recupero web è disponibile su:
- Claude Sonnet 4.5 (
claude-sonnet-4-5-20250929) - Claude Sonnet 4 (
claude-sonnet-4-20250514) - Claude Sonnet 3.7 (deprecato) (
claude-3-7-sonnet-20250219) - Claude Haiku 4.5 (
claude-haiku-4-5-20251001) - Claude Haiku 3.5 (
claude-3-5-haiku-latest) - Claude Opus 4.1 (
claude-opus-4-1-20250805) - Claude Opus 4 (
claude-opus-4-20250514)
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 siti web renderizzati dinamicamente tramite Javascript.
Come utilizzare il recupero web
Fornisci lo strumento di recupero web nella tua richiesta API:
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: web-fetch-2025-09-10" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-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
}]
}'import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-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
}],
extra_headers={
"anthropic-beta": "web-fetch-2025-09-10"
}
)
print(response)import { Anthropic } from '@anthropic-ai/sdk';
const anthropic = new Anthropic();
async function main() {
const response = await anthropic.messages.create({
model: "claude-sonnet-4-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
}],
headers: {
"anthropic-beta": "web-fetch-2025-09-10"
}
});
console.log(response);
}
main().catch(console.error);Definizione dello strumento
Lo strumento di recupero web 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
"blocked_domains": ["private.example.com"],
// Optional: Enable citations for fetched content
"citations": {
"enabled": true
},
// Optional: Maximum content length in tokens
"max_content_tokens": 100000
}Max uses
Il parametro max_uses limita il numero di recuperi web eseguiti. Se Claude tenta più recuperi del consentito, il web_fetch_tool_result sarà un errore con il codice di errore max_uses_exceeded. Attualmente non esiste un limite predefinito.
Filtro dei domini
Quando si utilizzano i filtri dei domini:
- I domini non devono includere lo schema HTTP/HTTPS (usa
example.cominvece dihttps://example.com) - I sottodomini sono automaticamente inclusi (
example.comcopredocs.example.com) - I percorsi secondari sono supportati (
example.com/blog) - Puoi utilizzare
allowed_domainsoblocked_domains, ma non entrambi nella stessa richiesta.
Tieni presente che i caratteri Unicode nei nomi di dominio possono creare vulnerabilità di sicurezza attraverso attacchi di omografi, in cui caratteri visivamente simili da script diversi possono aggirare i filtri dei domini. Ad esempio, аmazon.com (utilizzando la 'а' cirillica) può sembrare identico a amazon.com ma rappresenta un dominio diverso.
Quando configuri elenchi di domini consentiti/bloccati:
- Utilizza nomi di dominio solo ASCII quando possibile
- Considera che i parser di URL possono gestire la normalizzazione Unicode diversamente
- Testa i tuoi filtri di dominio con potenziali variazioni di omografi
- Controlla regolarmente le tue configurazioni di dominio per caratteri Unicode sospetti
Limiti di contenuto
Il parametro max_content_tokens limita la quantità di contenuto che sarà inclusa nel contesto. Se il contenuto recuperato supera questo limite, verrà troncato. 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 leggermente.
Citazioni
A differenza della ricerca web in cui 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:
{
"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 recupero
I risultati del recupero includono:
url: L'URL che è stato recuperatocontent: Un blocco di documento contenente il contenuto recuperatoretrieved_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. Ciò significa che il contenuto restituito potrebbe non essere sempre la versione più recente disponibile all'URL. Il comportamento della cache è gestito automaticamente e può cambiare nel tempo per ottimizzare diversi tipi di contenuto e modelli di utilizzo.
Per i documenti PDF, il contenuto verrà 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 validourl_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 modellourl_not_accessible: Impossibile recuperare il contenuto (errore HTTP)too_many_requests: Limite di velocità superatounsupported_content_type: Tipo di contenuto non supportato (solo testo e PDF)max_uses_exceeded: Utilizzi massimi dello strumento di recupero web superatiunavailable: 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 da risultati di ricerca web o recupero web precedenti
Lo strumento non può recuperare URL arbitrari generati da Claude 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:
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-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}
}
],
extra_headers={
"anthropic-beta": "web-fetch-2025-09-10"
}
)In questo flusso di lavoro, Claude:
- Utilizzerà la ricerca web per trovare articoli rilevanti
- Selezionerà i risultati più promettenti
- Utilizzerà il recupero web per recuperare il contenuto completo
- Fornirà un'analisi dettagliata con citazioni
Memorizzazione nella cache dei prompt
Il recupero web funziona con la memorizzazione nella cache dei prompt. Per abilitare la memorizzazione nella cache dei prompt, aggiungi punti di interruzione cache_control nella tua richiesta. I risultati del recupero memorizzati nella cache possono essere riutilizzati nei turni di conversazione.
import anthropic
client = anthropic.Anthropic()
# First request with web fetch
messages = [
{
"role": "user",
"content": "Analyze this research paper: https://arxiv.org/abs/2024.12345"
}
]
response1 = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=messages,
tools=[{
"type": "web_fetch_20250910",
"name": "web_fetch"
}],
extra_headers={
"anthropic-beta": "web-fetch-2025-09-10"
}
)
# Add Claude's response to conversation
messages.append({
"role": "assistant",
"content": response1.content
})
# Second request with cache breakpoint
messages.append({
"role": "user",
"content": "What methodology does the paper use?",
"cache_control": {"type": "ephemeral"}
})
response2 = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=messages,
tools=[{
"type": "web_fetch_20250910",
"name": "web_fetch"
}],
extra_headers={
"anthropic-beta": "web-fetch-2025-09-10"
}
)
# The second response benefits from cached fetch results
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")Streaming
Con lo streaming abilitato, gli eventi di recupero fanno parte del flusso 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 (10KB): ~2,500 tokens
- Large documentation page (100KB): ~25,000 tokens
- Research paper PDF (500KB): ~125,000 tokens