Créer votre premier agent géré
Si vous avez déjà construit une boucle d'agent à la main, vous connaissez la routine : boucles while, aiguillages sur la raison d'arrêt, exécutions d'outils. Cela fonctionne, et pour beaucoup de fonctionnalités, c'est d'ailleurs la bonne approche. Mais parfois, cette boucle va devoir s'exécuter pendant très longtemps — des minutes, voire des heures — à travers de nombreux outils, avec un état à conserver, des fichiers à écrire, et du travail à reprendre après un incident réseau. À ce stade, vous ne voulez pas exécuter la boucle sur votre serveur. Vous voulez la déléguer. C'est ce que sont les agents gérés.
Qu'est-ce qu'un agent géré ?
Un agent géré est une boucle d'agent qui s'exécute sur l'infrastructure d'Anthropic plutôt que sur la vôtre. Vous décrivez l'agent une fois, vous lui donnez un environnement dans lequel travailler, puis vous démarrez une session. Anthropic exécute la boucle, et vous n'avez plus qu'à diffuser les événements en streaming au fur et à mesure qu'elle avance.
Les agents gérés sont activés par défaut pour chaque compte API — aucun accès spécial n'est nécessaire.
Les quatre primitives
Il existe quatre primitives, et elles s'enchaînent dans un ordre précis :
- Agent — la persona : modèle, invite système et jeu d'outils. Elle est réutilisable pour de nombreuses exécutions.
- Environnement — l'endroit où l'agent s'exécute : cloud ou auto-hébergé, configuration réseau, etc.
- Session — une exécution unique d'un agent dans un environnement donné. La session est l'unité de travail.
- Événements — les messages qui circulent dans les deux sens : les actions de l'agent, les appels d'outils, les résultats, les réponses.
Voici comment les éléments s'articulent : votre application communique avec une session, la session pilote le travail à l'intérieur de l'environnement, et tout ce qui se produit ressort via le flux d'événements :

Remarquez le changement : vous n'exécutez pas de boucle while. Vous envoyez des événements et vous lisez des événements.
Le plus petit agent géré possible
Construisons le plus petit agent géré qui fait quelque chose d'utile : créer un fichier sur le disque temporaire, compter ses lignes, et en rendre compte.
Pour les outils, nous allons utiliser le jeu d'outils de l'agent — les outils de fichiers, bash et web regroupés par Anthropic. Ils conviennent parfaitement à cette tâche, nous n'avons donc pas besoin de définir nous-mêmes d'outils.
Étape 1 : créer l'agent
Pour commencer, nous créons l'agent. Remarquez le jeu d'outils de l'agent défini directement dans le tableau tools — c'est le jeu d'outils regroupé :
import anthropic
client = anthropic.Anthropic()
agent = client.beta.agents.create(
name="Line Counter",
model="claude-opus-5",
system="You are a helpful agent that completes small file tasks.",
tools=[
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}
],
)N'oubliez pas : l'agent est réutilisable. Créez-le une fois et exécutez-le dans de nombreuses sessions.
Étape 2 : créer l'environnement
Ensuite, l'environnement. Il définit le bac à sable (sandbox) dans lequel votre agent s'exécute : cloud, avec un réseau limited. Avec limited, le bac à sable et les outils web n'atteignent que les hôtes que vous listez dans allowed_hosts. Cette tâche n'a besoin d'aucun réseau, donc nous n'en listons aucun. N'utilisez unrestricted que lorsque l'agent doit atteindre des sites que vous ne pouvez pas lister à l'avance. Chaque session obtient son propre bac à sable, et c'est là que le fichier est écrit :
environment = client.beta.environments.create(
name="line-counter-env",
config={
"type": "cloud",
"networking": {"type": "limited"},
},
)Étape 3 : créer la session
Ensuite, nous créons une session avec notre agent et notre environnement, plus un titre facultatif. La session est l'unité de travail :
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Count lines demo",
)Étape 4 : ouvrir le flux, puis envoyer le message de lancement
Nous ouvrons maintenant le flux d'événements — et remarquez que nous le faisons en premier. Le flux ne transmet que les événements qui se produisent après son ouverture, donc ouvrez-le toujours avant d'envoyer le message de lancement. Ensuite, nous envoyons le message de l'utilisateur dans le flux en direct :
with client.beta.sessions.events.stream(session_id=session.id) as stream:
# Le flux est ouvert — envoyez maintenant le message de lancement
client.beta.sessions.events.send(
session_id=session.id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Create a file in the temp directory, "
"count its lines, and report back.",
}
],
}
],
)Remarquez qu'il s'agit d'events — au pluriel. Les événements sont la manière dont tout circule dans cette API.
Étape 5 : consommer le flux
Enfin, nous consommons le flux, toujours à l'intérieur du bloc with de l'étape 4. Il y a trois types d'événements qui comptent pour cette démo :
agent.message— le texte de Claudeagent.tool_use— l'outil que Claude a choisisession.status_idle— l'agent s'est arrêté et attend une saisie
Cette démo s'arrête au premier événement idle. Dans votre propre application, vérifiez event.stop_reason.type avant de considérer le travail comme terminé : end_turn signifie que l'agent a terminé son tour ou que vous l'avez interrompu, et requires_action signifie qu'un appel d'outil nécessite une réponse de votre part.
for event in stream:
if event.type == "agent.message":
for block in event.content:
if block.type == "text":
print(block.text, end="", flush=True)
elif event.type == "agent.tool_use":
print(f"\n[tool] {event.name}")
elif event.type == "session.status_idle":
print("\n--- Agent done ---")
breakExécutez-le, et le résultat montre l'agent qui raisonne à voix haute — du vrai texte, les outils qu'il choisit, et une réponse finale. Le tout s'exécutant dans le conteneur d'Anthropic, pas dans le vôtre :

L'échange
Habituellement, avec les agents, nous avons notre propre boucle où nous devons tout contrôler. Avec les agents gérés, vous déléguez cette boucle, le bac à sable et la capacité de reprise — et vous vous contentez de consommer le flux d'événements au fur et à mesure qu'il arrive. L'historique des événements de la session est stocké sur le serveur. Donc si votre connexion tombe, ouvrez un nouveau flux, listez les événements passés pour voir ce que vous avez manqué, et ignorez tout événement en direct déjà renvoyé par la liste. Consultez Se reconnecter sans manquer d'événements(s’ouvre dans un nouvel onglet) pour le code.
Dans une application de production, c'est la forme adaptée aux tâches de longue durée, qui touchent des fichiers, du type « va organiser ça pour moi ». Imaginez un nettoyage de partage de fichiers : un agent géré lit une spécification de structure de répertoire cible, parcourt le dossier d'arrivée en désordre, déplace les fichiers vers les bons dossiers de projet, archive les doublons et les fichiers de taille nulle, et signale tout ce qu'il ne peut pas placer avec certitude — le tout dans une session qui peut s'exécuter pendant des minutes sur des milliers de fichiers. Voici à quoi cela ressemble dans une application réelle — un tableau de bord de nettoyage de partage de fichiers diffusant en direct l'activité de l'agent pendant qu'il trie, archive et signale des fichiers :

Récapitulatif
- Les agents gérés sont la boucle d'agent, exécutée pour vous — sur l'infrastructure d'Anthropic plutôt que sur votre serveur.
- Le flux de travail est : créer un agent, créer un environnement, créer une session, envoyer des événements, et diffuser des événements en retour.
- L'agent (modèle, invite système, jeu d'outils) est réutilisable d'une exécution à l'autre ; la session est une exécution unique ; les événements sont la manière dont tout circule.
- Ouvrez le flux d'événements avant d'envoyer votre message de lancement — il ne transmet que les événements qui se produisent après son ouverture.
- Surveillez trois événements :
agent.message(texte),agent.tool_use(choix d'outils), etsession.status_idle(arrêté et en attente de saisie, avecstop_reason.typeindiquant pourquoi). - Faites appel aux agents gérés lorsque la boucle risque de durer trop longtemps, d'en faire trop, ou de devoir résister à un incident. Faites appel à une boucle manuelle lorsque vous souhaitez un contrôle total.