Qu'est-ce qu'un agent géré ?

Si vous avez construit une boucle d'agent à la main, vous connaissez la routine : boucles while, commutateurs de raison d'arrêt, exécutions d'outils. Cela fonctionne, et pour beaucoup de fonctionnalités, c'est en fait la bonne approche. Mais parfois, cette boucle va s'exécuter très longtemps — des minutes, peut-être même des heures — sur plusieurs outils, avec un état à maintenir, des fichiers à écrire, et du travail à reprendre après une interruption réseau. À ce moment-là, 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.

Un agent géré est une boucle d'agent qui s'exécute sur l'infrastructure d'Anthropic au lieu de la vôtre. Vous décrivez l'agent une fois, vous lui donnez un environnement dans lequel travailler, et vous démarrez une session. Anthropic exécute la boucle, et vous diffusez simplement les événements au fur et à mesure qu'il travaille.

Les agents gérés sont activés par défaut pour chaque compte API — aucun accès spécial nécessaire.

Les quatre primitives

Il y a quatre primitives, et elles viennent dans l'ordre :

Agent — la persona : modèle, invite système et ensemble d'outils. Ceci est réutilisable sur plusieurs exécutions.
Environment — où l'agent s'exécute : cloud ou local, configuration réseau, etc.
Session — une seule exécution d'un agent dans un certain environnement. La session est l'unité de travail.
Events — les messages entrants et sortants : les actions de l'agent, les appels d'outils, les résultats, les réponses.

Voici comment les pièces s'assemblent : votre application communique avec une session, la session pilote le travail dans l'environnement, et tout ce qui se passe revient par le flux d'événements :

Diagramme d'architecture montrant un agent connecté à une Session, qui pilote un Environment, avec les résultats revenant par un Event Stream vers votre application

Remarquez le changement ici : vous n'exécutez pas une boucle while. Vous envoyez des événements et 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 dans le lecteur temporaire, compter ses lignes et faire un rapport.

Pour les outils, nous utiliserons l'ensemble d'outils d'agent — les outils fichier, bash et web groupés d'Anthropic. Ils fonctionnent bien pour cette tâche, donc nous n'avons pas à définir nous-mêmes d'outils.

Étape 1 : Créer l'agent

D'abord, nous créons l'agent. Notez l'ensemble d'outils d'agent défini directement dans le tableau tools — c'est l'ensemble groupé :

import anthropic

client = anthropic. Anthropic()

agent = client. beta. agents. create( name="Line Counter", model="claude-opus-4-8", system="You are a helpful agent that completes small file tasks. ", tools=[ {"type": "agent_toolset_20260401", "default_config": {"enabled": True}} ], )

Souvenez-vous : l'agent est réutilisable. Créez-le une fois et exécutez-le sur plusieurs sessions.

Étape 2 : Créer l'environnement

Ensuite, l'environnement. Cela lance le modèle de conteneur — cloud, avec réseau sans restriction. C'est le bac à sable où le fichier est réellement écrit :

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

Étape 3 : Créer la session

Ensuite, nous créons une session avec notre agent et environnement, plus un titre optionnel. 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

Maintenant, nous ouvrons le flux d'événements — et remarquez que nous le faisons en premier. Le flux ne livre 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 utilisateur dans le flux en direct :

with client. beta. sessions. events. stream(session_id=session. id) as stream:

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 que c'est events — pluriel. Les événements sont la façon dont tout circule dans cette API.

Étape 5 : Consommer le flux

Enfin, nous consommons le flux. Il y a trois types d'événements qui importent pour cette démo :

agent. message — le texte de Claude
agent. tool_use — quel outil Claude a choisi
session. status_idle — l'agent est terminé

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 ---") break

Exécutez-le, et la sortie est l'agent raisonnant à haute voix — du texte réel, les outils qu'il choisit, et une réponse finale. Tout cela s'exécutant dans le conteneur d'Anthropic, pas le vôtre :

Sortie du terminal de l'exécution de l'agent géré : les ID d'agent, d'environnement et de session sont créés, puis le flux d'événements montre l'agent écrivant le fichier, exécutant ses outils et signalant que le fichier contient 3 lignes

Le compromis

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 consommez simplement le flux d'événements au fur et à mesure qu'il arrive.

Dans une application de production, c'est la forme pour les tâches longues, qui touchent des fichiers, « va organiser cela 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 entrant désordonné, déplace les fichiers dans les dossiers de projet appropriés, archive les doublons et les ordures de zéro octet, et signale tout ce qu'il ne peut pas placer avec confiance — 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 alimenté par un agent géré, montrant l'arborescence des dossiers en cours d'organisation aux côtés d'un flux d'activité en direct des événements de l'agent au fur et à mesure qu'il déplace et archive les fichiers :

Une application web de nettoyage de partage de fichiers alimentée par un agent géré, montrant l'arborescence des dossiers en cours d'organisation aux côtés d'un flux d'activité en direct des événements de l'agent

Récapitulatif

Les agents gérés sont la boucle d'agent, exécutée pour vous — sur l'infrastructure d'Anthropic au lieu de votre serveur.
Le flux est : créer un agent, créer un environnement, créer une session, envoyer des événements, et diffuser les événements en sortie.
L'agent (modèle, invite système, ensemble d'outils) est réutilisable sur plusieurs exécutions ; la session est une seule exécution ; les événements sont la façon dont tout circule.
Ouvrez le flux d'événements avant d'envoyer votre message de lancement — il ne livre que les événements qui se produisent après son ouverture.
Surveillez trois événements : agent. message (texte), agent. tool_use (choix d'outils), et session. status_idle (terminé).
Utilisez les agents gérés quand la boucle s'exécuterait trop longtemps, ferait trop de choses, ou devrait survivre à une interruption. Utilisez une boucle manuelle quand vous voulez le contrôle total.