Outils

Claude Managed Agents fournit un ensemble d'outils intégrés que Claude peut utiliser de manière autonome au sein d'une session. Vous contrôlez quels outils sont disponibles en les spécifiant dans la configuration de l'agent.

Claude Managed Agents prend également en charge les outils personnalisés définis par l'utilisateur. Votre application exécute ces outils séparément et renvoie les résultats à Claude, qui les utilise pour poursuivre la tâche. Pour donner à l'agent des outils provenant d'un serveur MCP, utilisez plutôt le connecteur MCP.



Outils disponibles

L'ensemble d'outils de l'agent comprend les outils suivants. Tous sont activés par défaut lorsque vous incluez l'ensemble d'outils dans la configuration de votre agent. Chaque entrée du tableau configs est identifiée par son name, en utilisant les valeurs de la colonne Nom, et accepte un champ type facultatif avec la même valeur. Les entrées web_search et web_fetch acceptent des paramètres supplémentaires ; consultez Restreindre les domaines de recherche web et de récupération web.

Lorsqu'une sortie d'outil dépasse 100 000 caractères (environ 25 000 tokens), elle est automatiquement écrite dans un fichier du bac à sable. Le modèle reçoit un aperçu tronqué avec le chemin du fichier et peut lire le contenu complet à partir de là.



Configuration de l'ensemble d'outils

Activez l'ensemble d'outils complet avec agent_toolset_20260401 lors de la création d'un agent. Utilisez le tableau configs pour désactiver des outils spécifiques ou remplacer leurs paramètres. Chaque entrée de configuration peut également définir une permission_policy qui contrôle si les appels de l'outil sont approuvés automatiquement ou nécessitent une confirmation. Consultez Politiques d'autorisation pour les types de politiques disponibles.

Les entrées de configuration pour web_search et web_fetch acceptent également des filtres de domaine et d'autres paramètres web ; consultez Restreindre les domaines de recherche web et de récupération web.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML



Désactiver des outils spécifiques

Pour désactiver un outil, définissez enabled: false dans son entrée de configuration dans l'objet d'ensemble d'outils du tableau tools de votre agent :

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}



Activer uniquement des outils spécifiques

L'objet default_config définit la base de référence pour chaque outil de l'ensemble, et les entrées configs par outil la remplacent. Pour commencer avec tout désactivé et n'activer que ce dont vous avez besoin, définissez default_config.enabled sur false :

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}



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

Pour contrôler quels sites les outils web de l'agent peuvent atteindre, définissez allowed_domains (l'outil ne peut atteindre que ces hôtes) ou blocked_domains (l'outil ne peut jamais atteindre ces hôtes) sur les entrées web_search et web_fetch du tableau configs de l'ensemble d'outils. Chaque outil possède sa propre liste, de sorte que web_search et web_fetch peuvent avoir des restrictions différentes. Un domaine listé couvre cet hôte et tous ses sous-domaines. À l'exécution, un appel web_fetch pour une URL que ses listes n'autorisent pas renvoie un résultat d'erreur à l'agent (is_error: true sur l'événement agent.tool_result, avec un contenu qui nomme le code d'erreur url_not_allowed), et web_search omet les résultats que ses listes n'autorisent pas.

L'ensemble d'outils suivant limite web_search à deux sites et localise ses résultats, et bloque un hôte pour web_fetch tout en plafonnant la quantité de contenu récupéré qui entre dans le contexte :

{
  "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
    }
  ]
}

La requête suivante crée un agent avec cet ensemble d'outils et affiche le tableau configs de la réponse :

ant beta:agents create --transform tools.0.configs <<'YAML'
name: Research Agent
model: claude-opus-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
YAML

Dans la Claude Console, définissez les domaines autorisés ou bloqués depuis les 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.

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



Règles des listes de domaines

• Définissez soit allowed_domains, soit blocked_domains sur une entrée, pas les deux. Une entrée qui définit les deux est rejetée.
• Chaque liste contient de 1 à 64 domaines, chacun de 1 à 255 caractères. Une liste vide est rejetée : pour n'appliquer aucune restriction, omettez le champ ou envoyez null.
• Chaque domaine est un nom de domaine enregistrable, ou un sous-domaine de celui-ci, écrit comme un nom d'hôte simple : lettres ASCII, chiffres, tirets, traits de soulignement et points, sans schéma, port, identifiants, caractère générique ni espace, aucun label ne commençant ou ne se terminant par un tiret, et aucun chemin autre que le suffixe de chemin web_search facultatif décrit plus loin dans cette liste. Utilisez example.com, et non https://example.com, example.com:443 ou *.example.com. Les noms d'hôte sont comparés sans tenir compte de la casse, et un seul / final est ignoré.
• Un domaine listé correspond à cet hôte et à ses sous-domaines : example.com couvre docs.example.com, mais docs.example.com ne couvre pas 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 adresses IP ne sont acceptées sous aucune forme, qu'il s'agisse d'IPv4, d'IPv6, entre crochets ou de notation numérique abrégée telle que 127.1. Listez plutôt le nom de domaine du site.
• Un domaine de premier niveau nu ou un suffixe de registre tel que com, co.uk ou gov.uk est rejeté, de même qu'un nom à label unique tel que intranet. Listez un domaine complet tel que example.co.uk.
• localhost et les hôtes se terminant par .localhost, .local, .internal, .localdomain ou .invalid sont rejetés.
• Utilisez la forme xn-- (Punycode) pour les noms de domaine internationalisés ; un domaine contenant des caractères non ASCII est rejeté.
• Un domaine web_fetch ne peut pas inclure de chemin : utilisez example.com, et non example.com/*. Un domaine web_search peut porter un suffixe de chemin tel que example.com/blog, dans lequel le chemin ne peut pas contenir d'espaces, ?, #, ni aucun des caractères $ , | ^ !. Préférez également les noms d'hôte simples pour web_search, car 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.
• Les domaines en double au sein d'une liste sont rejetés. www.example.com et example.com comptent comme des domaines différents ; consultez la règle de correspondance précédente pour savoir ce que chacun couvre.



Quand les paramètres sont validés

Les violations de format et de limite sont rejetées avec une erreur 400 invalid_request_error lorsque vous créez un agent ou mettez à jour un agent, et lorsque vous créez ou mettez à jour une session qui fournit tools. Par exemple, le message pour une entrée qui définit les deux listes inclut Only one of allowed_domains or blocked_domains may be set., et le message pour une liste vide inclut allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. Le message pour un domaine qui enfreint une règle de format nomme sa liste et sa position de base zéro, par exemple allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

Les mêmes requêtes rejettent é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), et un user_location.timezone qui n'est pas un nom IANA valide. La session vérifie à nouveau la configuration lorsqu'elle initialise l'outil pour la première fois ; si un paramètre qui avait été accepté précédemment n'est plus valide à ce moment-là, la session émet un événement session.error et revient à idle sans réessayer. Corrigez le paramètre en mettant à jour les outils de la session, mettez également à jour l'agent afin que les nouvelles sessions démarrent avec la configuration corrigée, puis envoyez un nouveau user.message pour continuer.



Sessions multi-agents, résultats et mises à jour en cours de session

Dans une session multi-agents, chaque liste de domaines qui s'applique à un fil d'exécution est appliquée en même temps : un agent du roster du coordinateur est lié par ses propres allowed_domains et blocked_domains, par ceux de tout agent qui l'a appelé, et par les listes actuelles du coordinateur.

• Les listes d'autorisation se combinent pour ne retenir que les domaines que toutes couvrent, et les listes de blocage s'additionnent, de sorte qu'un agent du roster peut restreindre ce qu'un outil atteint mais jamais l'élargir. Par exemple, un agent du roster qui définit blocked_domains conserve les allowed_domains du coordinateur et bloque ces hôtes au sein de celle-ci, et un agent du roster qui définit ses propres allowed_domains ne peut atteindre que les hôtes que sa liste et celle du coordinateur couvrent toutes deux.
• Si les listes d'autorisation combinées n'ont aucun domaine en commun, l'outil reste disponible pour cet agent mais chaque appel échoue avec une erreur url_not_allowed indiquant qu'aucun domaine n'est autorisé, et la description de l'outil en informe le modèle. Gardez la liste d'autorisation de chaque agent du roster à l'intérieur de celle du coordinateur pour éviter cela.
• max_content_tokens et user_location ne sont pas combinés : un fil d'exécution utilise la valeur de sa propre configuration d'outil si elle est définie, sinon celle de l'agent qui l'a appelé, sinon celle de la configuration actuelle du coordinateur.
• Une entrée de roster {"type": "self"} n'a pas de paramètres web propres et suit les paramètres actuels du coordinateur.
• L'évaluateur dans les sessions pilotées par les résultats s'exécute sans web_search ni web_fetch, indépendamment de ces paramètres.
• Vous pouvez modifier les listes sur 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 d'exécution les applique à partir de son prochain tour, tandis que les listes propres d'un agent du roster restent telles que sa définition d'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 le même vocabulaire allowed_domains et blocked_domains que le filtrage de domaine sur les outils serveur de l'API Messages, avec les différences suivantes sur Managed Agents :

• Chaque liste est plafonnée à 64 domaines.
• Les domaines listés pour web_fetch ne peuvent pas inclure de chemin.
• max_uses, citations et cache_control ne sont pas disponibles sur l'ensemble d'outils.



Outils personnalisés

En plus des outils intégrés, vous pouvez définir des outils personnalisés. Les outils personnalisés sont analogues aux outils client définis par l'utilisateur dans l'API Messages.

Chaque outil personnalisé définit un contrat : vous spécifiez quelles opérations sont disponibles et ce qu'elles renvoient, et Claude détermine quand et comment les appeler. Le modèle n'exécute jamais rien par lui-même. Il émet une requête structurée, votre code exécute l'opération, et le résultat est réinjecté dans la conversation. Consultez Flux d'événements de session pour savoir comment recevoir les appels d'outils personnalisés et renvoyer les résultats pendant une session.

Si vos sessions s'exécutent dans un bac à sable auto-hébergé, le worker d'environnement peut servir des outils personnalisés depuis votre bac à sable, y compris des outils qui encapsulent un serveur MCP à l'intérieur de votre réseau.

ant beta:agents create < agent.yaml

name: Weather Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
  - type: custom
    name: get_weather
    description: Get current weather for a location
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: City name
      required:
        - location

Une fois que vous avez défini des outils personnalisés sur l'agent, celui-ci les invoque pendant une session.



Bonnes pratiques pour les définitions d'outils personnalisés

• Fournissez des descriptions extrêmement détaillées. C'est de loin le facteur le plus important pour la performance des outils. Vos descriptions doivent expliquer ce que fait l'outil et quand l'utiliser (et quand ne pas l'utiliser). Expliquez ce que signifie chaque paramètre et comment il affecte le comportement de l'outil. Signalez toute mise en garde ou limitation importante. Plus vous donnez de contexte à Claude sur vos outils, mieux il détermine quand et comment les utiliser. Visez trois à quatre phrases pour chaque description d'outil, davantage si l'outil est complexe.
• Consolidez les opérations connexes en moins d'outils. Plutôt que de créer un outil distinct pour chaque action (create_pr, review_pr, merge_pr), regroupez-les en un seul outil avec un paramètre action. Des outils moins nombreux et plus polyvalents réduisent l'ambiguïté de sélection et rendent votre surface d'outils plus facile à parcourir pour Claude.
• Utilisez un espace de noms significatif dans les noms d'outils. Lorsque vos outils couvrent plusieurs services ou ressources, préfixez les noms avec la ressource (par exemple, db_query ou storage_read). Cela rend la sélection d'outils sans ambiguïté à mesure que votre bibliothèque s'agrandit.
• Concevez les réponses d'outils pour ne renvoyer que des informations à forte valeur. Renvoyez des identifiants sémantiques et stables (par exemple, des slugs ou des UUID) plutôt que des références internes opaques, et n'incluez que les champs dont Claude a besoin pour déterminer sa prochaine étape. Des réponses surchargées gaspillent du contexte et rendent plus difficile pour Claude d'extraire ce qui compte.



Prochaines étapes