Claude Platform Docs
MessaggiStrumenti

Strumento di ricerca web

Offri a Claude l’accesso a contenuti web aggiornati con fonti citate, filtraggio dinamico opzionale e controlli sui domini.

L’utilizzo varia in base al prodotto

Messages API
Aggiungi uno strumento web_search ai tools della richiesta. Impostazioni come max_uses, gli elenchi di domini e user_location vanno su quello strumento.
Managed Agents
Attivo per impostazione predefinita nel toolset dell’agente, senza max_uses, citations o cache_control.

Lo strumento di ricerca web offre a Claude accesso diretto a 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.

Con web_search_20260209 e versioni successive, Claude può scrivere ed eseguire codice che filtra i risultati di ricerca prima che raggiungano la “context window” (finestra di contesto) (filtraggio dinamico, “dynamic filtering”), mantenendo solo le informazioni pertinenti. Il filtraggio dinamico è disponibile con Claude 4.6 e modelli successivi e con Claude Mythos Preview.

Sono disponibili tre versioni dello strumento di ricerca web:

Gli esempi in questa pagina usano web_search_20250305 per la ricerca di base e web_search_20260318 per il filtraggio dinamico.

Per l’idoneità della ricerca web alla conservazione zero dei dati e la relativa configurazione di allowed_callers, consulta Strumenti server.

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

Per verificare se un modello accetta la ricerca web prima di inviare una richiesta, leggi il suo valore capabilities.server_tools.web_search.supported dalla Models API. Utilizzo della Models API descrive il campo.

Come funziona la ricerca web

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

  1. Claude determina quando effettuare una ricerca in base al prompt.
  2. L’API esegue le ricerche e fornisce i risultati a Claude. 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 ricerche

Claude effettua ricerche 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 può essere orientata tramite il tuo “system prompt” (prompt di sistema): puoi incoraggiare Claude a effettuare ricerche più facilmente oppure a preferire risposte dirette. Per imporre un limite, usa max_uses per limitare il numero di ricerche in un turno.

Filtraggio dinamico

Con la ricerca web di base, ogni risultato di ricerca viene caricato nella finestra di contesto di Claude, e gran parte di quel contenuto può essere irrilevante per la richiesta. Con web_search_20260209 o versioni successive, Claude invece scrive ed esegue codice che filtra prima i risultati, in modo che solo i contenuti pertinenti raggiungano la finestra di contesto. Questo riduce l’uso di token nelle richieste che richiedono molte ricerche.

Il filtraggio dinamico esegue la ricerca web dall’interno dell’esecuzione di codice: su web_search_20260209 e versioni successive, il campo allowed_callers dello strumento ha come valore predefinito ["code_execution_20260120"] e, quando viene eseguito il filtraggio dinamico, l’API predispone automaticamente l’esecuzione di codice necessaria per la richiesta. Non è necessario aggiungere manualmente lo strumento di esecuzione del codice a tools. Non ci sono costi aggiuntivi per le chiamate di esecuzione del codice effettuate in questo modo oltre ai costi standard dei token.

Per chiamare la ricerca web direttamente, senza filtraggio dinamico, imposta allowed_callers: ["direct"]. I modelli che non supportano la chiamata programmatica degli strumenti richiedono questa impostazione. Senza di essa, l’API restituisce un errore 400 che ti indica di impostarla.

Gli esempi seguenti usano web_search_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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_20260318", "name": "web_search"}],
)
print(response)

Per sapere come le impostazioni di ricerca web della tua organizzazione si applicano alle sessioni di Claude Managed Agents, consulta Limitare i domini di ricerca web e recupero web.

Fornisci lo strumento di ricerca web nella tua richiesta API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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:

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

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

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "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"
  }
}

Tutte le versioni dello strumento di ricerca web accettano allowed_callers, che controlla se Claude chiama la ricerca web direttamente o dall’esecuzione di codice tramite il filtraggio dinamico. Su web_search_20260209 e versioni successive il valore predefinito è ["code_execution_20260120"] anziché ["direct"]. Consulta ZDR e allowed_callers per sapere come configurarlo. web_search_20260318 e versioni successive accettano anche response_inclusion.

Utilizzi massimi

Il parametro max_uses limita il numero di ricerche in un singolo turno. Le query su un singolo fatto usano in genere 1–3 ricerche; le ricerche comparative o su più entità possono usarne 10 o più.

Le ricerche non riuscite vengono conteggiate nel limite. Se Claude chiama la ricerca web direttamente più volte di quanto consentito, web_search_tool_result è un errore con il codice di errore max_uses_exceeded. Se Claude chiama la ricerca web dall’esecuzione di codice più volte di quanto consentito, l’esecuzione del codice termina con un errore.

Un turno può estendersi su più richieste. Una richiesta continua un turno quando riprende dopo pause_turn o quando il suo ultimo messaggio contiene solo blocchi tool_result. Le ricerche delle richieste precedenti in quel turno vengono conteggiate nel limite, a meno che Claude non le abbia eseguite dall’esecuzione di codice tramite il filtraggio dinamico.

Filtraggio dei domini

Fornisci allowed_domains oppure blocked_domains, non entrambi. Se una richiesta li include entrambi, l’API restituisce un errore 400. Le voci sono domini semplici con un percorso opzionale, ad esempio example.com o example.com/blog, senza schema.

Per le regole complete di filtraggio dei domini, consulta Filtraggio dei domini nella guida Strumenti server.

Su Claude Managed Agents, imposta questi campi sulla voce web_search del set di strumenti dell’agente; consulta Limitare i domini di ricerca web e recupero web.

Localizzazione

Il parametro user_location ti consente di localizzare i risultati di ricerca in base alla posizione di un utente. Fornisci almeno uno tra city, region, country o timezone.

  • type: Il tipo di posizione (deve essere approximate)
  • city: Il nome della città
  • region: La regione o lo stato
  • country: Il codice paese di due lettere ISO 3166-1 alpha-2 (l’API rifiuta un codice non supportato con un errore 400)
  • timezone: L’ID del fuso orario IANA

Su Claude Managed Agents, anche la voce web_search del set di strumenti dell’agente accetta user_location; consulta le impostazioni degli strumenti web.

Inclusione nella risposta

Il parametro response_inclusion controlla come i blocchi dei risultati di ricerca appaiono nella risposta dell’API quando il risultato è stato utilizzato da una chiamata di esecuzione di codice completata nella stessa risposta. Imposta "response_inclusion": "excluded" per eliminare completamente dalla risposta quelle coppie annidate di blocchi server_tool_use e di risultato, per i flussi di lavoro agentici che non hanno bisogno del contenuto grezzo delle ricerche. L’utilizzo dei token non cambia, perché Claude legge l’output del codice anziché questi blocchi. Il valore predefinito è "full". L’API restituisce sempre per intero i risultati delle chiamate dirette, o delle chiamate di esecuzione di codice che si sono messe in pausa prima di essere completate, in modo che tu possa reinviarli nella richiesta successiva.

JSON
{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}

Risposta

Ecco un esempio di struttura della risposta:

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

Questo esempio mostra una ricerca diretta. Quando una ricerca viene eseguita tramite il filtraggio dinamico, la risposta contiene anche i blocchi di risultato dello strumento di esecuzione del codice, e ogni coppia annidata di server_tool_use e web_search_tool_result contiene un campo caller che identifica la chiamata di esecuzione di codice che l’ha generata.

Risultati di ricerca

I risultati di ricerca includono:

  • url: L’URL della pagina di origine
  • title: Il titolo della pagina di origine
  • page_age: Quando il sito è stato aggiornato l’ultima volta
  • encrypted_content: Contenuto crittografato che devi reinviare nelle conversazioni multi-turno

Per continuare una conversazione che contiene risultati di ricerca, reinvia i blocchi di contenuto dell’assistente esattamente come li hai ricevuti, incluso l’encrypted_content di ciascun risultato. L’API decrittografa quel contenuto nelle richieste successive per ripristinare i risultati di ricerca nel contesto di Claude. Se encrypted_content è mancante o modificato, la richiesta fallisce con un errore di convalida 400.

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 reinviato nelle 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 di output.

Errori

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

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

In caso di errore, content è un singolo oggetto di errore anziché un elenco di blocchi di risultato. Una ricerca che ha esito positivo ma non trova risultati restituisce un elenco content vuoto, non un errore.

Questi sono i possibili codici di errore:

  • too_many_requests: Limite di velocità superato
  • invalid_tool_input: Parametro della query di ricerca non valido
  • max_uses_exceeded: Superato il numero massimo di utilizzi dello strumento di ricerca web
  • query_too_long: La query supera la lunghezza massima
  • request_too_large: La richiesta di ricerca è troppo grande, in genere a causa di un lungo elenco di filtri dei domini
  • unavailable: Si è verificato un errore interno

Motivo di arresto pause_turn

L’API può mettere in pausa un turno di ricerca di lunga durata e restituire stop_reason: "pause_turn". Per continuare, reinvia il messaggio dell’assistente messo in pausa senza modifiche in una nuova richiesta.

Se Claude chiama la ricerca web e uno dei tuoi strumenti client nello stesso gruppo di chiamate parallele agli strumenti, l’API restituisce invece stop_reason: "tool_use" e non esegue ancora la ricerca. Per continuare, restituisci i risultati degli strumenti client e l’API eseguirà la ricerca nella richiesta successiva. Consulta Combinare strumenti server e strumenti client in un unico turno.

Per il ciclo lato server e la gestione di pause_turn, consulta Il ciclo lato server e pause_turn nella guida Strumenti server.

Cache dei prompt

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

Streaming

Con lo streaming abilitato, ricevi gli eventi di ricerca come parte dello stream. C’è una pausa mentre la ricerca viene eseguita:

Output
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 runs

// 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 Message Batches API. Le chiamate allo strumento di ricerca web tramite la Message Batches API hanno lo stesso prezzo di quelle nelle normali richieste alla Messages API.

Per proteggere la capacità condivisa, la Batches API limita le richieste di ricerca web per ogni 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 di richieste della Claude Console. Per richiedere un limite più alto, contatta il team vendite da quella pagina.

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
    }
  }
}

Sulla Claude API, la ricerca web costa $10 USD ogni 1.000 ricerche, più i costi standard dei token per i contenuti generati dalla ricerca. I risultati della ricerca vengono conteggiati come token di input, sia mentre Claude continua a cercare all’interno di un turno sia nei turni successivi della conversazione.

Ogni ricerca web conta come un singolo utilizzo, indipendentemente dal numero di risultati restituiti. Una ricerca web che non riesce a causa di un errore non viene fatturata.

Passaggi successivi

Recupera e leggi contenuti da URL specifici per arricchire il contesto di Claude con contenuti web in tempo reale.

Lavora con gli strumenti eseguiti da Anthropic: blocchi server_tool_use, continuazione con pause_turn e filtraggio dei domini.

Elenco degli strumenti forniti da Anthropic e riferimento per le proprietà opzionali della definizione degli strumenti.

Disponibilità

Strumento di ricerca web
API
  • Messages API
  • Managed Agents
Modelli
  • Tutti i modelli

Endpoint applicabili

  • /v1/messages con lo strumento web_search
Conservazione zero dei datiIdoneo

Esclude Modelli coperti

Risultati della ricerca web in tempo reale restituiti nella risposta dell’API. Il filtro dinamico per la ricerca web non è idoneo per ZDR o HIPAA.

HIPAAIdoneo

Il filtro dinamico per la ricerca web non è idoneo per ZDR o HIPAA.

Questa pagina ti è stata utile?