Strumento di ricerca web

Lo strumento di ricerca web dà a Claude accesso diretto ai contenuti web in tempo reale, permettendogli di rispondere alle domande con informazioni aggiornate 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 finestra di contesto (dynamic filtering, filtraggio dinamico), mantenendo solo le informazioni rilevanti. Il filtraggio dinamico è disponibile con Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6.

Sono disponibili tre versioni dello strumento di ricerca web:

• web_search_20250305: ricerca web di base
• web_search_20260209: aggiunge il filtraggio dinamico
• web_search_20260318: aggiunge il controllo dell'inclusione nella risposta per i flussi di lavoro agentici

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 Zero Data Retention e la relativa configurazione 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 determina quando cercare 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 cerca

Claude cerca quando la richiesta dipende da informazioni attuali, in evoluzione o al di fuori dei 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 verificare qualcosa

Claude risponde direttamente senza cercare 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
• Scambi conversazionali e saluti

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



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 il contenuto rilevante raggiunga la finestra di contesto. Questo riduce l'uso di token nelle richieste con 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 il filtraggio dinamico viene eseguito, l'API fornisce automaticamente l'esecuzione di codice necessaria per la richiesta. Non è necessario aggiungere tu stesso lo strumento di esecuzione di codice a tools. Non ci sono costi aggiuntivi per le chiamate di esecuzione di 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-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_20260318", "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.
  // 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. Su web_search_20260209 e versioni successive il valore predefinito è ["code_execution_20260120"] invece di ["direct"]. Consulta Strumenti server per come configurarlo. web_search_20260318 e versioni successive accettano anche response_inclusion.



Utilizzi massimi

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

Le semplici query fattuali usano tipicamente 1–3 ricerche; le ricerche comparative o su più entità possono usarne 10 o più. Per le ricerche sensibili alla latenza, max_uses: 3 limita i costi troncando raramente. Per gli agenti di ricerca, imposta max_uses a 15–20 oppure omettilo del tutto.



Filtraggio dei domini

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

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



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 a due lettere ISO 3166-1 alpha-2. L'API rifiuta i codici paese non supportati con un errore 400.
• timezone: L'ID del fuso orario IANA.



Inclusione nella risposta

Il parametro response_inclusion controlla come i blocchi dei risultati di ricerca appaiono nella risposta dell'API quando il risultato è stato consumato da una chiamata di esecuzione di codice completata nello stesso turno. Imposta "response_inclusion": "excluded" per eliminare completamente dalla risposta quelle coppie annidate di blocchi server_tool_use e di risultato, riducendo i costi dei token di output per i flussi di lavoro agentici che non hanno bisogno di restituire al client il contenuto grezzo della ricerca. Il valore predefinito è "full". I risultati delle chiamate dirette, o delle chiamate di esecuzione di codice che si sono messe in pausa prima di completarsi, vengono sempre restituiti per intero in modo che possano essere rinviati al turno successivo.

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



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

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 di codice, e ogni coppia annidata server_tool_use e web_search_tool_result porta un campo caller che identifica la chiamata di esecuzione di codice che l'ha effettuata.



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 restituire nelle conversazioni multi-turno

Per continuare una conversazione che contiene risultati di ricerca, invia i blocchi di contenuto dell'assistente esattamente come li hai ricevuti, incluso l'encrypted_content di ogni risultato. L'API decrittografa quel contenuto nei turni successivi per ripristinare i risultati di ricerca nel contesto di Claude. Se encrypted_content è mancante o modificato, la richiesta fallisce con un errore di validazione 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 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 contano ai fini dell'utilizzo dei token di input o output.



Errori

Quando lo strumento di ricerca web incontra un errore (come il raggiungimento dei limiti di velocità), la Claude API restituisce comunque una risposta 200 (successo). L'errore è rappresentato all'interno del corpo della risposta usando 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"
  }
}

In caso di errore, content è un singolo oggetto di errore anziché un elenco di blocchi di risultato. Una ricerca che ha successo 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 di 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
• request_too_large: La richiesta di ricerca è troppo grande, tipicamente a causa di un lungo elenco di filtri di dominio
• 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, invia il messaggio dell'assistente 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 di strumenti parallele, 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 esegue la ricerca nella richiesta successiva. Consulta Combinare strumenti server e strumenti client in un turno.

Per il ciclo lato server e la gestione di 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 Limits nella Claude Console. Per richiedere un limite più alto, contatta il reparto 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
    }
  }
}

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.



Prossimi passi