WaveSpeedAI
← Blog

Claude Managed Agents Quickstart Guide 2026

Step-by-step quickstart for Claude Managed Agents: beta header setup, first session, tool calls, and streaming events — with key code patterns and cost checkpoints.

By Dora 7 min read
Claude Managed Agents Quickstart Guide 2026

La première fois que j’ai essayé de lancer une session Managed Agents, j’ai obtenu une erreur 400 dès le premier curl. Pas lors de la création de l’agent. Pas lors de l’environnement. Sur l’endpoint de streaming. J’avais copié-collé mon en-tête depuis la requête de création — anthropic-beta: managed-agents-2026-04-01 — et l’API de streaming l’a rejeté. Il s’avère que l’endpoint de streaming référençait, à ce moment-là dans la documentation, un en-tête beta différent. J’ai perdu quarante minutes là-dessus.

Si vous essayez de faire tourner votre première session Managed Agents de bout en bout aujourd’hui, voici le chemin que j’ai réellement parcouru. Bonjour, c’est Dora ! L’en-tête beta d’abord, parce que c’est là que vivent la moitié des échecs. Ensuite l’agent, l’environnement, la session, le stream. Et un point de contrôle des coûts à la fin, parce que le temps d’exécution de la session continue de tourner pendant que vous déboguez.

Avant de commencer

Vous avez besoin d’une clé API Anthropic avec accès Managed Agents. Il n’y a pas de liste d’attente en ce moment — toute clé existante fonctionne en bêta publique.

L’en-tête beta est non négociable. Chaque endpoint Managed Agents requiert anthropic-beta: managed-agents-2026-04-01. Selon la présentation des Managed Agents d’Anthropic, le SDK le définit automatiquement. Si vous utilisez du curl brut, vous l’ajoutez vous-même à chaque requête. C’est la cause la plus fréquente d’erreurs 400 que j’ai vue dans les rapports de la communauté.

Si vous utilisez le SDK officiel (anthropic pour Python, @anthropic-ai/sdk pour TypeScript), vérifiez que vous êtes sur une version qui inclut le support des agents beta. Les versions plus anciennes n’auront pas client.beta.agents ni client.beta.sessions.

Le choix du modèle a son importance ici. Opus 4.7 est plus performant pour le raisonnement agent à long horizon. Sonnet 4.6 est moins cher et plus rapide par token. Pour un démarrage rapide, Sonnet 4.6 suffit. Si votre vraie charge de travail implique du débogage, de la planification ou de longues chaînes d’outils, Opus 4.7 vaut son prix.

Étape 1 — Définir votre agent

Un agent, dans Managed Agents, est un objet de configuration, pas un processus. Vous définissez le nom, le modèle, le prompt système et l’accès aux outils une fois, puis vous le réutilisez entre les sessions.

Définition minimale viable tirée du démarrage rapide officiel :

python

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding agent.",
    tools=[{"type": "agent_toolset_20260401"}],
)

Le type d’outil agent_toolset_20260401 déverrouille le jeu d’outils intégré complet — bash, lecture/écriture de fichiers, recherche web, récupération web, exécution de code. Vous pouvez le réduire plus tard. Pour un premier essai, laissez-le large afin de voir ce que l’agent choisit réellement d’utiliser.

Sauvegardez agent.id. Chaque session y fait référence.

Étape 2 — Créer un environnement

Un environnement définit le conteneur sandboxé. Pour la plupart des premiers essais :

python

env = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

Sauvegardez env.id. Si votre agent ne touche que son propre système de fichiers, "networking": {"type": "limited"} est plus sûr et bien documenté dans le cookbook SRE incident responder.

Étape 3 — Démarrer une session

Une session associe un agent à un environnement. Créer une session ne démarre pas le travail. Elle se contente de provisionner. Le travail commence quand vous envoyez un événement utilisateur.

python

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

Ce modèle — créer, puis piloter avec des événements — est celui où le modèle de machine à états de la référence des sessions prend tout son sens. La session persiste. Vous pouvez envoyer d’autres événements plus tard. Le système de fichiers survit entre les tours.

Étape 4 — Streamer les événements

Ouvrez le stream, envoyez le message utilisateur, lisez les événements jusqu’à session.status_idle :

python

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text",
                         "text": "Generate first 20 Fibonacci numbers, save to fib.txt"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[tool: {event.name}]")
            case "session.status_idle":
                break

Les noms d’événements suivent {domaine}.{action}. Le schéma complet se trouve dans la documentation des événements et du streaming. Le champ processed_at est important : s’il est null, l’événement est en file d’attente, pas encore exécuté. Je l’ai raté lors de mon premier essai et j’ai cru que les outils échouaient silencieusement.

Points de contrôle des coûts

Managed Agents facture deux choses : les tarifs standard de tokens plus 0,08 $ par heure de session de temps d’exécution actif. Selon la page de tarification officielle, le temps d’exécution s’accumule à la milliseconde — mais seulement quand le statut est running. Le temps d’inactivité et les sessions terminées ne sont pas facturés.

Ce que cela signifie en pratique :

  • Une session que vous oubliez de fermer pendant le débogage : toujours en cours de facturation (si elle tourne).
  • Recherche web : 10 $ pour 1 000 appels, facturés séparément. Les agents de recherche atteignent ce seuil rapidement.
  • Vérifiez les sessions actives dans Console tracing avant de terminer votre journée. Vérifiez vous-même le chemin actuel dans l’interface — la disposition de la Console évolue.

Erreurs courantes

En-tête beta manquant ou incorrect. Erreur 400, souvent avec un message sur les endpoints non supportés. Solution : confirmez managed-agents-2026-04-01 sur chaque appel HTTP direct. Si vous utilisez le SDK et rencontrez toujours ce problème, mettez le SDK à jour.

Limites de débit. Les endpoints de création sont plafonnés à 60 rpm ; les endpoints de lecture à 600 rpm. Les limites de niveau organisationnel s’appliquent en plus. Les erreurs 429 signifient qu’il faut reculer avec du jitter, pas relancer immédiatement.

Boucle d’outils silencieuse. L’agent continue d’appeler des outils mais ne produit aucun message final. Vérifiez les traces de session — il s’agit généralement d’un requires_action non géré qui n’a jamais reçu de réponse.

FAQ

Q1 : Comment activer la coordination multi-agent dans Managed Agents ?

Le multi-agent (ainsi que la mémoire et les résultats) est encore une fonctionnalité en préversion de recherche. Vous demandez l’accès séparément via la Claude Console. Le modèle de coordination — un orchestrateur délégant à des agents appelables — est documenté dans sessions multi-agents, mais vous ne pouvez pas l’utiliser tant que l’indicateur de préversion n’est pas activé pour votre organisation.

Q2 : Puis-je inspecter les outils appelés par l’agent pendant une session ?

Oui. Utilisez client.beta.sessions.events.list(session.id) pour un accès programmatique, ou la vue de traçage de la Console pour une chronologie avec tokens et horodatages par événement.

Q3 : Où se trouve le cookbook officiel de Managed Agents ?

Les tutoriels se trouvent sur le site Claude Cookbook — le notebook iterate-fix-failing-tests est la meilleure première lecture. Le notebook operate-in-production couvre les vaults, MCP et webhooks une fois que vous dépassez le stade hello-world.

Q4 : Existe-t-il un moyen de tester sans engager de coûts de temps d’exécution de session ?

Il n’existe pas de niveau gratuit dédié à Managed Agents. Les crédits gratuits de l’API standard le couvrent. Gardez les sessions courtes pendant le développement et fermez-les quand vous arrêtez de travailler. Les sessions inactives ne sont pas facturées, mais celles qui tournent le sont — et « en cours d’exécution » inclut les agents en boucle silencieuse.

Q5 : Quel est le meilleur modèle pour les tâches Managed Agents de longue durée ?

Cela dépend de ce que « longue durée » signifie. Pour un raisonnement de plusieurs heures avec une utilisation intensive des outils, Opus 4.7. Pour des boucles plus simples à volume élevé, Sonnet 4.6 avec mise en cache des prompts réduit considérablement les coûts. Je teste encore Opus 4.7 sur des sessions de plus de 2 heures. C’est là que s’arrêtent mes données. Suite à venir.

Je vérifie encore le comportement de la compaction au-delà de la marque des deux heures. Testez-le vous-même — cela vous en apprendra plus que je ne pourrais le faire.

Articles précédents :

Partager