Premiers pas

Premiers pas avec Claude Managed Agents

Créez votre premier agent autonome.

Ce guide vous explique comment créer un agent, configurer un environnement, démarrer une session et diffuser les réponses de l'agent.

Concepts fondamentaux

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	A configured container template (packages, network access)
Session	A running agent instance within an environment, performing a specific task and generating outputs
Events	Messages exchanged between your application and the agent (user turns, tool results, status updates)

Prérequis

Un compte Console Anthropic
Une clé API

Installer le CLI

Vérifiez l'installation :

ant --version

Installer le SDK

Définissez votre clé API comme variable d'environnement :

export ANTHROPIC_API_KEY="your-api-key-here"

Créez votre première session

Toutes les requêtes à 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.

Créer un agent

Créez un agent qui définit le modèle, le prompt système et les outils disponibles.

set -euo pipefail

agent=$(
  curl -sS --fail-with-body 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 @- <<'EOF'
{
  "name": "Coding Assistant",
  "model": "claude-sonnet-4-6",
  "system": "You are a helpful coding assistant. Write clean, well-documented code.",
  "tools": [
    {"type": "agent_toolset_20260401"}
  ]
}
EOF
)

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

echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

Le type d'outil agent_toolset_20260401 active l'ensemble complet des outils d'agent préconstruits (bash, opérations sur les fichiers, recherche web, et plus encore). Consultez Outils pour la liste complète et les options de configuration par outil.

Sauvegardez l'agent.id retourné. Vous y ferez référence dans chaque session que vous créez.

Créer un environnement

Un environnement définit le conteneur dans lequel votre agent s'exécute.

environment=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
    -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'
{
  "name": "quickstart-env",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")

echo "Environment ID: $ENVIRONMENT_ID"

Sauvegardez l'environment.id retourné. Vous y ferez référence dans chaque session que vous créez.

Démarrer une session

Créez une session qui référence votre agent et votre environnement.

session=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -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
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "title": "Quickstart session"
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")

echo "Session ID: $SESSION_ID"

Envoyer un message et diffuser la réponse

Ouvrez un flux, envoyez un événement utilisateur, puis traitez les événements au fur et à mesure qu'ils arrivent :

# Send the user message first; the API buffers events until the stream attaches
curl -sS --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -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 @- >/dev/null <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"
        }
      ]
    }
  ]
}
EOF

# Open the SSE stream and process events as they arrive
while IFS= read -r line; do
  [[ $line == data:* ]] || continue
  json=${line#data: }
  case $(jq -r '.type' <<<"$json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<<"$json"
      ;;
    agent.tool_use)
      printf '\n[Using tool: %s]\n' "$(jq -r '.name' <<<"$json")"
      ;;
    session.status_idle)
      printf '\n\nAgent finished.\n'
      break
      ;;
  esac
done < <(
  curl -sS -N --fail-with-body \
    "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "Accept: text/event-stream"
)

L'agent va écrire un script Python, l'exécuter dans le conteneur et vérifier que le fichier de sortie a été créé. Votre sortie ressemblera à ceci :

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

Ce qui se passe

Lorsque vous envoyez un événement utilisateur, Claude Managed Agents :

Provisionne un conteneur : Votre configuration d'environnement détermine comment il est construit.
Exécute la boucle de l'agent : Claude décide quels outils utiliser en fonction de votre message
Exécute les outils : Les écritures de fichiers, les commandes bash et autres appels d'outils s'exécutent à l'intérieur du conteneur
Diffuse les événements : Vous recevez des mises à jour en temps réel pendant que l'agent travaille
Passe en veille : L'agent émet un événement session.status_idle lorsqu'il n'a plus rien à faire

Prochaines étapes

Définir votre agent

Créez des configurations d'agent réutilisables et versionnées

Configurer les environnements

Personnalisez les paramètres réseau et de conteneur

Outils de l'agent

Activez des outils spécifiques pour votre agent

Événements et diffusion

Gérez les événements et guidez l'agent en cours d'exécution

Was this page helpful?

Concepts fondamentaux

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	A configured container template (packages, network access)
Session	A running agent instance within an environment, performing a specific task and generating outputs
Events	Messages exchanged between your application and the agent (user turns, tool results, status updates)

Créez votre première session

Toutes les requêtes à 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.

Créer un agent

Créez un agent qui définit le modèle, le prompt système et les outils disponibles.

set -euo pipefail

agent=$(
  curl -sS --fail-with-body 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 @- <<'EOF'
{
  "name": "Coding Assistant",
  "model": "claude-sonnet-4-6",
  "system": "You are a helpful coding assistant. Write clean, well-documented code.",
  "tools": [
    {"type": "agent_toolset_20260401"}
  ]
}
EOF
)

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

echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

Sauvegardez l'agent.id retourné. Vous y ferez référence dans chaque session que vous créez.

Créer un environnement

Un environnement définit le conteneur dans lequel votre agent s'exécute.

environment=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
    -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'
{
  "name": "quickstart-env",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")

echo "Environment ID: $ENVIRONMENT_ID"

Sauvegardez l'environment.id retourné. Vous y ferez référence dans chaque session que vous créez.

Démarrer une session

Créez une session qui référence votre agent et votre environnement.

session=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -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
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "title": "Quickstart session"
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")

echo "Session ID: $SESSION_ID"

Envoyer un message et diffuser la réponse

Ouvrez un flux, envoyez un événement utilisateur, puis traitez les événements au fur et à mesure qu'ils arrivent :

# Send the user message first; the API buffers events until the stream attaches
curl -sS --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -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 @- >/dev/null <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"
        }
      ]
    }
  ]
}
EOF

# Open the SSE stream and process events as they arrive
while IFS= read -r line; do
  [[ $line == data:* ]] || continue
  json=${line#data: }
  case $(jq -r '.type' <<<"$json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<<"$json"
      ;;
    agent.tool_use)
      printf '\n[Using tool: %s]\n' "$(jq -r '.name' <<<"$json")"
      ;;
    session.status_idle)
      printf '\n\nAgent finished.\n'
      break
      ;;
  esac
done < <(
  curl -sS -N --fail-with-body \
    "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "Accept: text/event-stream"
)

L'agent va écrire un script Python, l'exécuter dans le conteneur et vérifier que le fichier de sortie a été créé. Votre sortie ressemblera à ceci :

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

Ce qui se passe

Lorsque vous envoyez un événement utilisateur, Claude Managed Agents :

Provisionne un conteneur : Votre configuration d'environnement détermine comment il est construit.

Exécute la boucle de l'agent : Claude décide quels outils utiliser en fonction de votre message

Exécute les outils : Les écritures de fichiers, les commandes bash et autres appels d'outils s'exécutent à l'intérieur du conteneur

Diffuse les événements : Vous recevez des mises à jour en temps réel pendant que l'agent travaille

Passe en veille : L'agent émet un événement session.status_idle lorsqu'il n'a plus rien à faire