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 l'agent.

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 est identifiée par son name, qui prend une valeur de la colonne Nom dans Outils disponibles. Une entrée accepte également un champ facultatif type avec la même valeur.

Chaque entrée de configuration peut également définir une permission_policy. La politique détermine 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.

L'exemple suivant active l'ensemble d'outils et désactive web_fetch :

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

{
  "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 la recherche web et la récupération web

Les entrées web_search et web_fetch acceptent également des listes de domaines, une limite sur le contenu récupéré et une localisation de recherche. Consultez Restreindre les domaines de recherche web et de récupération web.

Types d'entrées de configuration dans les SDK

Les SDK Python, TypeScript, Go, Java, C#, Ruby et PHP typent chaque entrée configs par outil. Le type est une union comportant un membre par outil intégré, discriminée par type.

En Go, Java, C# et PHP, vous construisez les entrées à partir de valeurs typées plutôt que de simples dictionnaires ou hashes. Dans ces SDK, le type d'élément de configs est l'union elle-même ; construisez donc chaque entrée à partir de son type de membre propre à l'outil.

Vous pouvez omettre type lorsque vous construisez une entrée, car le serveur le déduit de name. Les réponses l'incluent toujours. Ce typage ne modifie pas le JSON vers lequel une entrée est sérialisée. Une requête dont les entrées ne définissent que name, enabled et permission_policy est valide avec ou sans type.

Outils personnalisés

Les outils personnalisés sont analogues aux outils client définis par l'utilisateur dans l'API Messages. Vous spécifiez quelles opérations sont disponibles et ce qu'elles renvoient, et Claude détermine quand et comment les appeler.

Claude n'exécute pas lui-même un outil personnalisé. Il émet une requête structurée, votre code exécute l'opération, et vous renvoyez le résultat à la session.

L'exemple suivant crée un agent avec l'ensemble d'outils intégré et un outil personnalisé, get_weather :

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

Le nom d'un outil personnalisé ne peut pas commencer par mcp__ ou ant__, ni correspondre au nom d'un outil d'agent intégré. Une requête qui enfreint cette règle renvoie une erreur 400. Un agent qui possède déjà un outil personnalisé dont le nom commence par ant__ n'accepte une mise à jour que si celle-ci envoie tools sans ce nom ; renommez ou supprimez donc l'outil lors de votre prochaine mise à jour. Une nouvelle session est refusée avec une erreur 400 si un tel outil se trouve sur son agent (après d'éventuels remplacements), sur un agent de la liste predefined_agents de subagents, ou sur un agent de la liste predefined_agents de workflows. Les sessions déjà existantes ne sont pas affectées.

L'agent appelle ses outils personnalisés au cours d'une session. Pour recevoir les appels et renvoyer les résultats, consultez Flux d'événements de session.

Pour les sessions qui s'exécutent dans un sandbox auto-hébergé, le worker d'environnement peut servir des outils personnalisés depuis le sandbox. Ceux-ci peuvent inclure des outils qui encapsulent un serveur MCP au sein de votre réseau.

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. Plus vous donnez de contexte à Claude sur vos outils, mieux il parvient à déterminer quand et comment les utiliser. Visez trois à quatre phrases pour chaque description d'outil, davantage si l'outil est complexe. Vos descriptions doivent couvrir :
  • Ce que fait l'outil
  • Quand l'utiliser, et quand ne pas l'utiliser
  • Ce que signifie chaque paramètre et comment il affecte le comportement de l'outil
  • Toute mise en garde ou limitation importante
• Regroupez les opérations connexes dans un nombre réduit d'outils. Regroupez des actions telles que create_pr, review_pr et merge_pr dans un seul outil doté d'un paramètre action. Des outils moins nombreux mais 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. N'incluez que les champs dont Claude a besoin pour déterminer sa prochaine étape. Des réponses surchargées gaspillent du contexte et compliquent l'extraction de ce qui compte pour Claude.

Prochaines étapes