Strumento di ricerca web

Lo strumento di ricerca web offre a Claude accesso diretto ai contenuti web in tempo reale, consentendogli di rispondere alle domande con informazioni aggiornate che vanno oltre il suo limite di conoscenza. La risposta include citazioni per le fonti tratte dai risultati di ricerca.

La versione più recente dello strumento di ricerca web (web_search_20260209) supporta il filtraggio dinamico con Claude Opus 4.8, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6. Claude può scrivere ed eseguire codice per filtrare i risultati di ricerca prima che raggiungano la finestra di contesto, mantenendo solo le informazioni rilevanti e scartando il resto. Questo porta a risposte più accurate riducendo al contempo il consumo di token. La versione precedente dello strumento (web_search_20250305) rimane disponibile senza filtraggio dinamico.

Per l'idoneità alla Zero Data Retention e la soluzione alternativa allowed_callers, consulta Strumenti server.

Per il supporto dei modelli, consulta il Riferimento degli strumenti.



Come funziona la ricerca web

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

1. Claude decide quando effettuare una ricerca in base al prompt.
2. L'API esegue le ricerche e fornisce a Claude i risultati. Questo processo può ripetersi più volte nel corso di una singola richiesta.
3. Alla fine del suo turno, Claude fornisce una risposta finale con le fonti citate.



Quando Claude effettua una ricerca

Claude effettua una ricerca quando la richiesta dipende da informazioni attuali, in evoluzione o esterne ai suoi dati di addestramento:

• Eventi recenti, notizie o annunci
• Prezzi, tassi, punteggi o statistiche attuali
• Informazioni su organizzazioni, persone o prodotti specifici che potrebbero essere cambiate
• Richieste esplicite di cercare o consultare qualcosa

Claude risponde direttamente senza effettuare ricerche quando la richiesta si basa su conoscenze stabili:

• Fatti consolidati, matematica, fondamenti scientifici o concetti di programmazione
• Scrittura creativa o brainstorming
• Analisi di contenuti già forniti nella conversazione
• Turni conversazionali e saluti

L'attivazione è orientabile tramite il tuo prompt di sistema: puoi incoraggiare Claude a effettuare ricerche più prontamente o a preferire risposte dirette. Per un vincolo rigido, usa max_uses per limitare il numero di ricerche per ogni richiesta.



Filtraggio dinamico

La ricerca web è un'attività ad alto consumo di token. Con la ricerca web di base, Claude deve caricare i risultati di ricerca nel contesto, recuperare l'HTML completo da più siti web e ragionare su tutto questo prima di arrivare a una risposta. Spesso, gran parte di questo contenuto è irrilevante, il che può degradare la qualità della risposta.

Con la versione dello strumento web_search_20260209, Claude può scrivere ed eseguire codice per post-elaborare i risultati delle query. Invece di ragionare su file HTML completi, Claude filtra dinamicamente i risultati di ricerca prima di caricarli nel contesto, mantenendo solo ciò che è rilevante e scartando il resto.

Il filtraggio dinamico è particolarmente efficace per:

• Ricerca all'interno di documentazione tecnica
• Revisione della letteratura e verifica delle citazioni
• Ricerca tecnica
• Fondamento e verifica delle risposte

Per abilitare il filtraggio dinamico, usa la versione dello strumento web_search_20260209:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
        }
    ],
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
)
print(response)



Come usare la ricerca web

Fornisci lo strumento di ricerca web nella tua richiesta API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)



Definizione dello strumento

Lo strumento di ricerca web supporta i seguenti parametri:

{
  "type": "web_search_20250305",
  "name": "web_search",

  // Optional: Limit the number of searches per request
  "max_uses": 5,

  // Optional: Only include results from these domains
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Never include results from these domains
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Localize search results
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}



Max uses

Il parametro max_uses limita il numero di ricerche eseguite. Se Claude tenta di effettuare più ricerche di quelle consentite, il web_search_tool_result è un errore con il codice di errore max_uses_exceeded.

Le query fattuali semplici utilizzano in genere da 1 a 3 ricerche; le ricerche comparative o su più entità possono utilizzarne 10 o più. Per le ricerche sensibili alla latenza, max_uses: 3 limita i costi con rari troncamenti. Per gli agenti di ricerca, imposta max_uses a 15–20 o omettilo del tutto.



Filtraggio dei domini

Per il filtraggio dei domini con allowed_domains e blocked_domains, consulta Strumenti server.



Localizzazione

Il parametro user_location consente di localizzare i risultati di ricerca in base alla posizione dell'utente.

• type: Il tipo di posizione (deve essere approximate)
• city: Il nome della città
• region: La regione o lo stato
• country: Il paese
• timezone: L'ID del fuso orario IANA.



Risposta

Ecco un esempio di struttura della risposta:

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to search
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. The search query used
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Search results
    {
      "type": "web_search_tool_result",
      "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "content": [
        {
          "type": "web_search_result",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
          "page_age": "April 30, 2025"
        }
      ]
    },
    {
      "text": "Based on the search results, ",
      "type": "text"
    },
    // 4. Claude's response with citations
    {
      "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
      "type": "text",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
          "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}



Risultati di ricerca

I risultati di ricerca includono:

• url: L'URL della pagina sorgente
• title: Il titolo della pagina sorgente
• page_age: Quando il sito è stato aggiornato l'ultima volta
• encrypted_content: Contenuto crittografato che deve essere restituito nelle conversazioni multi-turno per le citazioni



Citazioni

Le citazioni sono sempre abilitate per la ricerca web e ogni web_search_result_location include:

• url: L'URL della fonte citata
• title: Il titolo della fonte citata
• encrypted_index: Un riferimento che deve essere restituito per le conversazioni multi-turno.
• cited_text: Fino a 150 caratteri del contenuto citato

I campi di citazione della ricerca web cited_text, title e url non vengono conteggiati nell'utilizzo dei token di input o output.



Errori

Quando lo strumento di ricerca web incontra un errore (ad esempio il raggiungimento dei limiti di velocità), l'API di Claude restituisce comunque una risposta 200 (successo). L'errore è rappresentato all'interno del corpo della risposta utilizzando la seguente struttura:

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

Questi sono i possibili codici di errore:

• too_many_requests: Limite di velocità superato
• invalid_input: Parametro della query di ricerca non valido
• max_uses_exceeded: Numero massimo di utilizzi dello strumento di ricerca web superato
• query_too_long: La query supera la lunghezza massima
• unavailable: Si è verificato un errore interno



Motivo di arresto pause_turn

Per continuare dopo un motivo di arresto pause_turn, consulta Strumenti server.



Cache dei prompt

Per la memorizzazione nella cache delle definizioni degli strumenti tra i turni, consulta Uso degli strumenti con la cache dei prompt.



Streaming

Con lo streaming abilitato, riceverai gli eventi di ricerca come parte dello stream. Ci sarà una pausa mentre la ricerca viene eseguita:

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 search

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

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}

// Claude's response with citations (omitted in this example)



Richieste batch

Puoi includere lo strumento di ricerca web nella Messages Batches API. Le chiamate allo strumento di ricerca web tramite la Messages Batches API hanno lo stesso prezzo di quelle nelle normali richieste della Messages API.

Per proteggere la capacità condivisa, la Batches API limita le richieste di ricerca web per organizzazione, quindi i batch di grandi dimensioni con molte ricerche potrebbero richiedere più tempo per essere completati. Puoi vedere il limite di velocità della ricerca web della tua organizzazione nella pagina Limiti della Claude Console; contatta il team commerciale da quella pagina per richiedere un limite più elevato. I carichi di lavoro tipici di ricerca web in batch includono l'arricchimento di record con dati web attuali, la ricerca su un ampio elenco di entità e il fondamento o la verifica di un corpus di contenuti rispetto a fonti live.



Utilizzo e prezzi

L'utilizzo della ricerca web viene addebitato in aggiunta all'utilizzo dei token:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

La ricerca web è disponibile sull'API di Claude al costo di 10 $ per 1.000 ricerche, oltre ai costi standard dei token per i contenuti generati dalla ricerca. I risultati della ricerca web recuperati nel corso di una conversazione vengono conteggiati come token di input, sia nelle iterazioni di ricerca eseguite durante un singolo turno sia nei turni successivi della conversazione.

Ogni ricerca web viene conteggiata come un singolo utilizzo, indipendentemente dal numero di risultati restituiti. Se si verifica un errore durante la ricerca web, questa non verrà addebitata.



Passaggi successivi