Limitare i domini di ricerca web e web fetch
Controlla quali siti possono raggiungere gli strumenti di ricerca web e web fetch di un agente, limita il contenuto recuperato e localizza i risultati di ricerca.
L’utilizzo varia in base al prodotto
allowed_domains o blocked_domains sullo strumento web_search o web_fetch nella richiesta.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.
Anche le impostazioni di ricerca web della tua organizzazione nella pagina Funzionalità della Claude Console si applicano a web_search in una sessione. Se un amministratore disabilita la ricerca web, le chiamate web_search restituiscono un risultato di errore all’agente e la sessione continua. Se l’organizzazione limita i domini di ricerca web, l’agente riceve solo i risultati di ricerca consentiti sia dalle restrizioni di dominio dell’organizzazione sia dagli elenchi per singolo strumento dell’agente.
Anche le impostazioni di web fetch della tua organizzazione nella stessa pagina si applicano a web_fetch in una sessione. Se un amministratore disattiva web fetch, le chiamate web_fetch restituiscono un risultato di errore all’agente e la sessione continua. Se l’organizzazione imposta domini consentiti o bloccati per web fetch, un URL deve superare l’elenco dell’organizzazione e gli elenchi per singolo strumento dell’agente, così come qualsiasi URL a cui porta un reindirizzamento. Anche una chiamata web_fetch per un URL escluso da uno qualsiasi di essi restituisce un risultato di errore all’agente.
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 inoltre user_location e max_content_tokens. Impostazioni li descrive entrambi.
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
---ant apply crea l’agente e ne stampa l’ID.
In un ambiente cloud con rete limited, anche l’allowed_hosts dell’ambiente si applica a web_search e web_fetch. La creazione di una sessione fallisce con un errore 400 quando l’allowed_domains di uno strumento web abilitato contiene 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 dello 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 Strumenti integrati nel modulo dell’agente. Imposta max_content_tokens e user_location nella vista Non elaborato della configurazione dell’agente.
Impostazioni
Oltre a enabled e permission_policy, le voci degli strumenti web accettano le seguenti impostazioni:
| Impostazione | Si applica a | Descrizione |
|---|---|---|
allowed_domains | web_search, web_fetch | Gli unici host che lo strumento può raggiungere. Consulta Regole degli elenchi di domini. |
blocked_domains | web_search, web_fetch | Host che lo strumento non può raggiungere. Consulta Regole degli elenchi di domini. |
max_content_tokens | web_fetch | Limita la quantità di contenuto delle pagine recuperate incluso nel contesto. Deve essere un numero intero positivo. Consulta i limiti di contenuto. |
user_location | web_search | Localizza i risultati di ricerca. Un oggetto con gli stessi campi del parametro user_location della Messages API. |
Per i tipi che l’SDK usa per 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. L’API rifiuta una richiesta che viola una qualsiasi di queste regole, come descritto in Errori di convalida.
- Al massimo un elenco per voce: Imposta su una voce
allowed_domainsoppureblocked_domains, 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.comeexample.comcontano 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 di web_search può anche includere un percorso, come descritto in Suffissi di percorso sui domini di ricerca web.
| Non accettato | Esempio | Usa invece |
|---|---|---|
| Uno schema | https://example.com | example.com |
| Una porta | example.com:443 | example.com |
| Un wildcard | *.example.com | example.com |
Un percorso su un dominio web_fetch | example.com/* | example.com |
| Un indirizzo IP in qualsiasi forma, che sia IPv4, IPv6, tra parentesi quadre o in forma numerica abbreviata | 127.1 | Il nome di dominio del sito |
| Un dominio di primo livello semplice o un suffisso di registro | com, co.uk, gov.uk | Un dominio completo come example.co.uk |
| Un nome a etichetta singola | intranet | Un dominio completo come example.co.uk |
| Caratteri non ASCII, come in un nome di dominio internazionalizzato | La forma xn-- (Punycode) |
L’API rifiuta anche un dominio che contiene credenziali o spazi, oppure che ha un’etichetta che inizia o termina con un trattino. Rifiuta anche localhost e gli host che terminano con .localhost, .local, .internal, .localdomain o .invalid.
Suffissi di percorso sui domini di ricerca web
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.
L’API rifiuta le violazioni di formato e di limiti con un errore 400 invalid_request_error:
| Violazione | Messaggio di errore |
|---|---|
| Una voce imposta entrambi gli elenchi. | Include Only one of allowed_domains or blocked_domains may be set. |
| Un elenco è vuoto. | Include allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. |
| Un dominio viola una regola di formato. | Indica l’elenco del dominio e la posizione a partire da zero, come in allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com" |
Nelle stesse richieste, l’API rifiuta anche tre impostazioni che dipendono dai provider di ricerca e recupero:
- Un dominio in
allowed_domainsa cui il crawler di Anthropic non è autorizzato ad accedere. - Un
user_location.countryche il provider di ricerca non supporta. Il messaggio termina conuser_location.country: not a country the search provider supports. - Un
user_location.timezoneche non è un nome di fuso orario IANA valido.
In un ambiente cloud con rete limited, la creazione e l’aggiornamento della sessione verificano anche allowed_domains rispetto all’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:
- Correggi l’impostazione aggiornando gli strumenti della sessione.
- Aggiorna anche l’agente, in modo che le nuove sessioni inizino con la configurazione corretta.
- 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 elencato nell’elenco predefined_agents di subagents è vincolato da tre insiemi di elenchi per singolo strumento:
- I propri
allowed_domainseblocked_domains - Quelli di qualsiasi agente che lo ha chiamato
- Gli elenchi correnti dell’agente eseguito dalla sessione
Le impostazioni si combinano come segue:
| Impostazione | Come si combina |
|---|---|
allowed_domains | Lo strumento può raggiungere un host solo se ogni elenco lo copre. |
blocked_domains | Gli elenchi si sommano. |
max_content_tokens, user_location | Non combinate. Un thread usa il valore della propria configurazione dello strumento, se impostato. Altrimenti usa il valore dell’agente che lo ha chiamato e, in mancanza di questo, la configurazione corrente dell’agente della sessione. |
Un agente elencato può quindi restringere ciò che uno strumento raggiunge, ma mai ampliarlo:
- Un agente elencato che imposta
blocked_domainsmantiene gliallowed_domainsdell’agente della sessione e blocca quegli host al loro interno. - Un agente elencato che imposta i propri
allowed_domainspuò raggiungere solo gli host che sia il suo elenco sia l’elenco dell’agente della sessione coprono.
Una voce {"type": "self"} nell’elenco predefined_agents di subagents non ha impostazioni web proprie e segue le impostazioni correnti dell’agente della sessione.
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 il cui testo include no domain is permitted. La descrizione dello strumento comunica lo stesso al modello. Per evitarlo, mantieni gli allowed_domains di ciascun agente elencato all’interno degli allowed_domains dell’agente della sessione.
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. Per un agente elencato nell’elenco predefined_agents di subagents, l’aggiornamento non modifica gli elenchi propri dell’agente. Questi restano 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 sugli strumenti server della Messages API. Managed Agents differisce in quattro modi:
- Ogni elenco è limitato a 64 domini.
- I domini elencati per
web_fetchnon possono includere un percorso. - I domini devono essere ASCII. La Messages API accetta voci Unicode, anche se ne sconsiglia l’uso.
max_uses,citationsecache_controlnon sono disponibili nel toolset.
Passaggi successivi
Scopri gli strumenti integrati, abilitali o disabilitali e definisci strumenti personalizzati.
Controlla quando vengono eseguiti gli strumenti dell’agente e MCP.
Controlla l’accesso di rete in uscita della sandbox stessa.
Coordina più agenti all’interno di una singola sessione.
Disponibilità
Claude API
- API
- Messages API
- Managed Agents Beta richiede
- Modelli
- Tutti i modelli
Claude Platform on AWS
- Stato
- Beta
- API
- Managed Agents
- Header beta
- Richiede
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents Beta richiede
- Modelli
- Tutti i modelli
Questa pagina ti è stata utile?