Claude Platform Docs
Managed AgentsDéfinir votre agent

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

Contrôlez les sites que les outils de recherche web et de récupération web d’un agent peuvent atteindre, plafonnez le contenu récupéré et localisez les résultats de recherche.

L’utilisation varie selon le produit

Messages API
Définissez allowed_domains ou blocked_domains sur l’outil web_search ou web_fetch dans la requête.
Managed Agents
Définissez les mêmes champs dans l’ensemble d’outils de l’agent ; chaque liste contient au maximum 64 domaines.

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.

Les paramètres de recherche web de votre organisation sur la page Capacités de la Claude Console s’appliquent également à web_search dans une session. Si un administrateur désactive la recherche web, les appels web_search renvoient un résultat d’erreur à l’agent, et la session se poursuit. Si l’organisation restreint les domaines de recherche web, l’agent ne reçoit que les résultats de recherche qu’autorisent à la fois les restrictions de domaines de l’organisation et les listes propres à chaque outil de l’agent.

Les paramètres de récupération web de votre organisation sur la même page s’appliquent également à web_fetch dans une session. Si un administrateur désactive la récupération web, les appels web_fetch renvoient un résultat d’erreur à l’agent, et la session se poursuit. Si l’organisation définit des domaines autorisés ou bloqués pour la récupération web, une URL doit satisfaire à la fois la liste de l’organisation et les listes propres à chaque outil de l’agent, tout comme toute URL vers laquelle mène une redirection. Un appel web_fetch pour une URL que l’une de ces listes exclut renvoie également un résultat d’erreur à l’agent.

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. Paramètres décrit les deux.

ant apply agent.md
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 crée l’agent et affiche son ID.

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 couverte par 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 ne fonctionnent pas de la même manière : l’entrée d’un outil couvre ses sous-domaines, mais une entrée de 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 couverte par des allowed_hosts valant ["example.com"], mais elle l’est par ["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 Outils intégrés du formulaire de l’agent. Définissez max_content_tokens et user_location dans la vue Brut 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 :

ParamètreS’applique àDescription
allowed_domainsweb_search, web_fetchLes seuls hôtes que l’outil peut atteindre. Consultez Règles des listes de domaines.
blocked_domainsweb_search, web_fetchLes hôtes que l’outil ne peut pas atteindre. Consultez Règles des listes de domaines.
max_content_tokensweb_fetchPlafonne la quantité de contenu de page récupéré incluse dans le contexte. Doit être un entier positif. Consultez les limites de contenu.
user_locationweb_searchLocalise les résultats de recherche. Un objet avec les mêmes champs que le paramètre user_location de l’API Messages.

Pour connaître les types que le SDK utilise pour 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. L’API rejette une requête qui enfreint l’une de ces règles, comme décrit dans Erreurs de validation.

  • Au plus 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 web_search peut également comporter un chemin, comme le décrit Suffixes de chemin sur les domaines de recherche web.

Non acceptéExempleÀ utiliser à la place
Un schémahttps://example.comexample.com
Un portexample.com:443example.com
Un caractère générique*.example.comexample.com
Un chemin sur un domaine web_fetchexample.com/*example.com
Une adresse IP sous quelque forme que ce soit, qu’il s’agisse d’IPv4, d’IPv6, entre crochets ou en notation numérique abrégée127.1Le nom de domaine du site
Un domaine de premier niveau nu ou un suffixe de registrecom, co.uk, gov.ukUn domaine complet tel que example.co.uk
Un nom à étiquette uniqueintranetUn domaine complet tel que example.co.uk
Des caractères non ASCII, comme dans un nom de domaine internationaliséLa forme xn-- (Punycode)

L’API rejette également un domaine qui contient des identifiants ou des espaces, ou dont l’une des étiquettes commence ou se termine par un trait d’union. Elle rejette aussi localhost et les hôtes se terminant par .localhost, .local, .internal, .localdomain ou .invalid.

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.

L’API rejette les violations de format et de limites avec une erreur 400 invalid_request_error :

ViolationMessage d’erreur
Une entrée définit les deux listes.Inclut Only one of allowed_domains or blocked_domains may be set.
Une liste est vide.Inclut allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.
Un domaine enfreint une règle de format.Indique la liste du domaine et sa position (à partir de zéro), comme dans allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com"

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 de fuseau horaire 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 figurant dans la liste predefined_agents de subagents est soumis à trois ensembles de listes propres à chaque outil :

  • Ses propres allowed_domains et blocked_domains
  • Ceux de tout agent qui l’a appelé
  • Les listes actuelles de l’agent exécuté par la session

Les paramètres se combinent comme suit :

ParamètreMode de combinaison
allowed_domainsL’outil ne peut atteindre un hôte que si chaque liste le couvre.
blocked_domainsLes listes s’additionnent.
max_content_tokens, user_locationNon combinés. Un fil utilise la valeur de sa propre configuration d’outil si elle est définie. Sinon, il utilise la valeur de l’agent qui l’a appelé, et à défaut la configuration actuelle de l’agent de la session.

Un agent listé peut donc restreindre ce qu’un outil atteint, mais jamais l’élargir :

  • Un agent listé qui définit blocked_domains conserve les allowed_domains de l’agent de la session et bloque ces hôtes à l’intérieur de cette liste.
  • Un agent listé qui définit ses propres allowed_domains ne peut atteindre que les hôtes que couvrent à la fois sa liste et la liste de l’agent de la session.

Une entrée {"type": "self"} dans la liste predefined_agents de subagents n’a pas de paramètres web propres et suit les paramètres actuels de l’agent de la session.

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 dont le texte inclut no domain is permitted. La description de l’outil indique la même chose au modèle. Pour éviter cela, maintenez les allowed_domains de chaque agent listé à l’intérieur des allowed_domains de l’agent de la session.

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 prochain tour. Pour un agent figurant dans la liste predefined_agents de subagents, la mise à jour ne modifie pas les listes propres de l’agent. 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 :

Étapes suivantes

Découvrez les outils intégrés, activez-les ou désactivez-les, et définissez des outils personnalisés.

Contrôlez quand les outils d’agent et MCP s’exécutent.

Contrôlez l’accès réseau sortant propre au sandbox.

Coordonnez plusieurs agents au sein d’une même session.

Disponibilité

Restrictions de domaines web
API
  • Messages API
  • Managed Agents Bêta nécessite
Modèles
  • Tous les modèles

Cette page vous a-t-elle été utile ?