Strumento di ricerca web

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.

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 di inclusione nella risposta 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 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.

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

Gli esempi seguenti usano web_search_20260318:

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)

Come usare la ricerca web

Queste impostazioni a livello di organizzazione nella Claude Console si applicano solo alle richieste della Messages API. Le sessioni di Claude Managed Agents 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. 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. 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: