Définir votre agent

Un agent est une configuration réutilisable et versionnée qui définit une persona et des capacités. Il regroupe le modèle, l'invite système, les outils, les serveurs MCP et les compétences 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. Voir Remplacer la configuration de l'agent pour une session.



Créer un agent

L'exemple suivant définit un agent de codage qui utilise Claude Opus 4.8 avec accès à l'ensemble d'outils d'agent préconfigurés. Cet ensemble d'outils permet à l'agent d'écrire du code, de lire des fichiers, de rechercher 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é un, le guide de démarrage rapide couvre l'installation et la configuration du client.

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-8}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

La réponse reprend votre configuration et ajoute les champs id, type, version, created_at, updated_at et archived_at. 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-4-8",
    "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": [],
  "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 sur l'ensemble d'outils affiche sa politique de permissions par défaut, always_allow, qui s'applique sauf si vous en configurez une.



Mettre à jour un agent

La mise à jour d'un agent génère une nouvelle version lorsque la configuration change. Le champ version est obligatoire et doit correspondre à la version actuelle de l'agent, afin que vous mettiez toujours à jour à partir d'un état connu. Une incompatibilité de version renvoie une erreur 409, et les mises à jour d'agents archivés sont rejetées.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."



Sémantique de mise à jour

• Les champs omis sont préservé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.

• 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 préservées. Pour supprimer une clé spécifique, définissez sa valeur à null.

• Détection d'absence de modification. 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 de 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"



Prochaines étapes