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 il filtraggio dinamico con Claude Opus 4.6 e 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 filtraggio dinamico.

Modelli supportati

Il recupero web è disponibile su:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• 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)

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.

Filtraggio dinamico con Opus 4.6 e Sonnet 4.6

Il recupero di pagine web e PDF completi 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 filtraggio dinamico è particolarmente utile per:

• Estrarre sezioni specifiche da documenti lunghi
• Elaborare dati strutturati da pagine web
• Filtrare informazioni rilevanti da PDF
• Ridurre i costi dei token quando si lavora con documenti di grandi dimensioni

Per abilitare il filtraggio dinamico, utilizza la versione dello strumento web_fetch_20260209 con l'intestazione beta code-execution-web-tools-2026-02-09:

Come utilizzare 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:

{
  "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 di quelli consentiti, il web_fetch_tool_result sarà un errore con il codice di errore max_uses_exceeded. Attualmente non esiste un limite predefinito.

Filtraggio del dominio

Quando si utilizzano filtri di dominio:

• I domini non devono 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.

Limiti di contenuto

Il parametro max_content_tokens limita la quantità di contenuto che verrà incluso 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.

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.

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 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 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 valido
• url_too_long: L'URL supera la lunghezza massima (250 caratteri)
• url_not_allowed: URL bloccato dalle regole di filtraggio del dominio 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 apparsi in precedenza 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 che Claude genera o URL da strumenti server basati su container (Esecuzione del codice, 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-opus-4-6",
    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. Utilizzerà la ricerca web per trovare articoli rilevanti
2. Selezionerà i risultati più promettenti
3. Utilizzerà il recupero web per recuperare il contenuto completo
4. 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 tra i 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-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch"}],
)

# 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-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch"}],
)

# 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