---
title: Strumento di ricerca web
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool
description: Dai a Claude accesso a contenuti web aggiornati con fonti citate, filtraggio dinamico opzionale e controlli sui domini.
---
Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
Lo strumento di ricerca web ("web search tool") dà a Claude accesso diretto a contenuti web in tempo reale, consentendogli di rispondere a domande con informazioni aggiornate oltre la sua data 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**, o "dynamic filtering"), mantenendo solo le informazioni rilevanti. Il filtraggio dinamico è disponibile con i modelli Claude 4.6 e successivi e con [Claude Mythos Preview](https://anthropic.com/glasswing).
Sono disponibili tre versioni dello strumento di ricerca web:
* `web_search_20250305`: ricerca web di base
* `web_search_20260209`: aggiunge il [filtraggio dinamico](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#dynamic-filtering)
* `web_search_20260318`: aggiunge il controllo di [inclusione nella risposta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#response-inclusion) per 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 [Claude Mythos Preview](https://anthropic.com/glasswing), la ricerca web è supportata sulla Claude API, Google Cloud e Microsoft Foundry. La ricerca web non è disponibile per Mythos Preview su Amazon Bedrock o [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws).
Per l'idoneità della ricerca web alla Zero Data Retention e la relativa configurazione `allowed_callers`, consulta [Strumenti server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers).
Per il supporto dei modelli, consulta il [Riferimento degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference).
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](https://platform.claude.com/docs/it/models/overview#using-the-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 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 fonti citate.
### Quando Claude effettua ricerche
Claude effettua ricerche 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 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 "system prompt" (prompt di sistema): puoi incoraggiare Claude a cercare più prontamente o a preferire risposte dirette. Per un vincolo rigido, usa `max_uses` per limitare il numero di ricerche per ciascuna 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 i contenuti rilevanti raggiungano 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool): 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 predispone automaticamente l'esecuzione di codice necessaria per la richiesta. Non devi 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.
Lo strumento di ricerca web (con e senza filtraggio dinamico) è disponibile sulla Claude API, su [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws) e su [Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry). Su Microsoft Foundry, i deployment [ospitati su Azure](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) supportano solo lo strumento di ricerca web di base (`web_search_20250305`, senza filtraggio dinamico). I deployment ospitati su Anthropic supportano tutte le versioni. Su Google Cloud, è disponibile solo lo strumento di ricerca web di base (senza filtraggio dinamico). La ricerca web non è disponibile su Amazon Bedrock.
Gli esempi seguenti usano `web_search_20260318`:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"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"
}]
}'
```
```bash CLI
ant messages create <<'YAML'
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
YAML
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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" }]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [new() { Role = Role.User, Content = "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." }],
Tools = [new ToolUnion(new WebSearchTool20260318())]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")),
},
Tools: []anthropic.ToolUnionParam{
{OfWebSearchTool20260318: &anthropic.WebSearchTool20260318Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.WebSearchTool20260318;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")
.addTool(WebSearchTool20260318.builder().build())
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.'],
],
model: 'claude-opus-5-5',
tools: [
[
'type' => 'web_search_20260318',
'name' => 'web_search',
],
],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = 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"
}]
)
puts message
```
## Come usare la ricerca web
La ricerca web è abilitata per la tua organizzazione, a meno che un amministratore non l'abbia disabilitata nella [Claude Console](https://platform.claude.com/settings/capabilities), dove può anche limitare i domini in cui effettua le ricerche. Se è disabilitata, una richiesta che include lo strumento non va a buon fine e restituisce un errore 400 `invalid_request_error` che indica che la ricerca web non è abilitata, anziché un [codice di errore](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#errors) all'interno di un risultato di ricerca.
Queste impostazioni a livello di organizzazione nella Claude Console si applicano solo alle richieste della Messages API. Le sessioni di [Claude Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview) usano invece gli elenchi `allowed_domains` e `blocked_domains` per singolo strumento nel toolset dell'agente; consulta [Limitare i domini di web search e web fetch](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions). Per una sessione in un ambiente cloud con networking `limited`, anche gli `allowed_hosts` dell'ambiente si applicano a `web_search` e `web_fetch`; consulta [Networking](https://platform.claude.com/docs/it/managed-agents/environments#networking). Gli elenchi per singolo strumento limitano ulteriormente questi strumenti, all'interno degli host consentiti da `allowed_hosts`.
Fornisci lo strumento di ricerca web nella tua richiesta API:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "What is the weather in NYC?"
}
],
"tools": [{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: What is the weather in NYC?}' \
--tool '{type: web_search_20250305, name: web_search, max_uses: 5}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: "What's the weather in NYC?"
}
],
tools: [
{
type: "web_search_20250305",
name: "web_search",
max_uses: 5
}
]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "What's the weather in NYC?" }],
Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 5 })]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in NYC?")),
},
Tools: []anthropic.ToolUnionParam{
{OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{
MaxUses: anthropic.Int(5),
}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.WebSearchTool20250305;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("What's the weather in NYC?")
.addTool(WebSearchTool20250305.builder()
.maxUses(5L)
.build())
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "What's the weather in NYC?"],
],
model: 'claude-opus-5-5',
tools: [
[
'type' => 'web_search_20250305',
'name' => 'web_search',
'max_uses' => 5,
],
],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{ role: "user", content: "What's the weather in NYC?" }
],
tools: [{
type: "web_search_20250305",
name: "web_search",
max_uses: 5
}]
)
puts message
```
## Definizione dello strumento
Lo strumento di ricerca web supporta i seguenti parametri:
```json JSON
{
"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 tramite il [filtraggio dinamico](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#dynamic-filtering). Su `web_search_20260209` e versioni successive il valore predefinito è `["code_execution_20260120"]` invece di `["direct"]`. Consulta [Strumenti server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers) per sapere come configurarlo. `web_search_20260318` e versioni successive accettano anche [`response_inclusion`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#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 query fattuali semplici usano tipicamente 1–3 ricerche; le ricerche comparative o su più entità possono usarne 10 o più. Per indicazioni sulla scelta di un valore, consulta [Strumenti server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools).
### 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, ad esempio `example.com` o `example.com/blog`, senza schema.
Per le regole complete di filtraggio dei domini, consulta [Filtraggio dei domini](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#domain-filtering) nella guida Strumenti server.
Su [Claude Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview), imposta questi campi nella voce `web_search` del toolset dell'agente; consulta [Limitare i domini di web search e web fetch](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions).
### 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). L'API rifiuta i codici paese non supportati con un errore 400.
* `timezone`: L'[ID del fuso orario IANA](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
Su Claude Managed Agents, la voce `web_search` del toolset dell'agente accetta un oggetto `user_location` con gli stessi campi. L'API rifiuta un codice `country` non supportato con un errore 400 quando crei o aggiorni l'agente, oppure quando crei o aggiorni una sessione che fornisce l'impostazione. Consulta le [impostazioni degli strumenti web](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#settings).
### Inclusione nella risposta
Richiede `web_search_20260318` o versioni successive.
Il parametro `response_inclusion` controlla come i blocchi dei risultati di ricerca appaiono nella risposta API quando il risultato è stato consumato da una chiamata di [esecuzione di codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool) completata nello stesso turno. Imposta `"response_inclusion": "excluded"` per eliminare completamente dalla risposta quelle coppie annidate di `server_tool_use` e blocchi 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 delle ricerche. Il valore predefinito è `"full"`. I risultati delle chiamate dirette, o delle chiamate di esecuzione di codice messe in pausa prima del completamento, vengono sempre restituiti per intero in modo che possano essere rinviati al turno successivo.
```json JSON
{
"tools": [
{
"type": "web_search_20260318",
"name": "web_search",
"response_inclusion": "excluded"
}
]
}
```
## Risposta
Ecco un esempio di struttura della risposta:
```json 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#dynamic-filtering), la risposta contiene anche i blocchi di risultato dello [strumento di esecuzione di codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool), e ogni coppia annidata di `server_tool_use` e `web_search_tool_result` riporta 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 rinviare nelle conversazioni multi-turno
Per continuare una conversazione che contiene risultati di ricerca, rinvia i blocchi di contenuto dell'assistente esattamente come li hai ricevuti, incluso l'`encrypted_content` di ciascun 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 rinviato 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'uso dei token di input o di output.
Quando mostri gli output dell'API direttamente agli utenti finali, devono essere incluse le citazioni alla fonte originale. Se apporti modifiche agli output dell'API, anche rielaborandoli o combinandoli con materiale tuo prima di mostrarli agli utenti finali, mostra le citazioni in modo appropriato in base alla consultazione con il tuo team legale.
### Errori
Quando lo strumento di ricerca web incontra un errore (come il raggiungimento dei "rate limit", ovvero limiti di velocità), la Claude API restituisce comunque una risposta 200 (successo). L'errore è rappresentato nel corpo della risposta usando la seguente struttura:
```json 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é una lista di blocchi di risultato. Una ricerca che ha successo ma non trova risultati restituisce una lista `content` vuota, 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`: 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 una lunga lista 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, rinvia 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 parallele agli strumenti, l'API restituisce invece `stop_reason: "tool_use"` e non esegue ancora la ricerca. Per continuare, restituisci i risultati dello strumento client, e l'API esegue la ricerca nella richiesta successiva. Consulta [Combinare strumenti server e strumenti client in un turno](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn).
Per il ciclo lato server e la gestione di `pause_turn`, consulta [Il ciclo lato server e pause\_turn](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-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 cache dei prompt](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-use-with-prompt-caching).
## Streaming
Con lo streaming abilitato, riceverai gli eventi di ricerca come parte dello stream. Ci sarà una pausa mentre la ricerca viene eseguita:
```sse 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 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](https://platform.claude.com/docs/it/build-with-claude/batch-processing). 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 di velocità](https://platform.claude.com/usage/limits) della 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:
```json
{
"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 sulla Claude API a **$10 per 1.000 ricerche**, più i 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 conta come un singolo utilizzo, indipendentemente dal numero di risultati restituiti. Se si verifica un errore durante la ricerca web, la ricerca web non verrà fatturata.
## Prossimi passi
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 di pause\_turn e filtraggio dei domini.
Elenco degli strumenti forniti da Anthropic e riferimento per le proprietà opzionali di definizione degli strumenti.