Restreindre les domaines de recherche web et de récupération web

Pour contrôler les sites que les outils web de l'agent peuvent atteindre, définissez une liste de domaines sur les entrées web_search et web_fetch de l'ensemble d'outils de l'agent. Chacune de ces entrées configs accepte l'une de deux listes :

• allowed_domains : L'outil ne peut atteindre que ces hôtes.
• blocked_domains : L'outil ne peut jamais atteindre ces hôtes.

Chaque outil possède sa propre liste, de sorte que web_search et web_fetch peuvent avoir des restrictions différentes.

Définir des listes de domaines sur un agent

L'exemple suivant crée un agent qui limite web_search à deux sites et bloque un hôte pour web_fetch. Il définit également user_location et max_content_tokens, décrits dans Paramètres. L'exemple affiche ensuite le tableau configs de la réponse.

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

Dans un environnement cloud avec une mise en réseau limited, les allowed_hosts de l'environnement s'appliquent également à web_search et web_fetch. La création d'une session échoue avec une erreur 400 lorsque les allowed_domains d'un outil web activé contiennent une entrée qui n'est pas comprise dans allowed_hosts. Il en va de même pour une mise à jour de session qui ajoute une telle entrée. Pour corriger cela, ajoutez l'hôte à allowed_hosts ou supprimez l'entrée de allowed_domains. À l'exécution, un appel web_fetch pour une URL sur un hôte auquel allowed_hosts ne correspond pas renvoie un résultat d'erreur url_not_allowed. web_search omet les résultats provenant de tels hôtes. Les deux listes effectuent la correspondance différemment : l'entrée d'un outil couvre ses sous-domaines, mais une entrée allowed_hosts correspond à un seul hôte exact, sauf si elle commence par *.. Par exemple, l'entrée d'outil docs.example.com n'est pas comprise dans des allowed_hosts valant ["example.com"], mais elle l'est dans ["docs.example.com"] ou ["*.example.com"].

Dans la Claude Console, définissez les domaines autorisés ou bloqués à partir des lignes web_search et web_fetch de la carte Built-in tools du formulaire de l'agent. Définissez max_content_tokens et user_location dans la vue Raw de la configuration de l'agent.

Paramètres

En plus de enabled et permission_policy, les entrées des outils web acceptent les paramètres suivants :

Pour savoir comment les SDK typent ces entrées, consultez Types d'entrées de configuration dans les SDK.

Lorsqu'un domaine n'est pas autorisé

web_search omet les résultats que sa liste de domaines n'autorise pas. Un appel web_fetch pour une URL que sa liste de domaines n'autorise pas renvoie un résultat d'erreur à l'agent. L'événement agent.tool_result a is_error: true, et son contenu indique le code d'erreur url_not_allowed.

Règles des listes de domaines

Ces règles s'appliquent aussi bien à allowed_domains qu'à blocked_domains. Une requête qui enfreint l'une d'elles est rejetée, comme le décrit Erreurs de validation.

• Une liste par entrée : Définissez soit allowed_domains, soit blocked_domains sur une entrée, mais pas les deux.
• Taille de la liste : Chaque liste contient de 1 à 64 domaines, chacun de 1 à 255 caractères.
• Pas de listes vides : Pour n'appliquer aucune restriction, omettez le champ ou envoyez null.
• Pas de doublons : Un domaine ne peut apparaître qu'une seule fois dans une liste. www.example.com et example.com comptent comme des domaines différents.

Ce à quoi correspond un domaine listé

Un domaine listé correspond à cet hôte et à tous ses sous-domaines. example.com couvre docs.example.com, mais docs.example.com ne couvre ni example.com ni api.example.com.

Un préfixe www. est un sous-domaine comme un autre, donc www.example.com ne couvre pas example.com. Listez le domaine nu pour couvrir les deux.

Les noms d'hôte sont comparés sans tenir compte de la casse.

Format des domaines

Chaque domaine est un nom de domaine enregistrable, ou un sous-domaine de celui-ci, écrit sous forme de nom d'hôte simple. Il peut contenir des lettres ASCII, des chiffres, des traits d'union, des traits de soulignement et des points. Un seul / final est ignoré.

Un domaine est également rejeté s'il contient des identifiants ou des espaces, ou si l'une de ses étiquettes commence ou se termine par un trait d'union. localhost et les hôtes se terminant par .localhost, .local, .internal, .localdomain ou .invalid sont également rejetés.

Suffixes de chemin sur les domaines de recherche web

Un domaine web_search peut comporter un suffixe de chemin, tel que example.com/blog. Le chemin ne peut pas contenir d'espaces, de ?, de #, ni aucun des caractères $ , | ^ !.

Privilégiez également les noms d'hôte simples pour web_search. Le fournisseur de recherche fait correspondre les suffixes de chemin en tant que motifs d'URL plutôt qu'en tant que règles d'hôte strictes.

Erreurs de validation

L'API valide ces paramètres lorsque vous créez un agent ou mettez à jour un agent. Elle les valide également lorsque vous créez ou mettez à jour une session qui fournit tools.

Les violations de format et de limites sont rejetées avec une erreur 400 invalid_request_error :

Sur ces mêmes requêtes, l'API rejette également trois paramètres qui dépendent des fournisseurs de recherche et de récupération :

• Un domaine dans allowed_domains auquel le robot d'exploration d'Anthropic n'est pas autorisé à accéder.
• Un user_location.country que le fournisseur de recherche ne prend pas en charge. Le message se termine par user_location.country: not a country the search provider supports.
• Un user_location.timezone qui n'est pas un nom IANA valide.

Dans un environnement cloud avec une mise en réseau limited, la création et la mise à jour de session vérifient également allowed_domains par rapport aux allowed_hosts de l'environnement. Consultez la règle dans Définir des listes de domaines sur un agent.

Lorsqu'un paramètre accepté n'est plus valide

La session vérifie à nouveau la configuration lorsqu'elle initialise l'outil pour la première fois. Si un paramètre accepté précédemment n'est plus valide à ce moment-là, la session émet un événement session.error. Elle revient ensuite à l'état idle sans réessayer.

Pour poursuivre la session :

1. Corrigez le paramètre en mettant à jour les outils de la session.
2. Mettez également à jour l'agent, afin que les nouvelles sessions démarrent avec la configuration corrigée.
3. Envoyez un nouveau user.message.

Sessions multi-agents et sessions orientées résultats

Dans une session multi-agents, toutes les listes de domaines qui s'appliquent à un fil sont appliquées simultanément. Un agent de la liste du coordinateur est soumis à trois ensembles de listes :

• Ses propres allowed_domains et blocked_domains
• Ceux de tout agent qui l'a appelé
• Les listes actuelles du coordinateur

Les paramètres se combinent comme suit :

Un agent de la liste peut donc restreindre ce qu'un outil atteint, mais jamais l'élargir :

• Un agent de la liste qui définit blocked_domains conserve les allowed_domains du coordinateur et bloque ces hôtes au sein de ceux-ci.
• Un agent de la liste qui définit ses propres allowed_domains ne peut atteindre que les hôtes couverts à la fois par sa liste et par celle du coordinateur.

Une entrée de liste {"type": "self"} n'a pas de paramètres web propres et suit les paramètres actuels du coordinateur.

Si les listes allowed_domains combinées n'ont aucun domaine en commun, l'outil reste disponible pour cet agent, mais chaque appel échoue. Chaque appel renvoie une erreur url_not_allowed indiquant qu'aucun domaine n'est autorisé. La description de l'outil en informe également le modèle. Pour éviter cela, maintenez les allowed_domains de chaque agent de la liste à l'intérieur de ceux du coordinateur.

L'évaluateur des sessions orientées résultats s'exécute sans web_search ni web_fetch, quels que soient ces paramètres.

Modifier les listes en cours de session

Vous pouvez modifier les listes d'une session inactive en mettant à jour ses outils. Les nouvelles listes s'appliquent au reste de la session.

Dans une session multi-agents, chaque fil applique les nouvelles listes à partir de son tour suivant. La mise à jour ne modifie pas les listes propres d'un agent de la liste. Celles-ci restent telles que la définition de l'agent les a fixées lors de la création de la session.

Différences avec les outils de l'API Messages

Ces paramètres utilisent les mêmes champs allowed_domains et blocked_domains que le filtrage de domaines des outils serveur de l'API Messages. Managed Agents diffère sur quatre points :

• Chaque liste est plafonnée à 64 domaines.
• Les domaines listés pour web_fetch ne peuvent pas inclure de chemin.
• Les domaines doivent être en ASCII. L'API Messages accepte les entrées Unicode, bien qu'elle les déconseille.
• max_uses, citations et cache_control ne sont pas disponibles dans l'ensemble d'outils.

Étapes suivantes