Définir votre agent

Un agent est une configuration réutilisable et versionnée qui définit la personnalité et les capacités. Il regroupe le modèle, l'invite système, les outils, les serveurs MCP et les compétences qui façonnent le comportement de Claude lors d'une session.

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

Champs de configuration de l'agent

Créer un agent

L'exemple suivant définit un agent de codage qui utilise Claude Opus 4.7 avec accès à l'ensemble d'outils d'agent prédéfini. L'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.

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-7}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}'

La réponse reprend votre configuration et ajoute les champs id, version, created_at, updated_at et archived_at. La version commence à 1 et s'incrémente chaque fois que vous mettez à jour l'agent.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-7",
    "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
}

Mettre à jour un agent

La mise à jour d'un agent génère une nouvelle version. Passez la version actuelle pour vous assurer que vous mettez à jour à partir d'un état connu.

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, etc.) 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 tableau (tools, mcp_servers, skills, callable_agents) sont entièrement remplacés par le nouveau tableau. Pour effacer complètement un champ de tableau, passez null ou un tableau vide.

• 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 sur une chaîne vide.

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

Cycle de vie de l'agent

Lister les versions

Récupérez l'historique complet des versions pour suivre comment un agent a changé au fil du temps.

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

Archiver un agent

L'archivage rend l'agent en lecture seule. Les sessions existantes continuent à 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 d'archivage.

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

Étapes suivantes

• Configurer les outils pour personnaliser les capacités que l'agent peut utiliser.
• Attacher des compétences pour l'expertise spécifique au domaine.
• Démarrer une session qui référence votre agent.