---
title: Strumento di ricerca web
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool
description: Offri a Claude l'accesso a contenuti web aggiornati con fonti citate, filtraggio dinamico opzionale e controlli sui domini.
featureMetadata:
  status: stable
  zdr:
    eligibility: eligible
    note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). 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.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
    Claude Models on Google Cloud (Google managed):
      availability: stable
      note: Solo lo strumento di ricerca web di base (`web_search_20250305`), senza filtro dinamico.
    Microsoft Foundry:
      availability: stable
      note: Solo lo strumento di ricerca web di base (`web_search_20250305`), senza filtro dinamico.
---

**Supporto API**: 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](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 dell’[inclusione nella risposta](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#response-inclusion) 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.

<Note>
  Per [Claude Mythos Preview](https://anthropic.com/glasswing), la ricerca web è supportata sulla Claude API, su Claude Models on Google Cloud (Google managed) e su Microsoft Foundry.
</Note>

Per l’idoneità della ricerca web alla conservazione zero dei dati e la relativa configurazione di `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 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`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#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](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 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.

<Note>
  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), su [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed) 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 Claude Models on Google Cloud (Google managed), è disponibile solo lo strumento di ricerca web di base (senza filtraggio dinamico).
</Note>

Gli esempi seguenti usano `web_search_20260318`:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 UserMessageParam { 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: 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: Anthropic::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
  ```
</CodeGroup>

## Come usare la ricerca web

<Note>
  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 ricerche. Se è disabilitata, una richiesta alla Messages API che include lo strumento fallisce con un errore 400 `invalid_request_error` che indica che la ricerca web non è abilitata, anziché con 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.
</Note>

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](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions).

Fornisci lo strumento di ricerca web nella tua richiesta API:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 4096,
      "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 4096 \
    --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=4096,
      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: 4096,
    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 = 4096,
      Messages = [new UserMessageParam { 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: 4096,
  	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(4096L)
          .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: 4096,
      messages: [
          ['role' => 'user', 'content' => "What's the weather in NYC?"],
      ],
      model: 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: Anthropic::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
    }]
  )
  puts message
  ```
</CodeGroup>

## 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
  "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"]` anziché `["direct"]`. Consulta [ZDR e allowed\_callers](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 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`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#dynamic-filtering).

### 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](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 sulla voce `web_search` del set di strumenti dell’agente; consulta [Limitare i domini di ricerca web e recupero web](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 di due lettere [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (l’API rifiuta un codice non supportato 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, anche la voce `web_search` del set di strumenti dell’agente accetta `user_location`; consulta le [impostazioni degli strumenti web](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#settings).

### Inclusione nella risposta

<Note>
  Richiede `web_search_20260318` o versioni successive.
</Note>

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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool) 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 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 del 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` 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.

<Note>
  Quando mostri gli output dell’API direttamente agli utenti finali, è necessario includere le citazioni alla fonte originale. Se apporti modifiche agli output dell’API, anche rielaborandoli o combinandoli con il tuo materiale prima di mostrarli agli utenti finali, mostra le citazioni in modo appropriato sulla base di una consultazione con il tuo team legale.
</Note>

### 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:

```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é 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](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 la cache dei prompt](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-use-with-prompt-caching).

## Streaming

Con lo streaming abilitato, ricevi gli eventi di ricerca come parte dello stream. C’è 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 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](https://platform.claude.com/docs/it/build-with-claude/batch-processing). 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](https://platform.claude.com/usage/limits) 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:

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

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

<CardGroup cols={3}>
  <Card title="Strumento di recupero web" icon="link" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-fetch-tool">
    Recupera e leggi contenuti da URL specifici per arricchire il contesto di Claude con contenuti web in tempo reale.
  </Card>

  <Card title="Strumenti server" icon="tool" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools">
    Lavora con gli strumenti eseguiti da Anthropic: blocchi `server_tool_use`, continuazione con `pause_turn` e filtraggio dei domini.
  </Card>

  <Card title="Riferimento degli strumenti" icon="book" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference">
    Elenco degli strumenti forniti da Anthropic e riferimento per le proprietà opzionali della definizione degli strumenti.
  </Card>
</CardGroup>

## Disponibilità

La funzionalità Strumento di ricerca web è disponibile su tutti i modelli e idonea per conservazione zero dei dati e preparazione HIPAA.

### Supporto API

#### [Messages API](https://platform.claude.com/docs/it/build-with-claude/working-with-messages)

* Disponibilità: Disponibile
* Utilizzo: Aggiungi uno strumento `web_search` ai `tools` della richiesta. Impostazioni come `max_uses`, gli elenchi di domini e `user_location` vanno su quello strumento.

| Stato                   | Piattaforme cloud                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Disponibile             | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry) |
| Disponibile<sup>1</sup> | [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry (hosted on Azure)](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry)                                                                                                                               |

1. Solo lo strumento di ricerca web di base (`web_search_20250305`), senza filtro dinamico.

#### [Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview)

* Disponibilità: Disponibile
* Utilizzo: Fa parte del toolset dell’agente ed è attivo per impostazione predefinita una volta aggiunto il toolset. Gli elenchi di domini e `user_location` vanno nella voce `web_search` del toolset; `max_uses`, `citations` e `cache_control` non sono disponibili.

| Stato       | Piattaforme cloud                                                                                                                                                                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Disponibile | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |

### Gestione dei dati

[Panoramica sulla gestione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#feature-eligibility)

| Elemento | Conservazione zero dei dati                                                                                                                             | HIPAA                                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Stato    | Idoneo (esclude [Modelli coperti](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Idoneo                                                              |
| Dettagli | 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.      | Il filtro dinamico per la ricerca web non è idoneo per ZDR o HIPAA. |

Endpoint applicabili:

* `/v1/messages` con lo strumento `web_search`
