Lo strumento di ricerca web offre a Claude accesso diretto a contenuti web in tempo reale, permettendogli di rispondere a 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 tramite 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 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 durante una singola richiesta.
  3. Alla fine del suo turno, Claude fornisce una risposta finale con le 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 posso aggiornare un'app web 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 risultati solo 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 effettuate. 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 utilizzi i filtri di dominio:

  • I domini non devono 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 in base alla posizione di un utente.

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

​
Risposta

Ecco un esempio di struttura di risposta:

{
  "role": "assistant",
  "content": [
    // 1. La decisione di Claude di effettuare una ricerca
    {
      "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 della 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": "In base ai risultati della 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, 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 di origine
  • title: Il titolo della pagina di origine
  • page_age: Quando il sito è stato aggiornato l’ultima volta
  • encrypted_content: Contenuto crittografato che deve essere restituito 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 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.

Quando mostri risultati web o informazioni contenute nei risultati web agli utenti finali, le citazioni in linea devono essere 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 frequenza superato
  • invalid_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
  • unavailable: Si è verificato un errore interno

​
Motivo di arresto pause_turn

La risposta può includere un motivo di arresto 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 memorizzerà automaticamente nella cache fino all’ultimo blocco web_search_tool_result durante l’esecuzione dello strumento.

Per conversazioni multi-turno, imposta un punto di interruzione cache_control sull’ultimo blocco web_search_tool_result o dopo di esso per riutilizzare il contenuto memorizzato nella 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 della 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 della cache dopo i risultati di ricerca
messages.append({
    "role": "user",
    "content": "Dovrei aspettarmi pioggia più avanti 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 memorizzati nella cache
# pur essendo ancora in grado di eseguire nuove ricerche se necessario
print(f"Token di lettura dalla cache: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

Con lo streaming abilitato, riceverai 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": ""}}

// Decisione di Claude di effettuare una ricerca

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\":\"ultimi progressi nel quantum computing 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": "Progressi nel Quantum Computing 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 allo strumento di ricerca web tramite l’API Messages Batches hanno lo stesso prezzo di quelle nelle normali richieste dell’API Messages.

​
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 Anthropic a $10 per 1.000 ricerche, più i costi standard dei token per i contenuti generati dalla ricerca. I risultati della ricerca web recuperati durante una conversazione vengono conteggiati come token di input, sia nelle iterazioni di ricerca eseguite durante un singolo turno che nei turni di conversazione successivi.

Ogni ricerca web conta come un utilizzo, indipendentemente dal numero di risultati restituiti. Se si verifica un errore durante la ricerca web, la ricerca web non verrà addebitata.