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

Lorsque la sortie d'un outil dépasse 100 000 caractères (environ 25 000 tokens), elle est automatiquement écrite dans un fichier du sandbox. 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 s'exécutent sans confirmation, nécessitent une confirmation ou sont évalués individuellement par le serveur. Consultez Politiques d'autorisation pour connaître 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 apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---

Désactivation d'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 }
  ]
}

Activation d'outils spécifiques uniquement

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 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 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 (Outils intégrés) du formulaire de l'agent ; définissez max_content_tokens et user_location dans la vue Raw (Brut) de la configuration de l'agent.

En plus de enabled et permission_policy, les entrées des 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 sous forme de nom d'hôte simple : lettres ASCII, chiffres, traits d'union, traits de soulignement et points, sans schéma, port, identifiants, caractère générique ni espace, sans étiquette commençant ou se terminant par un trait d'union, et sans chemin autre que le suffixe de chemin facultatif de web_search 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 unique / 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 www. initial est un sous-domaine comme n'importe quel 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 en 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 à étiquette 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 comporter un suffixe de chemin tel que example.com/blog, dans lequel le chemin ne peut pas contenir d'espaces, de ?, de #, 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 en 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 accepté précédemment n'est plus valide à ce moment-là, la session émet un événement session.error et revient à l'état 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 attendus et mises à jour en cours de session

Dans une session multi-agents, chaque liste de domaines qui s'applique à un fil est appliquée en même temps : un agent figurant dans la liste d'agents 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 de la liste peut restreindre ce qu'un outil atteint mais jamais l'élargir. Par exemple, un agent de la liste qui définit blocked_domains conserve les allowed_domains du coordinateur et bloque ces hôtes en son sein, et un agent de la liste 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. Maintenez la liste d'autorisation de chaque agent de la liste à l'intérieur de celle du coordinateur pour éviter cela.
• max_content_tokens et user_location ne sont pas combinés : un fil 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 liste {"type": "self"} n'a pas de paramètres web propres et suit les paramètres actuels du coordinateur.
• L'évaluateur dans les sessions orientées résultats s'exécute sans web_search ni web_fetch, quels que soient ces paramètres.
• 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 les applique à partir de son prochain tour, tandis que les listes propres d'un agent de la liste 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 domaines des 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.
• Les domaines doivent être en ASCII : utilisez la forme xn-- (Punycode) pour les noms de domaine internationalisés. L'API Messages accepte les entrées Unicode, bien qu'elle les déconseille.
• 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 de 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 revient 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 sandbox auto-hébergé, le worker d'environnement peut servir des outils personnalisés depuis votre sandbox, y compris des outils qui encapsulent un serveur MCP à l'intérieur de votre réseau.

ant apply agent.md

---
name: Weather Agent
model: claude-opus-5-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, l'agent 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 les performances 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 pouvez donner de contexte à Claude sur vos outils, mieux il saura déterminer quand et comment les utiliser. Visez trois à quatre phrases pour chaque description d'outil, davantage si l'outil est complexe.
• Regroupez 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 performants réduisent l'ambiguïté de sélection et rendent votre surface d'outils plus facile à parcourir pour Claude.
• Utilisez des espaces de noms significatifs 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 des outils pour ne renvoyer que des informations à fort signal. 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