Définir votre agent

Un agent est une configuration réutilisable et versionnée qui définit un persona et des capacités. Il regroupe le modèle, l'invite système, les outils, les serveurs MCP et les skills qui déterminent le comportement de Claude pendant une session.

Créez l'agent une seule fois en tant que ressource réutilisable et référencez-le par son ID chaque fois que vous démarrez une session. Les agents sont versionnés et plus faciles à gérer sur de nombreuses sessions.

Champs de configuration de l'agent

Vous pouvez également remplacer model, system, tools, mcp_servers et skills pour une seule session sans modifier l'agent. Un remplacement de model remplace entièrement l'objet model de l'agent, de sorte que l'effort propre à l'agent n'est pas conservé. Pour exécuter la session à un niveau d'effort spécifique, définissez effort dans l'objet model du remplacement. Consultez Remplacer la configuration de l'agent pour une session.

Créer un agent

L'exemple suivant définit un agent de programmation qui utilise le modèle Claude Opus le plus récent avec accès à l'ensemble d'outils d'agent prédéfini. Cet ensemble d'outils permet à l'agent d'écrire du code, de lire des fichiers, d'effectuer des recherches sur le web, et plus encore. Consultez la référence des outils d'agent pour la liste complète des outils pris en charge.

Les exemples utilisent curl, la CLI ant ou l'un des SDK. Si vous n'en avez pas encore configuré, le guide de démarrage rapide couvre l'installation et la configuration du client.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

La réponse reprend votre configuration et ajoute les champs id, type, version, created_at, updated_at et archived_at, et renseigne les champs de model que vous omettez, comme effort, avec leurs valeurs par défaut. La version commence à 1 et s'incrémente chaque fois qu'une mise à jour modifie l'agent.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5-5",
    "effort": { "type": "medium" },
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

Le default_config de l'ensemble d'outils indique sa politique d'autorisation par défaut, always_allow, qui s'applique sauf si vous en configurez une.

Épingler la géographie d'inférence

Comme speed et effort, inference_geo se définit via la forme objet de model : passez model sous forme d'objet et définissez inference_geo à côté de id. Le champ accepte "us" ou "global". Lorsqu'il n'est pas défini, chaque requête au modèle suit la géographie d'inférence par défaut de l'espace de travail au moment où elle est servie. Consultez Résidence des données pour les contrôles de géographie au niveau de l'espace de travail et la tarification.

L'exemple suivant épingle un agent à l'inférence aux États-Unis et affiche la valeur inference_geo de l'objet model de l'agent :

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5-5
  inference_geo: us
---

You are a helpful assistant.

Un épinglage inference_geo est validé par rapport aux allowed_inference_geos de l'espace de travail lorsque l'agent est enregistré, lorsqu'une session est créée à partir de celui-ci, et à chaque tour servi par la session. Si la liste d'autorisation de l'espace de travail se restreint de sorte qu'un épinglage n'est plus autorisé, de nouvelles sessions ne peuvent plus être créées à partir de l'agent et les sessions en cours refusent les tours suivants ; les épinglages ne sont jamais exemptés, car les espaces de travail s'appuient sur eux pour la conformité et la résidence des données.

Définir inference_geo sur un modèle qui ne prend pas en charge l'épinglage géographique de l'inférence renvoie une erreur 400 ; consultez Disponibilité des modèles pour les modèles qui le prennent en charge. Dans une configuration multiagent, l'épinglage de l'agent et celui de chaque agent figurant dans la liste predefined_agents de subagents ou de workflows doivent tous être définis sur la même valeur ou tous être non définis ; consultez Orchestration multiagent. Pour modifier ou supprimer l'épinglage ultérieurement, mettez à jour l'objet model de l'agent ; fournir model sans inference_geo le supprime, comme décrit dans Sémantique de mise à jour.

Mettre à jour un agent

La mise à jour d'un agent génère une nouvelle version lorsque la configuration change. Le champ version est facultatif : fournissez-le pour une concurrence optimiste (une non-correspondance renvoie une erreur 409), ou omettez-le pour appliquer la mise à jour sans condition (la dernière écriture l'emporte). Les mises à jour des agents archivés sont rejetées.

Avec la CLI, modifiez le fichier de l'agent et exécutez à nouveau ant apply ; apply fournit version pour vous.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

L'exemple précédent fournit version à partir de la réponse de création, de sorte que la mise à jour ne s'applique que si rien d'autre n'a modifié l'agent depuis que vous l'avez lu. Pour appliquer une mise à jour sans condition, omettez version de la requête :

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

Sémantique de mise à jour

• version est facultatif et doit être au moins égal à 1 lorsqu'il est fourni. Lorsqu'il est fourni, la requête renvoie une erreur 409 s'il ne correspond pas à la version actuelle de l'agent, même lorsque les champs que vous envoyez correspondent déjà aux valeurs stockées ; relisez l'agent et réessayez. Lorsqu'il est omis, la mise à jour s'applique sans condition et la mise à jour la plus récente remplace silencieusement toute mise à jour concurrente, sans erreur pour aucun des appelants. Fournir version est le comportement par défaut recommandé pour les appelants interactifs, et l'omettre convient aux boucles d'application déclaratives, comme une tâche CI qui synchronise des définitions d'agents versionnées dans le dépôt, où la boucle est propriétaire de l'agent.

• Les champs omis sont conservés. Vous n'avez besoin d'inclure que les champs que vous souhaitez modifier.

• Les champs scalaires (model, system, name, description) sont remplacés par la nouvelle valeur. system et description peuvent être effacés en passant None. model et name sont obligatoires et ne peuvent pas être effacés. Dans un objet model que vous fournissez, effort est la seule exception : si l'id du modèle est inchangé, omettre effort laisse le niveau d'effort stocké inchangé. Si vous modifiez l'id du modèle, un effort omis est réinitialisé à la valeur par défaut du nouveau modèle. Les autres champs de model sont remplacés avec l'objet : fournir model sans inference_geo supprime l'épinglage de géographie d'inférence de l'agent.

• Les champs de type tableau (tools, mcp_servers, skills) sont entièrement remplacés par le nouveau tableau. Pour effacer complètement un champ de type tableau, passez None ou un tableau vide.

• multiagent est fusionné niveau par niveau dans le bloc stocké lorsque la mise à jour conserve le type multiagent_20261001. Un paramètre que vous omettez conserve sa valeur stockée, et une liste predefined_agents que vous envoyez remplace la liste stockée. Toute autre mise à jour qui envoie multiagent remplace le bloc stocké dans son ensemble, et les paramètres qu'elle omet prennent leurs valeurs par défaut. Passez multiagent=None pour effacer l'ensemble du bloc. À l'intérieur du bloc, null réinitialise un paramètre à sa valeur par défaut, de sorte que définir workflows sur null active les workflows dynamiques. Consultez Activer les workflows dynamiques.

• Les métadonnées sont fusionnées au niveau des clés. Les clés que vous fournissez sont ajoutées ou mises à jour. Les clés que vous omettez sont conservées. Pour supprimer une clé spécifique, définissez sa valeur sur null.

• Détection des opérations sans effet. Si la mise à jour ne produit aucun changement par rapport à la version actuelle, aucune nouvelle version n'est créée et la version existante est renvoyée.

• Les listes predefined_agents des autres agents ne sont pas mises à jour. Les agents qui répertorient cet agent dans la liste predefined_agents de subagents ou de workflows conservent la version qui était épinglée lors de leur création ou lors de la dernière mise à jour ayant envoyé cette liste, même si la référence omet version. Pour déléguer à la nouvelle version, mettez à jour l'agent qui la répertorie afin que la liste référence la nouvelle version.

La mise à jour suivante efface la description, supprime la clé team de metadata et définit workflows sur null, ce qui active les workflows dynamiques :

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

Cycle de vie de l'agent

Lister les versions

Récupérez l'historique complet des versions pour suivre l'évolution d'un agent au fil du temps. Les résultats sont paginés, et les exemples de SDK récupèrent automatiquement toutes les pages.

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

Archiver un agent

L'archivage rend l'agent en lecture seule et ne peut pas être annulé. Les sessions existantes continuent de s'exécuter, mais les nouvelles sessions ne peuvent pas référencer l'agent. La réponse définit archived_at sur l'horodatage de l'archivage.

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

Étapes suivantes