Comment créer des agents gérés Claude avec Claude Sonnet 5

Vous avez déjà voulu exécuter, depuis un script Python, un flux de travail à la Claude Code, où le modèle opère dans un environnement géré avec accès à des outils, des fichiers, des skills et des consignes ?

Les Claude Managed Agents sont conçus pour ce type de scénario et vous aident à créer des agents capables d’enchaîner des tâches en plusieurs étapes dans un environnement maîtrisé.

Dans ce tutoriel, je vous montre comment utiliser Claude Sonnet 5, un modèle récent d’Anthropic pensé pour le raisonnement avancé, le codage et l’analyse de données. Il permet à l’agent d’inspecter des données, d’utiliser des outils, d’écrire et d’exécuter du code, et de produire des sorties structurées.

Vous allez créer un Managed Agent, configurer son environnement, téléverser un fichier CSV et donner à l’agent l’accès à des outils et à un skill XLSX. 

L’agent analysera les données, générera des fichiers Python, JSON et Excel, vérifiera les résultats et mettra les livrables à disposition en téléchargement.

Si vous découvrez tout juste Claude, je vous recommande de commencer par le cours Claude Code 101.

Qu’est-ce qu’un Claude Managed Agent ?

Les Claude Managed Agents constituent le cadre géré d’Anthropic pour exécuter Claude en agent autonome. 

Au lieu d’écrire votre propre boucle pour envoyer des prompts, exécuter des appels d’outils, sauvegarder les résultats et gérer l’exécution, vous définissez l’agent et laissez Anthropic prendre en charge cette infrastructure. 

C’est conçu pour des tâches plus longues et multi‑étapes, où le modèle peut devoir utiliser plusieurs outils avant d’achever le travail.

Les Managed Agents s’articulent autour de quatre éléments clés :

• Agent : la configuration réutilisable qui contient le modèle, le prompt système, les outils, les serveurs MCP et les skills.
• Environnement : l’endroit où l’agent s’exécute, soit dans le bac à sable cloud d’Anthropic, soit dans votre propre bac à sable auto‑hébergé.
• Session : une instance en cours d’exécution de l’agent qui réalise une tâche précise.
• Événements : les messages, appels d’outils, résultats et mises à jour d’état échangés pendant la session.

1. Prérequis pour votre espace de travail d’agent Claude

Pour suivre ce tutoriel, installez Python 3.12 ou version ultérieure et Jupyter Notebook sur votre ordinateur. Nous utiliserons un Jupyter Notebook pour créer, exécuter et inspecter pas à pas le Managed Agent.

Vous aurez également besoin d’un compte Anthropic Console. 

Créez une nouvelle clé d’API dans la Console, ajoutez au moins 5 $ de crédits API et conservez la clé en lieu sûr. 

Les Managed Agents peuvent effectuer plusieurs appels au modèle et aux outils dans une même session, leur coût peut donc être supérieur à une requête API standard.

Stockez la clé dans une variable d’environnement ANTHROPIC_API_KEY plutôt que de l’ajouter directement au notebook ou de la valider sur GitHub.

Sur macOS, Linux ou WSL, exécutez ceci dans votre terminal :

export ANTHROPIC_API_KEY="your-api-key-here"

Sur Windows PowerShell, utilisez :

$env:ANTHROPIC_API_KEY="your-api-key-here"

2. Configurer le SDK Python Anthropic

Avant de créer un Managed Agent, installez le SDK Python officiel d’Anthropic et importez les modules nécessaires pour ce notebook. 

Le SDK fournit le client Anthropic, que vous utiliserez pour créer des agents, des environnements, des fichiers et des sessions. 

%pip install -q --upgrade anthropic

Ensuite, chargez votre clé API Anthropic depuis une variable d’environnement. 

Garder la clé en dehors du notebook est plus sûr que de l’insérer dans le code, surtout si vous prévoyez de partager le projet ou de le pousser sur GitHub.

import os
from anthropic import Anthropic

api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."

Les Managed Agents sont actuellement accessibles via l’API bêta d’Anthropic. Le flag bêta managed-agents-2026-04-01 active cette fonctionnalité, même si le SDK officiel envoie automatiquement l’en-tête bêta requis pour les requêtes Managed Agents. 

Nous conservons le flag dans le notebook car il sera nécessaire plus tard pour lister et télécharger les fichiers de session. 

BETA_FLAG = "managed-agents-2026-04-01"

client = Anthropic(api_key=api_key)

Enfin, créez un dictionnaire pour stocker les ID de chaque ressource créée durant le tutoriel. 

Cela inclut l’agent, l’environnement, le fichier téléversé et la session. Conserver ces ID facilite le nettoyage final, même si une étape ultérieure échoue.

created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")

Le client est prêt. 

3. Créer le Managed Agent

Un Managed Agent est la configuration réutilisable de votre flux de travail. 

Lors de sa création, vous choisissez le modèle Claude, rédigez le prompt système qui définit son rôle et ses consignes, et rattachez les outils et skills qu’il peut utiliser. 

Vous pouvez ensuite réutiliser le même agent sur plusieurs sessions sans recréer la configuration à chaque fois. 

Nous nommerons notre agent Sonnet 5 Data Analyst et utiliserons claude-sonnet-5. 

Le prompt système lui demande d’agir comme un·e analyste de données rigoureux·se : inspecter les fichiers montés dans /workspace, utiliser l’exécution de code pour l’analyse, rester concis dans les résultats et sauvegarder les fichiers finaux dans /mnt/session/outputs.

agent = client.beta.agents.create(
    name="Sonnet 5 Data Analyst",
    model="claude-sonnet-5",
    system=(
        "You are a meticulous data analyst. When asked about data, always read the "
        "file mounted at /workspace, analyse it with the code execution tool, and "
        "report concise, numeric results. Use the XLSX skill for spreadsheet work. "
        "Save final artifacts to /mnt/session/outputs."
    ),
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)

Le agent_toolset_20260401 donne à l’agent accès aux outils intégrés d’Anthropic dans une session, tandis que le skill xlsx apporte des consignes spécifiques pour créer et analyser des classeurs Excel. 

Anthropic propose aussi des skills prêts à l’emploi pour des workflows PowerPoint, Word et PDF.

Enfin, enregistrez l’ID de l’agent. 

Vous l’utiliserez plus tard pour créer une session, et la section de nettoyage s’en servira pour archiver l’agent une fois le tutoriel terminé.

created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")

Vous devriez voir une sortie similaire :

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Configurer le bac à sable cloud Anthropic

Créons maintenant l’environnement où le Managed Agent s’exécutera pendant une session. 

Un environnement agit comme un bac à sable sécurisé, offrant à l’agent un espace de travail séparé pour lire les fichiers montés, écrire du code et lancer des commandes.

Nous utiliserons l’environnement cloud d’Anthropic avec un réseau limité. L’agent exploitera ce bac à sable pour analyser ensuite le fichier CSV téléversé avec Python.

environment = client.beta.environments.create(
    name="code-exec-sandbox",
    config={"type": "cloud", "networking": {"type": "limited"}},
)

created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")

Après exécution, vous devriez voir un ID d’environnement de ce type :

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Téléverser des données avec l’API Files d’Anthropic

Nous allons maintenant téléverser le jeu de données que l’agent analysera. 

Les Managed Agents utilisent l’API Files d’Anthropic pour importer des fichiers locaux, qui peuvent ensuite être montés dans l’environnement de session.

Pour ce guide, nous utilisons l’exemple de jeu de données de 12 lignes nommé sales_data.csv. 

Avant de l’envoyer, nous vérifions que le fichier existe et qu’il contient bien le nombre attendu de lignes de données.

from pathlib import Path

csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"

row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"

Nous téléversons ensuite le fichier et conservons son ID pour le nettoyage ultérieur.

uploaded = client.beta.files.upload(file=csv_path)

created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")

Après exécution, vous devriez voir une sortie du type :

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Initialiser une session d’exécution d’agent

Créons à présent une session. 

Une session relie l’agent, l’environnement et les ressources nécessaires pour une tâche donnée. Ici, nous montons le fichier CSV téléversé à l’emplacement /workspace/sales_data.csv, afin que l’agent y accède depuis le bac à sable.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": uploaded.id,
            "mount_path": "/workspace/sales_data.csv",
        },
    ],
)

created["session"] = session.id
print(f"✓ Created session: {session.id}")

Vous devriez voir un ID de session semblable à :

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Diffuser la réponse de l’agent

Nous allons maintenant envoyer la tâche à la session et diffuser en continu l’activité de l’agent pendant son exécution. 

Créer une session ne fait que préparer l’agent et le bac à sable ; l’agent démarre une fois qu’il reçoit un événement user.message. 

Le flux d’événements nous permet d’observer en temps réel les messages de l’agent, ses appels d’outils et l’état final de la session. 

Le prompt demande à l’agent d’analyser le CSV monté, d’écrire et d’exécuter un script Python, de créer un résumé JSON et de produire un rapport Excel. 

Nous créons aussi trois variables pour collecter le texte de l’agent, enregistrer les outils utilisés et confirmer si la session se termine correctement.

agent_text_parts = []
tools_used = []
final_status = None

with client.beta.sessions.events.stream(session.id) as stream:
    # Send the user message once the stream is open.
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Use the XLSX skill and analyze /workspace/sales_data.csv. "
                            "Write /mnt/session/outputs/analyze_sales.py, run that Python "
                            "script, and have it create /mnt/session/outputs/summary.json. "
                            "Also create /mnt/session/outputs/sales_report.xlsx with the "
                            "source data, monthly profit, and a summary sheet."
                        ),
                    }
                ],
            }
        ],
    )

    for event in stream:
        etype = getattr(event, "type", None)

        if etype == "agent.message":
            for block in event.content:
                txt = getattr(block, "text", None)
                if txt:
                    print(txt, end="")
                    agent_text_parts.append(txt)

        elif etype == "agent.tool_use":
            name = getattr(event, "name", "<tool>")
            print(f"\n[tool_use] {name}")
            tools_used.append(name)

        elif etype == "session.status_idle":
            final_status = "idle"
            print("\n\n✓ Agent finished; session is idle.")
            break

        elif etype == "session.status_error":
            final_status = "error"
            print("\n✗ Session reported an error.")
            break

print("Tools used:", tools_used)

Pendant l’exécution, vous devriez voir des événements d’outils tels que read, bash, write et edit. 

Ils indiquent que l’agent inspecte les consignes et fichiers disponibles, rédige le script d’analyse, l’exécute dans le bac à sable et corrige les problèmes détectés.

Une session passe à l’état idle lorsque l’agent n’a plus de travail à accomplir. Dans cet exemple, session.status_idle signifie que la tâche est terminée, nous arrêtons donc l’écoute du flux. 

Anthropic gère l’exécution de ses outils intégrés dans le bac à sable ; vous n’avez à traiter vous‑même les résultats d’outils que pour vos outils personnalisés. 

8. Récupérer les fichiers générés et l’historique des événements

Une fois la session terminée, nous pouvons examiner son historique d’événements et télécharger les fichiers créés par l’agent. 

L’historique fournit un enregistrement complet de la session, y compris les requêtes au modèle, les appels d’outils, leurs résultats et les changements d’état.

history = client.beta.sessions.events.list(session.id, order="asc")

print("--- Session event history ---")
for event in history.data:
    print(event.type)

print(f"({len(history.data)} events total)")

Ensuite, nous listons les fichiers rattachés à la session et téléchargeons ceux marqués comme téléchargeables. Les fichiers sont enregistrés localement dans un dossier outputs.

import os

os.makedirs("outputs", exist_ok=True)

files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]

print(f"Found {len(downloadable)} downloadable file(s) for this session.")

downloaded_paths = []

for f in downloadable:
    try:
        content = client.beta.files.download(f.id, betas=[BETA_FLAG])
        local_path = os.path.join("outputs", f.filename)

        content.write_to_file(local_path)
        downloaded_paths.append(local_path)

        print(f"  downloaded {f.id} -> {local_path}")
    except Exception as exc:
        print(f"  skip {f.id}: {exc}")

Enfin, nous vérifions que toutes les sorties attendues ont bien été téléchargées :

expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}

assert expected_outputs <= downloaded_names, (
    f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)

Le script Python, le résumé JSON et le rapport Excel générés sont désormais disponibles dans le dossier local outputs.

9. Analyser les sorties Python, JSON et Excel

Après l’exécution de l’agent, les fichiers générés sont téléchargés dans le répertoire local outputs/. 

Ces fichiers montrent que l’agent a fait plus que renvoyer du texte : il a écrit et exécuté du code, créé des données structurées et produit un rapport tableur qui peut être relu indépendamment.

Les captures ci‑dessous montrent les trois artefacts générés.

Ce fichier contient le code d’analyse écrit et exécuté par l’agent, rendant le flux de travail reproductible et facile à auditer.

Ce fichier stocke les résultats dans un format structuré exploitable par des tableaux de bord, des API ou d’autres programmes.

Ce fichier Excel présente visuellement les calculs mensuels : chiffre d’affaires, coûts, profit, marges, totaux et un graphique.

Pour les 12 lignes de sales_data.csv, les résultats vérifiés sont :

• Chiffre d’affaires total : 32 900 $
• Coûts totaux : 14 750 $
• Profit total : 18 150 $
• Profit mensuel moyen : 1 512,50 $
• Meilleur mois : décembre (2 550 $ de profit)
• Pire mois : janvier (400 $ de profit)

Le classeur s’appuie sur des formules plutôt que sur des valeurs figées. 

Pendant l’exécution, l’agent a lu les consignes du skill XLSX joint, créé le classeur, l’a recalculé avec LibreOffice, a vérifié les formules et corrigé un problème de référence circulaire avant de terminer la tâche.

10. Nettoyer les ressources de l’API Managed Agent

Les ressources d’un Managed Agent restent disponibles jusqu’à leur suppression, il est donc important de les nettoyer une fois la tâche terminée. 

Des ressources actives, notamment des sessions et environnements en cours, peuvent continuer à générer des coûts si on les laisse tourner.

Une session doit être à l’état idle avant de pouvoir être supprimée. 

Dans cette dernière étape, nous supprimons la session, le fichier téléversé et l’environnement, puis nous archivons l’agent. 

Chaque action de nettoyage est encapsulée dans une fonction utilitaire afin qu’un échec n’empêche pas la suppression des autres ressources.

def safe(label, fn):
    try:
        fn()
        print(f"✓ deleted {label}")
    except Exception as exc:
        print(f"· could not delete {label}: {exc}")

if created["session"]:
    safe("session", lambda: client.beta.sessions.delete(created["session"]))

if created["file"]:
    safe("file", lambda: client.beta.files.delete(created["file"]))

if created["environment"]:
    safe("environment", lambda: client.beta.environments.delete(created["environment"]))

if created["agent"]:
    safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))

print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")

Vous devriez voir une sortie du type :

✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)

🎉 Cleanup complete. The agent is archived; other resources were deleted.

Le projet complet, incluant le notebook, le fichier CSV d’exemple et les instructions d’installation, est disponible sur GitHub. 

Vous pouvez cloner le référentiel et relancer le notebook pour reproduire les résultats de ce guide.

Dernières réflexions

J’ai trouvé les Claude Managed Agents simples à configurer et à utiliser. 

Vous créez un agent, vous lui donnez les outils, les skills et le bac à sable nécessaires, puis vous l’exécutez via une session. 

À partir de là, il peut gérer un flux de travail complet : écrire du code, créer des fichiers, vérifier ses propres sorties et renvoyer les résultats finaux.

J’ai d’abord tenté d’utiliser un Modal Sandbox pour bénéficier d’un environnement externe plus flexible. 

Toutefois, la mise en place s’est révélée trop complexe pour le cadre de ce guide, j’ai donc choisi de me concentrer sur le bac à sable cloud géré par Anthropic.

Le principal inconvénient, pour moi, a été le coût. J’ai exécuté deux fois cet exemple avec un petit CSV de seulement 12 lignes, et cela m’a coûté environ 0,25 $. 

Le tableau de bord affichait la facturation au niveau du modèle, mais je n’ai pas trouvé de ventilation détaillée. Pour un calcul simple et un rapport tableur, cela semble coûteux comparé à des options open source moins chères.

Globalement, ce projet illustre l’ensemble du workflow Managed Agent : créer un agent, téléverser un CSV, exécuter Python dans un bac à sable géré, générer des rapports JSON et Excel, vérifier les sorties, télécharger les fichiers et nettoyer les ressources ensuite.