Comment utiliser Claude Managed Agents : guide de configuration étape par étape

La création d'un agent IA ne se limite pas à un simple appel de modèle. Vous devez gérer la boucle de l'agent, exécuter des outils, fournir un environnement d'exécution, maintenir l'état de la session, gérer les autorisations et observer les actions de l'agent.

Les agents gérés Claude prennent en charge une grande partie de cette infrastructure pour vous. Au lieu de construire et d'exploiter votre propre environnement d'exécution d'agent, vous définissez l'agent, configurez son lieu d'exécution et créez des sessions pour qu'il puisse accomplir ses tâches. L'environnement d'exécution géré prend en charge les appels de modèle et l'exécution des outils, tandis que votre application interagit avec l'agent via des événements.

Dans ce guide, nous vous montrerons comment utiliser les agents gérés Claude étape par étape de la création de votre premier agent et de la configuration de son environnement à l'exécution d'une session, en passant par l'ajout d'outils et de serveurs MCP, ainsi que la gestion des événements de l'agent.

Si vous souhaitez d'abord acquérir les bases conceptuelles, consultez notre guide sur ce que sont les agents gérés Claude et comment fonctionne leur architecture. Ce guide suppose que vous êtes prêt à passer à la construction.

Prérequis

Avant de créer un agent géré, vous aurez besoin de :

1. Un compte Claude Console
2. Une clé API Anthropic
3. Le SDK Anthropic
4. Python, TypeScript ou un autre langage pris en charge

Étape 1 : Installer la CLI et le SDK

Pour Python, installez le SDK :

pip install anthropic

Définissez ensuite votre clé API en tant que variable d'environnement :

export ANTHROPIC_API_KEY="your-api-key"

Anthropic propose également une CLI pour gérer les ressources Managed Agent.

Le SDK lit la clé depuis votre environnement, vous n'avez donc pas besoin de l'inclure directement dans le code de votre application.

Activer l'API Managed Agents

Claude Managed Agents est actuellement disponible via l'API bêta d'Anthropic. La version bêta de Managed Agents est identifiée par l'en-tête :

managed-agents-2026-04-01bêta.

Lorsque vous utilisez le SDK officiel, celui-ci gère cet en-tête pour vous lors de l'accès aux API Managed Agents.

La configuration de base de votre client ressemble à ceci :

from anthropic import Anthropic
client = Anthropic()

À ce stade, votre application est prête à utiliser l'API Managed Agents.

L'étape suivante consiste à créer l' agent lui-même, en définissant le modèle Claude qu'il utilise, les instructions qu'il suit et les outils auxquels il peut accéder.

Étape 2 : Définissez votre agent

Un agent est un fichier Markdown. Le frontmatter contient la configuration de l'agent, tandis que le corps contient son prompt système.

Voici un exemple d'agent qui rédige des notes de version à partir d'un dépôt :‍


---
name: Release Notes Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

Le agent_toolset_20260401 permet à l'agent d'accéder aux outils prédéfinis d'Anthropic, incluant des fonctionnalités telles que les commandes shell et les opérations sur les fichiers. Vous pouvez également configurer des outils individuels si vous n'avez pas besoin de l'ensemble complet. Consultez la référence des outils pour connaître les options disponibles.

Enregistrez la configuration sous le nom release-notes-agent.md, puis appliquez-la avec l'interface de ligne de commande ant :

ant apply release-notes-agent.md


Cela crée l'agent et renvoie son identifiant.

L'agent est une ressource persistante. Vous le créez une fois, puis vous référencez son identifiant à chaque fois que vous démarrez une session qui l'utilise ; vous n'avez pas besoin de recréer l'agent pour chaque tâche.

Ensuite, vous allez créer l' environnement dans lequel vos sessions d'agent s'exécuteront.

Étape 3 : Créer un environnement

L'environnement définit le bac à sable (sandbox) dans lequel vos sessions d'agent s'exécutent.

Créez un fichier environment.yaml fichier :‍


# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: release-notes-env
config:
  type: cloud
  networking:
    type: unrestricted

Appliquez-le ensuite :

ant apply environment.yaml


Vous pouvez également appliquer l'agent et l'environnement ensemble :

ant apply release-notes-agent.md environment.yaml

Le paramètre networking: unrestricted donne au bac à sable un accès réseau illimité. Pour les agents qui interagissent avec des systèmes internes ou des données sensibles, utilisez une configuration réseau plus restrictive.

Vous disposez désormais des deux ressources nécessaires pour exécuter un agent :

• Agent : définit ce qu'est l'agent et ce qu'il peut faire.
• Environnement : définit l'endroit où l'agent s'exécute.

Ensuite, vous allez créer une session qui les connecte.

Étape 4 : Démarrer une session

Une session est une instance en cours d'exécution de votre agent travaillant sur une tâche spécifique.

Créez une session en transmettant les identifiants de votre agent et de votre environnement :

session = client.beta.sessions.create( 
  agent=agent.id, 
  environment_id=environment.id, 
  title="Release notes for v2.4", ) 

print(f"Session ID: {session.id}")

L'identifiant de session permet d'identifier cette exécution particulière. Vous l'utiliserez pour envoyer des messages, diffuser des événements et poursuivre vos interactions avec l'agent.

Le même agent peut avoir plusieurs sessions. Par exemple, votre Agent de notes de version vous pouvez exécuter une session distincte pour chaque version tout en conservant la même configuration d'agent.

Étape 5 : Envoyer un message et diffuser la réponse

Une fois la session lancée, envoyez une tâche à l'agent.

Ouvrez d'abord le flux d'événements, puis envoyez le message de l'utilisateur :‍


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": "Read the commits since v2.3 and draft release notes to NOTES.md",
                    },
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")

            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")

            case "session.status_idle":
                print("\n\nAgent finished.")
                break

Derrière cet appel, l'environnement d'exécution géré provisionne le bac à sable à partir de la configuration de votre environnement, démarre la boucle de l'agent, laisse Claude sélectionner et exécuter les outils, et diffuse les événements vers votre application.

Les trois types d'événements ci-dessus sont ceux que vous traiterez généralement en premier :

• agent.message — l'agent envoie une réponse.
• agent.tool_use — l'agent utilise un outil.
• session.status_idle — l'agent a terminé son travail en cours.

Pour obtenir la liste complète des événements, y compris les changements de statut et les erreurs, consultez la documentation de référence sur les événements et le streaming.

À ce stade, vous disposez d'un agent géré fonctionnel : vous l'avez défini, vous lui avez fourni un environnement d'exécution, vous avez démarré une session et vous lui avez envoyé une tâche.

Ensuite, nous verrons comment piloter un agent en cours d'exécution et gérer les sessions de longue durée.

Étape 6 : Piloter un agent en cours d'exécution

Vous n'avez pas besoin d'attendre qu'un agent ait terminé sa tâche pour changer sa direction.

Vous pouvez envoyer un user.interrupt événement pour arrêter le tour en cours, suivi d'un user.message avec la nouvelle instruction :

client.beta.sessions.events.send(
    session.id,
    events=[
        {"type": "user.interrupt"},
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": "Instead, focus on fixing the bug in line 42.",
                },
            ],
        },
    ],
)

L'interruption arrête la réponse actuelle du modèle et redonne le contrôle à la session. Si l'agent est en train d'exécuter un appel d'outil, l'interruption peut prendre plus de temps à s'appliquer le temps que cet outil se termine. Une fois l'interruption traitée, la session revient à l'état inactif, et le user.message suivant démarre le tour suivant.

Ceci est utile pour les tâches de longue durée lorsque vous réalisez que l'agent ne prend pas la bonne direction. Au lieu de terminer la session et de recommencer, vous pouvez réutiliser la même session et la rediriger avec un contexte supplémentaire.

Vous pouvez également interrompre une session en cours sans envoyer immédiatement une nouvelle instruction :‍


client.beta.sessions.events.send(
    session.id,
    events=[
        {"type": "user.interrupt"},
    ],
)

La session reste disponible après l'interruption, ce qui vous permet d'examiner ce qui s'est passé et de décider de la suite à donner.

Ensuite, vous devrez gérer ce qui se passe lorsque votre application perd sa connexion avec une session en cours.

Étape 7 : Gérer les déconnexions et reprendre les sessions

Une connexion en streaming peut être interrompue alors qu'un agent est toujours en train de travailler. Cela ne signifie pas que la session ou son travail sont perdus.

Managed Agents conserve l'historique des événements de la session côté serveur, afin que votre application puisse se reconnecter à la même session au lieu de recommencer la tâche.

L'essentiel est de conserver l'ID de session lors de la création de la session :‍

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Release notes for v2.4",
)

session_id = session.id

Si votre application perd sa connexion, utilisez le même session_id pour vous reconnecter et poursuivre vos interactions avec la session.

C'est crucial pour les agents de longue durée. La fermeture d'un onglet de navigateur, le redémarrage d'un processus ou une coupure réseau temporaire ne devraient pas obliger l'agent à reprendre la tâche depuis le début.

Pour les applications en production, considérez l'ID de session comme un état durable : stockez-le dans un emplacement où votre application pourra le récupérer après un redémarrage, plutôt que de le conserver uniquement en mémoire.

Le flux d'événements n'est que la connexion entre votre application et la session en cours d'exécution. La session elle-même continue d'exister indépendamment de cette connexion.

Ensuite, nous verrons comment doter votre agent de capacités supplémentaires grâce aux serveurs et outils MCP.

Exécution sur votre propre infrastructure

Le bac à sable cloud est l'option par défaut, ce qui empêche certaines équipes de déployer cette solution. Si des règles de résidence des données ou de conformité excluent l'exécution hébergée par Anthropic, les bacs à sable auto-hébergés permettent aux sessions de s'exécuter sur une infrastructure que vous contrôlez, tandis qu'Anthropic continue de gérer la boucle.

Notez ce qui est déplacé et ce qui ne l'est pas : l'exécution est transférée sur votre infrastructure, mais l'orchestration reste chez Anthropic.

Planification d'exécutions récurrentes

Pour les agents qui doivent s'exécuter selon une cadence plutôt qu'à la demande, déploiements planifiés lancent une session selon un calendrier cron. Une tâche de triage nocturne ou un rapport hebdomadaire s'y prête parfaitement, sans que vous ayez à mettre en place un planificateur.

Maîtriser sa facture

La facturation des Claude Managed Agents repose sur deux dimensions : les jetons (tokens) du modèle, ainsi que des frais d'exécution d'environ 0,08 $ par heure de session, couvrant le temps de conteneur.

Trois points importants à connaître dès le début :

Le temps d'inactivité est gratuit ; une session en attente d'une intervention humaine ne génère donc pas de frais d'exécution. Il n'existe pas de remise sur les traitements par lots, le travail que vous traiteriez normalement ainsi coûte donc la même chose ici. Enfin, la recherche web est facturée séparément de la boîte à outils.

Les frais par heure de session représentent généralement le montant le plus faible. Les jetons constituent l'essentiel du coût, et le nombre de jetons consommés par une exécution dépend de la manière dont le système gère le contexte, et non de vos configurations. Nous avons détaillé la structure complète des coûts dans la tarification des Claude Managed Agents.

Où les équipes rencontrent des limites

Deux contraintes ont tendance à apparaître une fois le prototype opérationnel. Le modèle appartient à Anthropic, il est donc impossible de passer à une alternative moins coûteuse lorsque votre volume augmente. De plus, la boucle est gérée par Anthropic, ce qui signifie que la stratégie de contexte n'est pas un paramètre que vous pouvez ajuster.

Si vous êtes en phase d'évaluation et non encore engagé, les alternatives aux Claude Managed Agents couvrent le sujet.

TrueForge : une alternative open source aux Claude Managed Agents, jusqu'à 75 % moins chère

TrueForge est le framework d'agents open source et indépendant des fournisseurs de TrueFoundry, destiné aux équipes souhaitant un meilleur contrôle sur l'exécution de leurs agents en production. Au lieu de lier l'exécution à un seul fournisseur de modèles, TrueForge vous permet d'utiliser vos propres modèles, serveurs MCP et infrastructures, tout en prenant en charge la boucle de l'agent, l'exécution des outils, la gestion du contexte, les approbations et le sandboxing.

Là où un agent auto-hébergé comme Hermes laisse une grande partie de l'infrastructure de production à la charge du développeur, TrueForge fournit le plan de contrôle nécessaire pour exploiter des agents au sein de différentes équipes et environnements. Cela inclut l'accès centralisé aux MCP et aux identifiants, les approbations avec intervention humaine, l'exécution en bac à sable (sandboxing), l'observabilité et la gouvernance.

Vous pouvez l'exécuter localement avec npx @truefoundry/trueforge ou déployez-le pour une équipe avec Docker Compose ou Helm.

TrueForge sépare également l'exécution de l'agent de la couche modèle. Cela signifie que les équipes peuvent changer de modèle ou diriger les charges de travail vers différents fournisseurs sans avoir à reconstruire l'agent lui-même. Associé à l'AI Gateway de TrueFoundry, les équipes peuvent également appliquer un routage de modèle et des contrôles de coûts pour éviter d'utiliser des modèles de pointe coûteux pour des tâches qui ne le nécessitent pas. Le résultat est un juste milieu entre un environnement d'exécution entièrement géré et la création de toute l'infrastructure de l'agent par vous-même : un framework d'agent open source doté des contrôles opérationnels nécessaires pour exécuter des agents en production à grande échelle.‍

Lors du benchmark de TrueFoundry face aux Claude Managed Agents, TrueForge a atteint une précision de tâche quasiment identique tout en utilisant environ 40 % de jetons en moins lorsque les deux étaient exécutés sur Opus 4.8, ce qui le rend environ 30 % moins cher par exécution. Lorsque le même benchmark a été effectué avec GLM-5.2 sur TrueForge, il a obtenu le même score de tâche d'environ 11/14 pour un coût d'environ 2,90 $ par exécution contre 11,80 $ pour les Claude Managed Agents, soit environ 75 % de réduction des coûts.

TrueFoundry fournit également un second levier pour réduire les coûts des modèles grâce à l'Auto Routing de l'AI Gateway. Au lieu d'envoyer chaque requête à un modèle de pointe, l'Auto Routing classe les requêtes par complexité et les dirige vers différents niveaux de modèles. Dans le benchmark de TrueFoundry portant sur 550 prompts, le routage entre Haiku, Sonnet et Opus a réduit les coûts de 69 % tout en conservant 98 % de la qualité de référence, et la latence moyenne est passée de 7,6 secondes à 4,0 secondes. Sur un trafic représentatif de la production, la réduction globale des coûts a atteint 80 %.

Ces deux couches traitent différentes parties de l'équation des coûts. TrueForge réduit la surcharge liée à l'exécution de l'agent lui-même, tandis que le routage de modèle vous permet d'éviter d'utiliser un modèle coûteux lorsque la tâche ne le nécessite pas. Pour les équipes qui exécutent des agents à grande échelle, disposer de ces deux contrôles peut être plus important que le prix du modèle seul.

TrueForge est open source et sous licence MIT, tandis que l'AI Gateway de TrueFoundry ajoute la couche opérationnelle dont les équipes ont besoin lors du passage d'agents individuels à la production : accès centralisé aux modèles, budgets, garde-fous, gestion des identifiants et traces unifiées.

Si vous comparez les agents gérés de Claude avec une architecture plus configurable, TrueFoundry mérite d'être pris en considération lorsque la flexibilité des modèles, le contrôle de l'infrastructure et l'optimisation des coûts des agents comptent autant que l'exécution même de l'agent.

An Open-Source Alternative to Claude Managed Agents, Up to 75% Cheaper

Run production-ready AI agents on your own infrastructure with TrueForge, using your choice of models, tools, and sandbox providers.

View on GitHub

Docs

Ce que les agents gérés ne couvrent pas

Les agents gérés assurent parfaitement l'exécution d'un agent individuel. Ce qu'ils ne font pas, c'est gérer un parc , ce qui devient problématique à partir du cinquième agent, lorsque le service financier demande combien tout cela coûte et que la sécurité demande qui a approuvé les identifiants.

Un environnement d'exécution d'agent contrôle le fonctionnement d'un agent. Une passerelle IA contrôle la manière dont cet agent accède aux modèles.

Par exemple, une organisation peut exécuter des agents en utilisant les agents gérés de Claude ou TrueForge tout en acheminant les requêtes de modèles via une passerelle IA.
La passerelle IA de TrueFoundry se place devant chaque appel de modèle et chaque appel MCP effectué par un agent, appliquant une gestion centralisée de l'accès aux modèles, des budgets par équipe, des limites de débit, des garde-fous, une gestion des identifiants et des traces unifiées, quels que soient les agents et les frameworks utilisés par vos équipes. Elle prend en charge plus de 1 000 LLM via une API unique compatible avec OpenAI, ajoute environ 3 à 4 ms de latence et gère plus de 350 requêtes par seconde sur un seul vCPU. Elle peut donc s'intégrer au chemin critique d'un agent à exécution longue sans devenir un goulot d'étranglement. Elle s'exécute dans votre propre VPC, sur site ou dans un environnement isolé (air-gapped).

Cela devient particulièrement utile lorsqu'une organisation exécute des agents sur plusieurs modèles plutôt que de dépendre d'un seul fournisseur.

Exécution de l'agent : gère la boucle de l'agent, les outils, l'état et l'exécution.

Passerelle IA : gère l'accès aux modèles, le routage, les politiques, l'observabilité et l'abstraction des fournisseurs.

Cette séparation permet aux équipes de modifier ou d'ajouter des modèles sans avoir à reconcevoir l'agent lui-même.

FAQ

Q : Comment utiliser les agents gérés Claude ?

R : Installez l' ant interface en ligne de commande (CLI) et le SDK Anthropic, définissez un agent dans un fichier markdown avec son modèle, son prompt système et ses outils, déclarez un environnement en YAML pour le bac à sable, puis créez une session référençant les deux et diffusez ses événements. Les agents et les environnements sont créés une fois et réutilisés ; les sessions sont propres à chaque tâche. L'ensemble du processus prend environ dix minutes.

Q : L'interface en ligne de commande ant est-elle nécessaire, ou puis-je tout faire depuis le SDK ?

R : L'interface en ligne de commande est pratique mais pas obligatoire. Anthropic documente les chemins cURL et SDK natifs pour chaque étape du guide de démarrage, en Python, TypeScript, Java, Go, C#, Ruby et PHP. Ce que l'interface en ligne de commande ajoute, c'est ant apply et claude-lock.json, qui permettent de versionner les identifiants des agents et des environnements avec votre code, plutôt que de les copier-coller dans une configuration.

Q : Les agents gérés Claude peuvent-ils fonctionner sur ma propre infrastructure ?

R : En partie. Les bacs à sable auto-hébergés permettent aux sessions de s'exécuter sur une infrastructure que vous contrôlez, ce qui est généralement suffisant pour répondre aux exigences de résidence des données. La couche d'orchestration reste chez Anthropic dans tous les cas, il ne s'agit donc pas de faire fonctionner l'intégralité de la pile vous-même.

Q : Est-ce que cela s'intègre à ma pile d'observabilité existante ?

R : La couche passerelle de TrueFoundry est compatible avec OpenTelemetry et se connecte à Grafana, Datadog, Prometheus ou tout autre outil que vous utilisez déjà, en traçant chaque requête, du prompt jusqu'à l'exécution de l'outil et du modèle. C'est essentiel lorsque des agents issus de différents frameworks doivent être centralisés au même endroit.

Q : Comment gérer les modèles et les serveurs MCP pour un grand nombre d'agents ?

R : Via une passerelle, dès que les clés API par équipe ne suffisent plus. L' AI Gateway regroupe plus de 1 000 LLM derrière une API compatible OpenAI, avec une latence ajoutée d'environ 3 à 4 ms et plus de 350 RPS sur un seul vCPU, incluant RBAC, budgets, garde-fous et rotation des identifiants. Les agents utilisant Claude Managed Agents, LangGraph ou tout autre outil sont gouvernés de la même manière.

Lectures complémentaires

• Qu'est-ce que Claude Managed Agents ?: l'architecture derrière les étapes ci-dessus
• Tarification de Claude Managed Agents: le détail complet des coûts avec un exemple concret
• Claude Agent SDK vs Claude Managed Agents: lequel choisir pour la production
• Alternatives à Claude Managed Agents: le paysage actuel, si vous êtes encore en phase d'évaluation
• Bonnes pratiques pour les frameworks d'agents: dix règles applicables quel que soit le framework choisi

Conclusion

Savoir utiliser Claude Managed Agents revient essentiellement à maîtriser quatre objets et l'ordre dans lequel les créer : agent, environnement, session, événements. La configuration est réellement rapide. Les points sur lesquels il vaut la peine de s'attarder sont ceux que le guide de démarrage rapide survole, à savoir la gestion des déconnexions, la configuration réseau de votre environnement et la compréhension de la part de votre facture sur laquelle vous pouvez réellement agir.

Si vous atteignez le stade où le choix du modèle et la stratégie de contexte deviennent plus importants que la rapidité de mise en place, c'est le signe qu'il est temps d'envisager un framework ouvert. npx @truefoundry/trueforge permet d'en exécuter un localement en une minute environ, ou réservez une démonstration si vous préférez le voir à l'œuvre avec votre propre charge de travail.