Définir votre agent

Un agent est une configuration réutilisable et versionnée qui définit une personnalité et des capacités. Il regroupe le modèle, l'invite système, les outils, les serveurs MCP et les skills qui façonnent le comportement de Claude au cours d'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 niveau d'effort défini dans un remplacement de model par session n'est pas appliqué, et comme le remplacement substitue intégralement l'objet model de l'agent, une session créée avec un remplacement de model s'exécute au niveau d'effort par défaut du modèle ; pour s'exécuter à un niveau d'effort spécifique, définissez effort sur l'agent et ne remplacez pas model pour cette session. 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 Claude Opus 5 avec accès à l'ensemble d'outils d'agent préconstruit. 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
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, tels que effort, avec leurs valeurs par défaut. Le champ 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",
    "effort": { "type": "high" },
    "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 zone géographique 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 zone géographique d'inférence par défaut de l'espace de travail au moment où elle est traitée. Consultez Résidence des données pour les contrôles géographiques 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
  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 que la session traite. 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 du coordinateur et celui de chaque membre de la liste doivent tous être définis à la même valeur ou tous être non définis ; consultez Orchestration multi-agents. Pour modifier ou effacer l'épinglage ultérieurement, mettez à jour l'objet model de l'agent ; fournir model sans inference_geo l'efface, comme décrit sous Sémantique des mises à 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 un 409), ou omettez-le pour appliquer la mise à jour de manière inconditionnelle (la dernière écriture l'emporte). Les mises à jour d'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
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 de manière inconditionnelle, omettez version de la requête :

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "description": "Writes and reviews code."
  }')

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

Sémantique des mises à jour

• version est facultatif et doit être au moins égal à 1 lorsqu'il est fourni. Lorsqu'il est fourni, la requête renvoie un 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 de manière inconditionnelle 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, telles qu'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 null. model et name sont obligatoires et ne peuvent pas être effacés. Au sein d'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 efface l'épinglage de zone géographique 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 entièrement un champ de type tableau, passez null ou un tableau vide.

• multiagent est remplacé dans son ensemble, y compris sa liste agents. Passez null pour l'effacer.

• 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 à 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 des coordinateurs ne sont pas mises à jour. Les coordinateurs qui référencent cet agent dans leur liste multiagent.agents conservent la version qui a été épinglée lors de la création ou de la dernière mise à jour du coordinateur, même si la référence omet version. Pour déléguer à la nouvelle version, mettez à jour le coordinateur afin que sa liste la référence.

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 SDK récupèrent automatiquement chaque page.

ant beta:agents:versions list --agent-id "$AGENT_ID"

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 à l'horodatage de l'archivage.

ant beta:agents archive --agent-id "$AGENT_ID"

Étapes suivantes