Limitare i domini di web search e web fetch

Per controllare quali siti possono raggiungere gli strumenti web dell'agente, imposta un elenco di domini sulle voci web_search e web_fetch del toolset dell'agente. Ciascuna di queste voci configs accetta uno di due elenchi:

• allowed_domains: Lo strumento può raggiungere solo questi host.
• blocked_domains: Lo strumento non può mai raggiungere questi host.

Ogni strumento ha il proprio elenco, quindi web_search e web_fetch possono avere restrizioni diverse.

Impostare elenchi di domini su un agente

L'esempio seguente crea un agente che limita web_search a due siti e blocca un host per web_fetch. Imposta anche user_location e max_content_tokens, descritti in Impostazioni. L'esempio stampa poi l'array configs dalla risposta.

ant apply agent.md

---
name: Research Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_search
        name: web_search
        allowed_domains: [docs.example.com, arxiv.org]
        user_location:
          type: approximate
          country: US
          timezone: America/Los_Angeles
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000
---

In un ambiente cloud con networking limited, anche gli allowed_hosts dell'ambiente si applicano a web_search e web_fetch. La creazione di una sessione fallisce con un errore 400 quando gli allowed_domains di uno strumento web abilitato contengono una voce che non rientra in allowed_hosts. Lo stesso vale per un aggiornamento della sessione che aggiunge una voce di questo tipo. Per risolvere, aggiungi l'host a allowed_hosts oppure rimuovi la voce da allowed_domains. In fase di esecuzione, una chiamata web_fetch per un URL su un host che non corrisponde a allowed_hosts restituisce un risultato di errore url_not_allowed. web_search omette i risultati provenienti da tali host. I due elenchi effettuano la corrispondenza in modo diverso: la voce di uno strumento copre i suoi sottodomini, mentre una voce di allowed_hosts corrisponde a un unico host esatto a meno che non inizi con *.. Ad esempio, la voce di strumento docs.example.com non rientra in un allowed_hosts pari a ["example.com"], ma rientra in ["docs.example.com"] o ["*.example.com"].

Nella Claude Console, imposta i domini consentiti o bloccati dalle righe web_search e web_fetch della scheda Built-in tools nel modulo dell'agente. Imposta max_content_tokens e user_location nella vista Raw della configurazione dell'agente.

Impostazioni

Oltre a enabled e permission_policy, le voci degli strumenti web accettano le seguenti impostazioni:

Per sapere come gli SDK tipizzano queste voci, consulta Tipi delle voci di configurazione negli SDK.

Quando un dominio non è consentito

web_search omette i risultati che il suo elenco di domini non consente. Una chiamata web_fetch per un URL che il suo elenco di domini non consente restituisce un risultato di errore all'agente. L'evento agent.tool_result ha is_error: true e il suo contenuto indica il codice di errore url_not_allowed.

Regole degli elenchi di domini

Queste regole si applicano allo stesso modo a allowed_domains e blocked_domains. Una richiesta che ne viola una viene rifiutata, come descritto in Errori di convalida.

• Un elenco per voce: Imposta allowed_domains oppure blocked_domains su una voce, non entrambi.
• Dimensione dell'elenco: Ogni elenco contiene da 1 a 64 domini, ciascuno da 1 a 255 caratteri.
• Nessun elenco vuoto: Per non applicare alcuna restrizione, ometti il campo o invia null.
• Nessun duplicato: Un dominio può comparire una sola volta in un elenco. www.example.com e example.com contano come domini diversi.

A cosa corrisponde un dominio elencato

Un dominio elencato corrisponde a quell'host e a tutti i suoi sottodomini. example.com copre docs.example.com, ma docs.example.com non copre example.com né api.example.com.

Un www. iniziale è un sottodominio come qualsiasi altro, quindi www.example.com non copre example.com. Elenca il dominio semplice per coprirli entrambi.

I nomi host vengono confrontati senza distinzione tra maiuscole e minuscole.

Formato del dominio

Ogni dominio è un nome di dominio registrabile, o un suo sottodominio, scritto come semplice nome host. Può contenere lettere ASCII, cifre, trattini, trattini bassi e punti. Una singola / finale viene ignorata.

Un dominio viene rifiutato anche se contiene credenziali o spazi, oppure se una delle sue etichette inizia o termina con un trattino. Vengono rifiutati anche localhost e gli host che terminano con .localhost, .local, .internal, .localdomain o .invalid.

Suffissi di percorso sui domini di web search

Un dominio web_search può includere un suffisso di percorso, come example.com/blog. Il percorso non può contenere spazi, ?, # o uno qualsiasi dei caratteri $ , | ^ !.

Preferisci nomi host semplici anche per web_search. Il provider di ricerca confronta i suffissi di percorso come pattern URL anziché come regole rigide sugli host.

Errori di convalida

L'API convalida queste impostazioni quando crei un agente o aggiorni un agente. Le convalida anche quando crei o aggiorni una sessione che fornisce tools.

Le violazioni di formato e di limiti vengono rifiutate con un errore 400 invalid_request_error:

Nelle stesse richieste, l'API rifiuta anche tre impostazioni che dipendono dai provider di ricerca e recupero:

• Un dominio in allowed_domains a cui il crawler di Anthropic non è autorizzato ad accedere.
• Un user_location.country che il provider di ricerca non supporta. Il messaggio termina con user_location.country: not a country the search provider supports.
• Un user_location.timezone che non è un nome IANA valido.

In un ambiente cloud con networking limited, la creazione e l'aggiornamento della sessione verificano anche allowed_domains rispetto agli allowed_hosts dell'ambiente. Consulta la regola in Impostare elenchi di domini su un agente.

Quando un'impostazione accettata non è più valida

La sessione verifica nuovamente la configurazione quando inizializza lo strumento per la prima volta. Se un'impostazione accettata in precedenza non è più valida in quel momento, la sessione emette un evento session.error. Torna quindi a idle senza riprovare.

Per continuare la sessione:

1. Correggi l'impostazione aggiornando gli strumenti della sessione.
2. Aggiorna anche l'agente, in modo che le nuove sessioni inizino con la configurazione corretta.
3. Invia un nuovo user.message.

Sessioni multiagente e orientate agli esiti

In una sessione multiagente, ogni elenco di domini che si applica a un thread viene applicato contemporaneamente. Un agente nel roster del coordinatore è vincolato da tre insiemi di elenchi:

• I propri allowed_domains e blocked_domains
• Quelli di qualsiasi agente che lo ha chiamato
• Gli elenchi correnti del coordinatore

Le impostazioni si combinano come segue:

Un agente del roster può quindi restringere ciò che uno strumento raggiunge, ma mai ampliarlo:

• Un agente del roster che imposta blocked_domains mantiene gli allowed_domains del coordinatore e blocca quegli host al loro interno.
• Un agente del roster che imposta i propri allowed_domains può raggiungere solo gli host coperti sia dal proprio elenco sia da quello del coordinatore.

Una voce di roster {"type": "self"} non ha impostazioni web proprie e segue le impostazioni correnti del coordinatore.

Se gli elenchi allowed_domains combinati non hanno alcun dominio in comune, lo strumento rimane disponibile per quell'agente ma ogni chiamata fallisce. Ogni chiamata restituisce un errore url_not_allowed che indica che nessun dominio è consentito. La descrizione dello strumento comunica lo stesso al modello. Per evitarlo, mantieni gli allowed_domains di ogni agente del roster all'interno di quelli del coordinatore.

Il grader nelle sessioni orientate agli esiti viene eseguito senza web_search e web_fetch, indipendentemente da queste impostazioni.

Modificare gli elenchi durante la sessione

Puoi modificare gli elenchi su una sessione inattiva aggiornandone gli strumenti. I nuovi elenchi si applicano al resto della sessione.

In una sessione multiagente, ogni thread applica i nuovi elenchi a partire dal turno successivo. L'aggiornamento non modifica gli elenchi propri di un agente del roster. Questi rimangono come li ha impostati la definizione dell'agente al momento della creazione della sessione.

Differenze rispetto agli strumenti della Messages API

Queste impostazioni usano gli stessi campi allowed_domains e blocked_domains del filtraggio dei domini negli strumenti server della Messages API. Managed Agents differisce in quattro modi:

• Ogni elenco è limitato a 64 domini.
• I domini elencati per web_fetch non possono includere un percorso.
• I domini devono essere ASCII. La Messages API accetta voci Unicode, anche se ne sconsiglia l'uso.
• max_uses, citations e cache_control non sono disponibili nel toolset.

Passaggi successivi