Managed Agents Anthropic : Déployer des agents IA autonomes en production

Qu'est-ce qu'un agent IA avec Claude ?

Un agent IA se distingue d'un chatbot classique par une capacité fondamentale : l'autonomie d'exécution. Alors qu'un chatbot répond à des prompts un par un, un agent reçoit un objectif, décompose le travail en sous-tâches, sélectionne les outils nécessaires et exécute chaque étape de manière autonome. Il lit des fichiers, écrit du code, lance des commandes shell, interroge des APIs et itère jusqu'à obtenir le résultat attendu. Ces agents constituent le composant le plus avancé de l'écosystème Claude d'Anthropic.

Avec Claude, cette boucle agent suit un cycle structuré : analyser la requête, décomposer en sous-tâches, exécuter les outils dans un environnement isolé, coordonner les flux parallèles quand c'est pertinent, puis livrer les résultats. Le modèle décide à chaque étape quel outil utiliser et quand s'arrêter.

Anthropic propose deux approches architecturales distinctes pour construire ces agents. Le choix entre les deux depend de vos contraintes d'infrastructure, de contrôle et de cas d'usage.

Agent SDK vs Managed Agents : deux philosophies

La différence fondamentale entre les deux approches tient en une question : où tourne l'agent et qui gère l'infrastructure ? L'Agent SDK vous donne un contrôle total en exécution locale. L'API Managed Agents délègue l'infrastructure à Anthropic dans des conteneurs cloud sandboxes.

Quand utiliser l'Agent SDK

L'Agent SDK est le bon choix quand vous avez besoin d'intégrer un agent dans vos pipelines CI/CD existants, quand vous construisez des applications de bureau avec un accès direct au filesystem, ou quand vous voulez un contrôle granulaire sur chaque outil. Le SDK gère la boucle d'outils de manière autonome — la différence avec le Client SDK classique est que vous n'avez plus à implémenter la boucle while/tool_use vous-même.

Quand utiliser les Managed Agents

Les Managed Agents sont adaptés aux tâches qui tournent pendant des minutes ou des heures, quand vous avez besoin d'une isolation sandbox complète, ou quand vous ne voulez pas gérer l'exécution des outils ni la boucle agent. Les sessions sont stateful et persistent entre les interactions, ce qui permet des workflows asynchrones complexes.

Agent SDK en pratique : architecture et code

L'Agent SDK s'installe via pip ou npm. Le point d'entrée principal est la fonction query(), qui crée un agent, exécute la boucle d'outils et streame les résultats en temps réel. Voici un agent minimal qui lit du code, trouve un bug et le corrige :

1import asyncio
2from claude_agent_sdk import query, ClaudeAgentOptions
3 
4async def main():
5    async for message in query(
6        prompt="Find and fix the bug in auth.py",
7        options=ClaudeAgentOptions(
8            allowed_tools=["Read", "Edit", "Bash"]
9        ),
10    ):
11        print(message)
12 
13asyncio.run(main())

L'agent dispose d'outils built-in immédiatement utilisables : Read et Write pour les fichiers, Bash pour les commandes terminal, Glob et Grep pour la recherche, WebSearch et WebFetch pour le web. Aucune implémentation manuelle n'est nécessaire -- l'agent les exécute de manière autonome.

Hooks et guardrails : sécuriser l'agent

Les hooks permettent d'exécuter du code custom aux points clés du lifecycle de l'agent. Un hook PreToolUse peut bloquer un appel d'outil avant exécution. Un hook PostToolUse peut valider le résultat. Un hook Stop peut empêcher l'agent de s'arrêter prématurément. Voici un exemple de hook d'audit :

1from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
2 
3async def log_file_change(input_data, tool_use_id, context):
4    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
5    with open("./audit.log", "a") as f:
6        f.write(f"{datetime.now()}: modified {file_path}\n")
7    return {}
8 
9async for message in query(
10    prompt="Refactor utils.py to improve readability",
11    options=ClaudeAgentOptions(
12        permission_mode="acceptEdits",
13        hooks={
14            "PostToolUse": [
15                HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
16            ]
17        },
18    ),
19):
20    if hasattr(message, "result"):
21        print(message.result)

Sessions et persistance de contexte

Le SDK permet de maintenir le contexte entre plusieurs échanges. On capture l'ID de session au premier appel via l'évènement SystemMessage(subtype="init"), puis on le réutilise avec l'option resume. L'agent retrouve ainsi tout le contexte de la conversation précédente sans avoir à tout ré-expliquer.

Managed Agents : l'API cloud pour les tâches longues

L'API Managed Agents repose sur quatre concepts : un Agent (modèle, system prompt, outils), un Environment (template de conteneur), une Session (instance en exécution) et des Events (messages bidirectionnels). Quand vous envoyez un événement utilisateur, Anthropic provisionne un conteneur, exécute la boucle agent, lance les outils dans le sandbox, et streame les résultats en temps réel.

Créer un agent et lancer une session

Le workflow de création suit trois étapes : créer un agent, créer un environnement, puis lancer une session. Le toolset agent_toolset_20260401 active l'ensemble complet d'outils pré-construits (Bash, Read, Write, Edit, Glob, Grep, web_fetch, web_search).

1from anthropic import Anthropic
2client = Anthropic()
3 
4# 1. Creer l'agent
5agent = client.beta.agents.create(
6    name="Data Analyst",
7    model="claude-sonnet-4-6",
8    system="Analyse les donnees et produis des rapports structures.",
9    tools=[{"type": "agent_toolset_20260401"}],
10)
11 
12# 2. Creer l'environnement
13environment = client.beta.environments.create(
14    name="analytics-env",
15    config={
16        "type": "cloud",
17        "packages": {"pip": ["pandas", "numpy", "matplotlib"]},
18        "networking": {"type": "limited", "allowed_hosts": ["api.example.com"]},
19    },
20)
21 
22# 3. Lancer la session
23session = client.beta.sessions.create(
24    agent=agent.id,
25    environment_id=environment.id,
26    title="Analyse trimestrielle",
27)

Streaming SSE et évènements

La communication est entièrement basée sur les événements Server-Sent Events (SSE). Vous ouvrez un stream, envoyez un message utilisateur, puis traitez les évènements au fil de l'eau. L'agent émet des événements agent.message pour le texte, agent.tool_use pour les appels d'outils, et session.status_idle quand il a terminé.

Patterns d'orchestration multi-agent

Les deux approches supportent l'orchestration multi-agent, mais avec des mécanismes différents.

Pattern Orchestrator avec l'Agent SDK

Dans l'Agent SDK, vous définissez des subagents spécialisés que l'agent principal peut invoquer. Chaque subagent a son propre system prompt, ses outils et sa spécialisation. L'agent orchestrateur délègue les sous-tâches et agrège les résultats. Les messages des subagents incluent un champ parent_tool_use_id pour tracer l'origine de chaque réponse.

1from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
2 
3async for message in query(
4    prompt="Review this codebase, then write tests for critical paths",
5    options=ClaudeAgentOptions(
6        allowed_tools=["Read", "Glob", "Grep", "Agent"],
7        agents={
8            "code-reviewer": AgentDefinition(
9                description="Expert code reviewer.",
10                prompt="Analyse la qualite du code et identifie les problemes.",
11                tools=["Read", "Glob", "Grep"],
12            ),
13            "test-writer": AgentDefinition(
14                description="Expert en ecriture de tests.",
15                prompt="Ecris des tests unitaires complets.",
16                tools=["Read", "Write", "Bash"],
17            ),
18        },
19    ),
20):
21    print(message)

Pattern Orchestrator avec Managed Agents

Dans l'API Managed Agents, l'orchestration repose sur des threads isolés. Un agent coordinateur délègue à d'autres agents qui tournent chacun dans leur propre thread avec un contexte séparé. Tous les agents partagent le meme conteneur et filesystem, mais leurs outils et contextes ne sont pas partagés. Un point important : un seul niveau de délégation est autorisé — les agents délégués ne peuvent pas déléguer à leur tour.

Pattern Handoff : transfert de responsabilité

Le pattern handoff consiste à transférer complètement le contrôle d'un agent à un autre. Cas d'usage typique : un agent de triage reçoit les demandes, classifie le type de travail, puis transfère au spécialiste adéquat (code review, generation de tests, recherche). Le thread persiste, ce qui permet au coordinateur d'envoyer un suivi à un agent appelé précédemment.

Pattern Guardrails : validation en boucle

Le pattern guardrails combine hooks (Agent SDK) ou outcomes (Managed Agents) pour valider le travail de l'agent à chaque étape. Avec les Managed Agents, le mécanisme d'Outcomes est particulièrement puissant : vous définissez un rubric détaillé, et un grader indépendant évalue l'artefact produit. Si le résultat ne satisfait pas les critères, l'agent itère automatiquement (jusqu'à 20 itérations maximum).

Cas d'usage réels en production

Les agents IA avec Claude ne sont pas un exercice théorique. Voici des scénarios concrets où chaque approche excelle.

Déployer un agent en production : guide étape par étape

Évolution des agents IA chez Anthropic

L'écosysteme agent d'Anthropic a évolué rapidement. Voici les jalons clés qui ont mené à l'offre actuelle.

Fonctionnalités avancées : Memory et Outcomes

Memory Stores : persistance cross-session

Par défaut, les sessions Managed Agents sont éphémères. Les Memory Stores résolvent ce problème en permettant à l'agent de conserver des apprentissages entre sessions : préférences utilisateur, conventions de projet, erreurs passées. Chaque memory store peut contenir plusieurs documents texte, chacun plafonné a 100 Ko. Jusqu'à 8 memory stores peuvent être attachés à une session.

Quand un memory store est attaché, l'agent obtient automatiquement les outils memory_list, memory_search, memory_read, memory_write et memory_edit. Le système inclut des écritures sécurisées avec concurrence optimiste et un historique de versions immutable pour l'audit.

Outcomes : transformer les sessions en travail mesurable

Les Outcomes transforment une session de conversation en travail. Vous définissez le résultat attendu via un rubric détaillé avec des critères explicites et évaluables. Le harness provisionne automatiquement un grader qui évalue l'artéfact dans une fenêtre de contexte séparée pour éviter les biais. Si le résultat ne satisfait pas les critères (needs_revision), l'agent itère automatiquement. Les livrables sont écrits dans /mnt/session/outputs/ et récupérables via la Files API.

Environnements : sandboxing et isolation

La sécurité d'un agent en production dépend directement de son isolation. Les environnements Managed Agents offrent un sandboxing complet avec des conteneurs cloud configurés à la demande.

Vous pouvez pré-installer des packages via six gestionnaires (apt, cargo, gem, go, npm, pip), configurer le reseau en mode unrestricted (défaut) ou limited avec une liste blanche de domaines. En production, utilisez toujours le mode limited avec des allowed_hosts explicites. Les packages sont cachés entre sessions partageant le même environnement, ce qui accélère les démarrages.

Conclusion : choisir sa strategie agent

L'écosystème agent d'Anthropic offre deux voies complémentaires. L'Agent SDK convient aux équipes qui veulent un contrôle total sur l'exécution et l'intégration dans des pipelines existants. L'API Managed Agents convient aux équipes qui préfèrent déléguer l'infrastructure et se concentrer sur la logique métier. Les deux partagent le même moteur Claude, les mêmes outils, et le même standard MCP pour l'extensibilité.

Le choix n'est d'ailleurs pas exclusif : beaucoup d'architectures combinent les deux. L'Agent SDK pour les tâches locales rapides en CI/CD, les Managed Agents pour les workflows longs et asynchrones. L'essentiel est de commencer avec un scope restreint, des guardrails solides, et d'élargir progressivement la surface d'action de l'agent. Le prototypage d'agents commence souvent dans Claude Code, avant un passage en production via l'API Managed Agents.