Lo strumento web fetch consente a Claude di recuperare contenuti completi da pagine web e documenti PDF specificati.

Lo strumento web fetch è attualmente in beta. Per abilitarlo, utilizza l’header beta web-fetch-2025-09-10 nelle tue richieste API.

Si prega di utilizzare questo modulo per fornire feedback sulla qualità delle risposte del modello, sull’API stessa o sulla qualità della documentazione.

Abilitare lo strumento web fetch in ambienti dove Claude elabora input non attendibili insieme a dati sensibili comporta rischi di esfiltrazione dati. Raccomandiamo di utilizzare questo strumento solo in ambienti fidati o quando si gestiscono dati non sensibili.

Per minimizzare i rischi di esfiltrazione, a Claude non è consentito costruire dinamicamente URL. Claude può recuperare solo URL che sono stati esplicitamente forniti dall’utente o che provengono da precedenti risultati di ricerca web o web fetch. Tuttavia, rimane comunque un rischio residuo che dovrebbe essere attentamente considerato quando si utilizza questo strumento.

Se l’esfiltrazione dati è una preoccupazione, considera:

  • Disabilitare completamente lo strumento web fetch
  • Utilizzare il parametro max_uses per limitare il numero di richieste
  • Utilizzare il parametro allowed_domains per limitare a domini sicuri noti

​
Modelli supportati

Web fetch è disponibile su:

  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 v2 (deprecato) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Come funziona web fetch

Quando aggiungi lo strumento web fetch alla tua richiesta API:

  1. Claude decide quando recuperare contenuti basandosi sul prompt e sugli URL disponibili.
  2. L’API recupera il contenuto testuale 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.

​
Come utilizzare web fetch

Fornisci lo strumento web fetch 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-opus-4-1-20250805",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Per favore analizza il contenuto su https://example.com/article"
            }
        ],
        "tools": [{
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5
        }]
    }'

​
Definizione dello strumento

Lo strumento web fetch 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 contenuti recuperati
  "citations": {
    "enabled": true
  },

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

​
Max uses

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

​
Filtro domini

Quando si utilizzano filtri di dominio:

  • I domini non dovrebbero includere lo schema HTTP/HTTPS (usa example.com invece di https://example.com)
  • I sottodomini sono automaticamente inclusi (example.com copre docs.example.com)
  • I sottopercorsi sono supportati (example.com/blog)
  • Puoi utilizzare allowed_domains o blocked_domains, ma non entrambi nella stessa richiesta.

Fai attenzione che i caratteri Unicode nei nomi di dominio possono creare vulnerabilità di sicurezza attraverso attacchi omografici, dove caratteri visivamente simili da script diversi possono aggirare i filtri di dominio. Ad esempio, аmazon.com (usando la ‘а’ cirillica) può apparire identico a amazon.com ma rappresenta un dominio diverso.

Quando configuri liste di domini consentiti/bloccati:

  • Usa nomi di dominio solo ASCII quando possibile
  • Considera che i parser URL possono gestire la normalizzazione Unicode diversamente
  • Testa i tuoi filtri di dominio con potenziali variazioni omografiche
  • 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 verrà inclusa nel contesto. Se il contenuto recuperato supera questo limite, verrà troncato. Questo aiuta a controllare l’utilizzo dei token quando si recuperano documenti grandi.

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 web fetch. Imposta "citations": {"enabled": true} per abilitare Claude a citare passaggi specifici dai documenti recuperati.

Quando mostri risultati web o informazioni contenute nei risultati web agli utenti finali, le citazioni inline devono essere rese chiaramente visibili e cliccabili nella tua interfaccia utente.

​
Risposta

Ecco un esempio di struttura di risposta:

{
  "role": "assistant",
  "content": [
    // 1. Decisione di Claude di recuperare
    {
      "type": "text",
      "text": "Recupererò il contenuto dall'articolo per analizzarlo."
    },
    // 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": "Contenuto testuale completo dell'articolo..."
          },
          "title": "Titolo dell'Articolo",
          "citations": {"enabled": true}
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Analisi di Claude con citazioni (se abilitate)
    {
      "text": "Basandosi sull'articolo, ",
      "type": "text"
    },
    {
      "text": "l'argomento principale presentato è che l'intelligenza artificiale trasformerà la sanità",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Titolo dell'Articolo",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "L'intelligenza artificiale è pronta a rivoluzionare l'erogazione sanitaria..."
        }
      ]
    }
  ],
  "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 documento contenente il contenuto recuperato
  • retrieved_at: Timestamp di quando il contenuto è stato recuperato

Lo strumento web fetch memorizza i risultati in cache per migliorare le prestazioni e ridurre le richieste ridondanti. Questo 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 per diversi tipi di contenuto e modelli di utilizzo.

Per 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 web fetch incontra un errore, l’API Anthropic 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: URL supera la lunghezza massima (250 caratteri)
  • url_not_allowed: URL bloccato dalle regole di filtro dominio e restrizioni del modello
  • url_not_accessible: Fallimento nel recuperare 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 web fetch superati
  • unavailable: Si è verificato un errore interno

​
Validazione URL

Per ragioni di sicurezza, lo strumento web fetch può recuperare solo URL che sono apparsi precedentemente nel contesto della conversazione. Questo include:

  • URL nei messaggi utente
  • URL nei risultati degli strumenti lato client
  • URL da precedenti risultati di ricerca web o web fetch

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

​
Ricerca e recupero combinati

Web fetch funziona perfettamente con la ricerca web per una raccolta completa di informazioni:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Trova articoli recenti sul quantum computing e analizza in dettaglio quello più rilevante"
        }
    ],
    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:

  1. Utilizzerà la ricerca web per trovare articoli rilevanti
  2. Selezionerà i risultati più promettenti
  3. Utilizzerà web fetch per recuperare contenuto completo
  4. Fornirà analisi dettagliate con citazioni

​
Prompt caching

Web fetch funziona con prompt caching. Per abilitare il prompt caching, aggiungi punti di interruzione cache_control nella tua richiesta. I risultati di recupero memorizzati in cache possono essere riutilizzati attraverso i turni di conversazione.

import anthropic

client = anthropic.Anthropic()

# Prima richiesta con web fetch
messages = [
    {
        "role": "user",
        "content": "Analizza questo documento di ricerca: https://arxiv.org/abs/2024.12345"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# Aggiungi la risposta di Claude alla conversazione
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Seconda richiesta con punto di interruzione cache
messages.append({
    "role": "user",
    "content": "Quale metodologia utilizza il documento?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# La seconda risposta beneficia dei risultati di recupero memorizzati in cache
print(f"Token di lettura cache: {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": ""}}

// Decisione di Claude di recuperare

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// URL di recupero trasmesso in streaming
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Pausa mentre il recupero viene eseguito

// Risultati del recupero trasmessi in streaming
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": "Contenuto dell'articolo..."}}}}}

// La risposta di Claude continua...

​
Richieste batch

Puoi includere lo strumento web fetch nell’API Messages Batches. Le chiamate dello strumento web fetch attraverso 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 Anthropic 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