Créer votre premier agent géré

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 seule 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 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 cet ordre :

1. Agent — la persona : modèle, invite système et ensemble d'outils. Elle est réutilisable sur de nombreuses exécutions.
2. Environnement — l'endroit où l'agent s'exécute : cloud ou auto-hébergé, configuration réseau, etc.
3. Session — une exécution unique d'un agent dans un environnement donné. La session est l'unité de travail.
4. É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 ces é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 remonte via le flux d'événements :



Remarquez le changement ici : vous n'exécutez pas une 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 fasse quelque chose d'utile : créer un fichier sur le disque temporaire, compter ses lignes, et rendre compte.

Pour les outils, nous utiliserons l'ensemble d'outils de l'agent — le jeu d'outils fichiers, bash et web fourni par Anthropic. Ils conviennent parfaitement à cette tâche, nous n'avons donc pas besoin de définir nos propres outils.

Étape 1 : créer l'agent

Commençons par créer l'agent. Remarquez l'ensemble d'outils de l'agent défini directement dans le tableau tools — c'est l'ensemble d'outils fourni :

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}}
    ],
)

Rappel : l'agent est réutilisable. Créez-le une fois et exécutez-le sur de nombreuses sessions.

Étape 2 : créer l'environnement

Ensuite, l'environnement. Il définit le bac à sable 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 ne nécessite aucun réseau, nous n'en listons donc aucun. N'utilisez unrestricted que lorsque l'agent doit atteindre des sites que vous ne pouvez pas lister à l'avance. Chaque session dispose de 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, ainsi qu'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 délivre que les événements qui se produisent après son ouverture, il faut donc toujours l'ouvrir avant d'envoyer le message de lancement. Nous envoyons ensuite le message 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 que c'est events — au 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 existe trois types d'événements importants pour cette démonstration :

• agent.message — le texte de Claude
• agent.tool_use — l'outil choisi par Claude
• session.status_idle — l'agent s'est arrêté et attend une saisie

Cette démonstration 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 ---")
            break

Exécutez-le, et le résultat est l'agent qui raisonne à voix haute — du texte réel, les outils qu'il choisit, et une réponse finale. Le tout s'exécutant à l'intérieur du conteneur d'Anthropic, pas du vôtre :



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 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. Ainsi, si votre connexion se coupe, 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 pour le code.

Dans une application en production, c'est la forme adaptée aux tâches longues, manipulant des fichiers, du type « va m'organiser ça ». 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 vides, et signale tout ce qu'il ne peut pas placer avec confiance — le tout dans une session qui peut tourner 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 déroulement est le suivant : 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 exécution unique ; 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 dé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 (arrêté et en attente d'une saisie, avec stop_reason.type indiquant pourquoi).
• Privilégiez les agents gérés lorsque la boucle risque de tourner trop longtemps, de faire trop de choses, ou de devoir survivre à un incident. Privilégiez une boucle manuelle lorsque vous voulez un contrôle total.