Définir votre agent

Un agent est une configuration réutilisable et versionnée qui définit la persona et les capacités. Il regroupe le modèle, le prompt 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 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.

Toutes les requêtes de l'API Managed Agents nécessitent l'en-tête bêta managed-agents-2026-04-01. Le SDK définit automatiquement l'en-tête bêta.

Champs de configuration de l'agent

Champ	Description
`name`	Obligatoire. Un nom lisible par l'humain pour l'agent.
`model`	Obligatoire. Le modèle Claude qui alimente l'agent. Tous les modèles Claude 4.5 et ultérieurs sont pris en charge.
`system`	Un prompt système qui définit le comportement et la persona de l'agent. Le prompt système est distinct des messages utilisateur, qui doivent décrire le travail à effectuer.
`tools`	Les outils disponibles pour l'agent. Combine les outils d'agent préconstruits, les outils MCP et les outils personnalisés.
`mcp_servers`	Serveurs MCP qui fournissent des capacités tierces standardisées.
`skills`	Les compétences qui fournissent un contexte spécifique au domaine avec une divulgation progressive.
`callable_agents`	D'autres agents que cet agent peut invoquer pour l'orchestration multi-agents. Il s'agit d'une fonctionnalité en aperçu de recherche ; demandez l'accès pour l'essayer.
`description`	Une description de ce que fait l'agent.
`metadata`	Paires clé-valeur arbitraires pour votre propre suivi.

Créer un agent

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

Pour utiliser Claude Opus 4.6 avec le mode rapide, passez model en tant qu'objet : {"id": "claude-opus-4-6", "speed": "fast"}.

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 mise à jour de l'agent.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-sonnet-4-6",
    "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 effectuez la mise à jour à partir d'un état connu.

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

Cycle de vie de l'agent

Opération	Comportement
Mise à jour	Génère une nouvelle version de l'agent.
Lister les versions	Récupère l'historique complet des versions pour suivre les modifications au fil du temps.
Archiver	L'agent devient en lecture seule. Les nouvelles sessions ne peuvent pas le référencer, mais les sessions existantes continuent de s'exécuter.

Lister les versions

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

Archiver un agent

L'archivage rend l'agent en lecture seule. 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 d'archivage.

Étapes suivantes

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

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -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 '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')

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

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 @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "You are a helpful coding agent. Always write tests."
}
EOF
)

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

curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"