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. Claude cita automaticamente le fonti dai risultati di ricerca come parte della sua risposta.

Ti preghiamo di contattarci attraverso il nostro modulo di feedback per condividere la tua esperienza con lo strumento di ricerca web.

​
Modelli supportati

La ricerca web è disponibile su:

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (nuovo) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Come funziona la ricerca web

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

  1. Claude decide quando cercare basandosi sul prompt.
  2. L’API esegue le ricerche e fornisce a Claude i risultati. Questo processo può ripetersi più volte durante una singola richiesta.
  3. Alla fine del suo turno, Claude fornisce una risposta finale con fonti citate.

​
Come utilizzare la ricerca web

L’amministratore della tua organizzazione deve abilitare la ricerca web nella Console.

Fornisci lo strumento di ricerca web nella tua richiesta API:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Come aggiorno una web app a TypeScript 5.5?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
Definizione dello strumento

Lo strumento di ricerca web supporta i seguenti parametri:

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

  // Opzionale: Limita il numero di ricerche per richiesta
  "max_uses": 5,

  // Opzionale: Includi solo risultati da questi domini
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Opzionale: Non includere mai risultati da questi domini
  "blocked_domains": ["untrustedsource.com"],

  // Opzionale: Localizza i risultati di ricerca
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

​
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 sarà un errore con il codice di errore max_uses_exceeded.

​
Filtraggio dei domini

Quando si utilizzano i filtri di dominio:

  • I domini non dovrebbero includere lo schema HTTP/HTTPS (usa example.com invece di https://example.com)
  • I sottodomini sono automaticamente inclusi (example.com copre docs.example.com)
  • I sottopercorsi sono supportati (example.com/blog)
  • Puoi utilizzare allowed_domains o blocked_domains, ma non entrambi nella stessa richiesta.

​
Localizzazione

Il parametro user_location ti permette di localizzare i risultati di ricerca basandosi sulla posizione di un utente.

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

​
Risposta

Ecco un esempio di struttura di risposta:

{
  "role": "assistant",
  "content": [
    // 1. Decisione di Claude di cercare
    {
      "type": "text",
      "text": "Cercherò quando è nato Claude Shannon."
    },
    // 2. La query di ricerca utilizzata
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon data di nascita"
      }
    },
    // 3. Risultati di ricerca
    {
      "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": "30 aprile 2025"
        }
      ]
    },
    {
      "text": "Basandomi sui risultati di ricerca, ",
      "type": "text"
    },
    // 4. Risposta di Claude con citazioni
    {
      "text": "Claude Shannon è nato il 30 aprile 1916, a 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 (30 aprile 1916 – 24 febbraio 2001) è stato un matematico americano, ingegnere elettrico, informatico, crittografo e i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

​
Risultati di ricerca

I risultati di ricerca includono:

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

​
Citazioni

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

  • url: L’URL della fonte citata
  • title: Il titolo della fonte citata
  • encrypted_index: Un riferimento che deve essere ripassato per 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 verso l’utilizzo di token di input o output.

Quando mostri risultati web o informazioni contenute nei risultati web agli utenti finali, le citazioni inline devono essere rese chiaramente visibili e cliccabili nella tua interfaccia utente.

​
Errori

Se si verifica un errore durante la ricerca web, riceverai una risposta che assume la seguente forma:

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

Questi sono i possibili codici di errore:

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

​
Motivo di stop pause_turn

La risposta può includere un motivo di stop pause_turn, che indica che l’API ha messo in pausa un turno di lunga durata. Puoi fornire la risposta così com’è in una richiesta successiva per permettere a Claude di continuare il suo turno, o modificare il contenuto se desideri interrompere la conversazione.

​
Caching dei prompt

La ricerca web funziona con il caching dei prompt. Per abilitare il caching dei prompt, aggiungi almeno un punto di interruzione cache_control nella tua richiesta. Il sistema metterà automaticamente in cache fino all’ultimo blocco web_search_tool_result quando esegue lo strumento.

Per conversazioni multi-turno, imposta un punto di interruzione cache_control su o dopo l’ultimo blocco web_search_tool_result per riutilizzare il contenuto in cache.

Ad esempio, per utilizzare il caching dei prompt con la ricerca web per una conversazione multi-turno:

import anthropic

client = anthropic.Anthropic()

# Prima richiesta con ricerca web e punto di interruzione cache
messages = [
    {
        "role": "user",
        "content": "Qual è il tempo attuale a San Francisco oggi?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# Aggiungi la risposta di Claude alla conversazione
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Seconda richiesta con punto di interruzione cache dopo i risultati di ricerca
messages.append({
    "role": "user",
    "content": "Dovrei aspettarmi pioggia più tardi questa settimana?",
    "cache_control": {"type": "ephemeral"}  # Cache fino a questo punto
})

response2 = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# La seconda risposta beneficerà dei risultati di ricerca in cache
# pur essendo ancora in grado di eseguire nuove ricerche se necessario
print(f"Token di lettura cache: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

Con lo streaming abilitato, riceverai eventi di ricerca come parte del flusso. 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": ""}}

// Decisione di Claude di cercare

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

// Query di ricerca in streaming
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"ultime scoperte nel calcolo quantistico 2025\"}"}}

// Pausa mentre la ricerca viene eseguita

// Risultati di ricerca in streaming
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": "Scoperte nel Calcolo Quantistico nel 2025", "url": "https://example.com"}]}}

// Risposta di Claude con citazioni (omessa in questo esempio)

​
Richieste batch

Puoi includere lo strumento di ricerca web nell’API Messages Batches. Le chiamate dello strumento di ricerca web attraverso l’API Messages Batches hanno lo stesso prezzo di quelle nelle richieste API Messages regolari.

​
Utilizzo e prezzi

Web search usage is charged in addition to token usage:

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

Web search is available on the Anthropic API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.