Managed Agents Anthropic : Deployer 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 capacite fondamentale : l'autonomie d'execution. Alors qu'un chatbot repond a des prompts un par un, un agent recoit un objectif, decompose le travail en sous-taches, selectionne les outils necessaires et execute chaque etape de maniere autonome. Il lit des fichiers, ecrit du code, lance des commandes shell, interroge des APIs et itere jusqu'a obtenir le resultat attendu.

Avec Claude, cette boucle agent suit un cycle structure : analyser la requete, decomposer en sous-taches, executer les outils dans un environnement isole, coordonner les flux paralleles quand c'est pertinent, puis livrer les resultats. Le modele decide a chaque etape quel outil utiliser et quand s'arreter.

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

Agent SDK vs Managed Agents : deux philosophies

La difference fondamentale entre les deux approches tient en une question : ou tourne l'agent et qui gere l'infrastructure ? L'Agent SDK vous donne un controle total en execution locale. L'API Managed Agents delegue l'infrastructure a Anthropic dans des conteneurs cloud sandboxes.

Quand utiliser l'Agent SDK

L'Agent SDK est le bon choix quand vous avez besoin d'integrer un agent dans vos pipelines CI/CD existants, quand vous construisez des applications de bureau avec un acces direct au filesystem, ou quand vous voulez un controle granulaire sur chaque outil. Le SDK gere la boucle d'outils de maniere autonome -- la difference avec le Client SDK classique est que vous n'avez plus a implementer la boucle while/tool_use vous-meme.

Quand utiliser les Managed Agents

Les Managed Agents sont adaptes aux taches qui tournent pendant des minutes ou des heures, quand vous avez besoin d'une isolation sandbox complete, ou quand vous ne voulez pas gerer l'execution 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'entree principal est la fonction query(), qui cree un agent, execute la boucle d'outils et streame les resultats en temps reel. 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 immediatement 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 implementation manuelle n'est necessaire -- l'agent les execute de maniere autonome.

Hooks et guardrails : securiser l'agent

Les hooks permettent d'executer du code custom aux points cles du lifecycle de l'agent. Un hook PreToolUse peut bloquer un appel d'outil avant execution. Un hook PostToolUse peut valider le resultat. Un hook Stop peut empecher l'agent de s'arreter prematurement. 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 echanges. On capture l'ID de session au premier appel via l'evenement SystemMessage(subtype="init"), puis on le reutilise avec l'option resume. L'agent retrouve ainsi tout le contexte de la conversation precedente sans avoir a tout re-expliquer.

Managed Agents : l'API cloud pour les taches longues

L'API Managed Agents repose sur quatre concepts : un Agent (modele, system prompt, outils), un Environment (template de conteneur), une Session (instance en execution) et des Events (messages bidirectionnels). Quand vous envoyez un evenement utilisateur, Anthropic provisionne un conteneur, execute la boucle agent, lance les outils dans le sandbox, et streame les resultats en temps reel.

Creer un agent et lancer une session

Le workflow de creation suit trois etapes : creer un agent, creer un environnement, puis lancer une session. Le toolset agent_toolset_20260401 active l'ensemble complet d'outils pre-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 evenements

La communication est entierement basee sur les evenements Server-Sent Events (SSE). Vous ouvrez un stream, envoyez un message utilisateur, puis traitez les evenements au fil de l'eau. L'agent emet des evenements agent.message pour le texte, agent.tool_use pour les appels d'outils, et session.status_idle quand il a termine.

Patterns d'orchestration multi-agent

Les deux approches supportent l'orchestration multi-agent, mais avec des mecanismes differents.

Pattern Orchestrator avec l'Agent SDK

Dans l'Agent SDK, vous definissez des subagents specialises que l'agent principal peut invoquer. Chaque subagent a son propre system prompt, ses outils et sa specialisation. L'agent orchestrateur delegue les sous-taches et agrege les resultats. Les messages des subagents incluent un champ parent_tool_use_id pour tracer l'origine de chaque reponse.

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 isoles. Un agent coordinateur delegue a d'autres agents qui tournent chacun dans leur propre thread avec un contexte separe. Tous les agents partagent le meme conteneur et filesystem, mais leurs outils et contextes ne sont pas partages. Un point important : un seul niveau de delegation est autorise -- les agents delegues ne peuvent pas deleguer a leur tour.

Pattern Handoff : transfert de responsabilite

Le pattern handoff consiste a transferer completement le controle d'un agent a un autre. Cas d'usage typique : un agent de triage recoit les demandes, classifie le type de travail, puis transfère au specialiste adequat (code review, generation de tests, recherche). Le thread persiste, ce qui permet au coordinateur d'envoyer un suivi a un agent appele precedemment.

Pattern Guardrails : validation en boucle

Le pattern guardrails combine hooks (Agent SDK) ou outcomes (Managed Agents) pour valider le travail de l'agent a chaque etape. Avec les Managed Agents, le mecanisme d'Outcomes est particulierement puissant : vous definissez un rubric detaille, et un grader independant evalue l'artefact produit. Si le resultat ne satisfait pas les criteres, l'agent itere automatiquement (jusqu'a 20 iterations maximum).

Cas d'usage reels en production

Les agents IA avec Claude ne sont pas un exercice theorique. Voici des scenarios concrets ou chaque approche excelle.

Deployer un agent en production : guide etape par etape

Evolution des agents IA chez Anthropic

L'ecosysteme agent d'Anthropic a evolue rapidement. Voici les jalons cles qui ont mene a l'offre actuelle.

Fonctionnalites avancees : Memory et Outcomes

Memory Stores : persistance cross-session

Par defaut, les sessions Managed Agents sont ephemeres. Les Memory Stores resolvent ce probleme en permettant a l'agent de conserver des apprentissages entre sessions : preferences utilisateur, conventions de projet, erreurs passees. Chaque memory store peut contenir plusieurs documents texte, chacun plafonne a 100 Ko. Jusqu'a 8 memory stores peuvent etre attaches a une session.

Quand un memory store est attache, l'agent obtient automatiquement les outils memory_list, memory_search, memory_read, memory_write et memory_edit. Le systeme inclut des ecritures securisees 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 definissez le resultat attendu via un rubric detaille avec des criteres explicites et evaluables. Le harness provisionne automatiquement un grader qui evalue l'artefact dans une fenetre de contexte separee pour eviter les biais. Si le resultat ne satisfait pas les criteres (needs_revision), l'agent itere automatiquement. Les livrables sont ecrits dans /mnt/session/outputs/ et recuperables via la Files API.

Environnements : sandboxing et isolation

La securite d'un agent en production depend directement de son isolation. Les environnements Managed Agents offrent un sandboxing complet avec des conteneurs cloud configures a la demande.

Vous pouvez pre-installer des packages via six gestionnaires (apt, cargo, gem, go, npm, pip), configurer le reseau en mode unrestricted (defaut) ou limited avec une liste blanche de domaines. En production, utilisez toujours le mode limited avec des allowed_hosts explicites. Les packages sont caches entre sessions partageant le meme environnement, ce qui accelere les demarrages.

Conclusion : choisir sa strategie agent

L'ecosysteme agent d'Anthropic offre deux voies complementaires. L'Agent SDK convient aux equipes qui veulent un controle total sur l'execution et l'integration dans des pipelines existants. L'API Managed Agents convient aux equipes qui preferent deleguer l'infrastructure et se concentrer sur la logique metier. Les deux partagent le meme moteur Claude, les memes outils, et le meme standard MCP pour l'extensibilite.

Le choix n'est d'ailleurs pas exclusif : beaucoup d'architectures combinent les deux. L'Agent SDK pour les taches 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'elargir progressivement la surface d'action de l'agent.