Antoine Laurent

Posted on May 19 • Originally published at apidog.com

Claude Agents Managés vs Agent SDK (2026) : Lequel Choisir

Vous déployez un agent IA de production sur Claude. Le premier choix d’architecture est simple à formuler, mais coûteux à corriger plus tard : laisser Anthropic héberger la boucle d’agent et le bac à sable avec les Claude Managed Agents, ou exécuter cette boucle dans votre propre service avec le SDK Claude Agent. Les deux peuvent produire une démo similaire ; en production, ils changent votre résidence des données, votre modèle de coût, votre observabilité et votre astreinte.

Essayez Apidog aujourd’hui

En bref

Choisissez Claude Managed Agents si vous voulez qu’Anthropic héberge la boucle d’agent, le bac à sable et l’état de session pour des tâches longues ou asynchrones.

Choisissez SDK Claude Agent si vous voulez exécuter la boucle dans votre propre processus, garder le contrôle des outils, des permissions, de la résidence des données et de l’infrastructure.

Dans les deux cas, votre agent dépendra surtout des API et serveurs MCP qu’il appelle. Testez-les avant la mise en production.

Introduction

Construire un agent IA en production ne consiste plus à mettre une boucle while autour d’une complétion de chat. Avec Claude, vous avez aujourd’hui deux modèles d’exécution :

Claude Managed Agents : Anthropic exécute la boucle d’agent, le bac à sable et l’état de session via une API REST.
SDK Claude Agent : vous importez une bibliothèque Python ou TypeScript, et la boucle s’exécute dans votre propre service.

Même modèle Claude, mais contrat opérationnel différent.

Un agent de production appelle presque toujours des API : rembourser un paiement, créer un ticket Zendesk, lire un inventaire, interroger une API interne, déclencher une tâche ETL. Sa fiabilité dépend donc directement de la fiabilité de ces dépendances.

Avant de choisir le modèle d’hébergement, préparez un environnement de test pour ces API. Avec Apidog, vous pouvez :

mocker les services appelés par l’agent ;
définir les schémas attendus ;
exécuter des tests de contrat ;
tester un serveur MCP comme l’agent le fera.

Pour un focus sur la partie hébergée, consultez aussi le guide sur les Claude Managed Agents.

Ce que sont réellement les Claude Managed Agents

Les Claude Managed Agents sont un harnais d’agent hébergé par Anthropic. Vous ne codez pas la boucle d’agent, le stockage de session ou le bac à sable : vous décrivez l’agent, puis vous envoyez des événements.

La fonctionnalité a été lancée en bêta publique en avril 2026 et nécessite actuellement l’en-tête bêta suivant sur chaque requête :

anthropic-beta: managed-agents-2026-04-01

Le SDK peut configurer cet en-tête pour vous.

Les 4 concepts principaux

Concept	Rôle
Agent	Modèle, invite système, outils, serveurs MCP et compétences. Vous le créez une fois et le référencez par ID.
Environnement	Modèle de conteneur avec packages préinstallés et règles réseau.
Session	Instance d’agent en cours d’exécution, avec système de fichiers persistant et historique de conversation.
Événements	Messages entre votre application et l’agent : tours utilisateur, résultats d’outils, statuts, réponses streamées.

Flux d’exécution

Le flux typique ressemble à ceci :

Créer un agent.
Configurer un environnement.
Démarrer une session.
Envoyer des messages utilisateur sous forme d’événements.
Streamer les réponses.
Récupérer l’historique d’événements pour audit ou débogage.

Les Managed Agents fournissent des outils intégrés comme :

Bash ;
lecture, écriture et édition de fichiers ;
glob et grep ;
recherche et récupération web ;
connexions à des serveurs MCP.

Ils sont adaptés aux charges de travail longues ou asynchrones : tâches qui durent plusieurs minutes ou heures, nombreux appels d’outils, besoin d’un état persistant et volonté de réduire l’infrastructure opérée côté application.

Point important : les outils personnalisés

Avec les Managed Agents, Claude peut décider d’appeler un outil personnalisé, mais votre application exécute réellement cet outil et renvoie le résultat via le flux d’événements.

Autrement dit :

la boucle d’agent est hébergée ;
le bac à sable est hébergé ;
mais l’exécution de vos outils métier reste dans votre environnement.

Certaines fonctionnalités comme les résultats et le multi-agent sont limitées en aperçu de recherche et nécessitent une demande d’accès distincte. Ne partez pas du principe que tout est disponible par défaut.

Pour replacer ces composants dans un modèle plus large, voir l’article sur l’architecture IA agentique.

Ce qu’est réellement le SDK Claude Agent

Le SDK Claude Agent est une bibliothèque Python ou TypeScript. Il expose la boucle d’agent, les outils intégrés et la gestion du contexte utilisés par Claude Code.

Il s’appelait auparavant SDK Claude Code. Le changement de nom reflète une portée plus large que les seuls cas de génération ou modification de code.

Installation :

pip install claude-agent-sdk

ou :

npm install @anthropic-ai/claude-agent-sdk

Avec le SDK, la boucle s’exécute dans votre propre processus. Vous contrôlez donc :

l’environnement d’exécution ;
les permissions ;
les hooks ;
les logs ;
les outils ;
l’état de session ;
la proximité avec vos bases de données ou services internes.

Exemple mental : pourquoi ce n’est pas juste un Client SDK

Avec un simple Client SDK, vous implémentez vous-même une boucle du type :

while response.stop_reason == "tool_use":
    tool_call = response.content
    result = execute_tool(tool_call)
    response = client.messages.create(...)

Avec le SDK Claude Agent, cette boucle est fournie. Vous configurez les outils, les permissions et les callbacks, puis vous consommez les messages streamés.

Ce que fournit le SDK

Fonction	Utilité
Outils intégrés	Lecture, écriture, édition, Bash, Glob, Grep, WebSearch, WebFetch, Monitor, AskUserQuestion.
Hooks	Points de contrôle comme `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`.
Sous-agents	Agents spécialisés pour des sous-tâches, traçables via `parent_tool_use_id`.
MCP	Connexion à des bases de données, navigateurs et API via Model Context Protocol.
Permissions	Autoriser, bloquer ou demander validation selon l’outil ou l’action.
Sessions	Capturer un ID de session, reprendre plus tard, forker une session, stocker l’état en JSONL.

Exemple de politique utile : avant un remboursement, intercepter l’appel d’outil avec PreToolUse, vérifier le montant, puis exiger une approbation humaine au-delà d’un seuil.

Le SDK lit aussi la configuration de l’écosystème Claude Code :

compétences dans .claude/skills/ ;
commandes slash ;
fichier CLAUDE.md ;
plugins.

Côté authentification, il prend en charge l’API Anthropic directe, Amazon Bedrock, Claude Platform sur AWS, Google Vertex AI et Azure AI Foundry.

Pour démarrer avec une boucle fonctionnelle, voir le guide de configuration du SDK Claude Agent avec un plan Claude et la procédure pas à pas pour créer votre propre Claude Code.

Facturation à surveiller

À partir du 15 juin 2026, l’utilisation du SDK Agent et de claude -p sur les plans d’abonnement sera déduite d’un crédit mensuel distinct pour le SDK Agent, séparé des limites d’utilisation interactive.

Ne basez pas votre budget sur une hypothèse ancienne. Vérifiez toujours les conditions actuelles directement chez Anthropic.

Comparatif : Managed Agents vs SDK Agent

Considérez la ligne de coût comme indicative. Confirmez les chiffres actuels sur la page de tarification d’Anthropic et dans la documentation des Managed Agents.

Dimension	Claude Managed Agents	SDK Claude Agent
Où s’exécute la boucle	Infrastructure gérée par Anthropic	Votre processus, votre infrastructure
Interface	API REST + flux d’événements SSE	Bibliothèque Python ou TypeScript
Contrôle de la boucle	Configuré, non codé ; pilotage via événements	Complet : hooks, permissions, logique in-process
Modèle de coût	Tokens Claude + frais d’exécution par heure de session active	Tokens Claude + calcul et infrastructure que vous opérez
Charge opérationnelle	Faible : pas de bac à sable ni stockage de session à maintenir	Plus élevée : service, scaling, sandboxing et monitoring à gérer
Observabilité	Journal d’événements hébergé et récupérable	Hooks, logs et tracing que vous instrumentez
Latence	Saut réseau vers l’exécution hébergée ; adapté aux tâches longues	Boucle in-process ; proximité contrôlée avec vos données et outils
Résidence des données	Bac à sable et état de session dans l’infrastructure Anthropic ou AWS selon option	Fichiers, état et exécution d’outils dans votre infrastructure
Outils personnalisés	Claude demande ; votre application exécute et renvoie le résultat	Fonctions Python ou TypeScript in-process
Meilleure adéquation	Agents longs, asynchrones, avec faible charge infra côté équipe	Agents proches de vos fichiers, services internes et contraintes de données

Comment décider

1. Regardez d’abord la résidence des données

Si l’état de session, les fichiers temporaires ou les logs ne peuvent pas sortir de votre infrastructure, choisissez le SDK.

Avec le SDK :

les outils s’exécutent chez vous ;
l’état de session reste chez vous ;
les hooks peuvent alimenter votre audit interne ;
seule l’inférence part vers Claude selon votre configuration.

Avec les Managed Agents, le bac à sable et le journal d’événements résident dans l’environnement d’Anthropic ou dans l’option AWS disponible, avec ses limites spécifiques.

2. Évaluez la charge opérationnelle

Les Managed Agents retirent de votre backlog :

le stockage de session ;
le sandboxing ;
le scaling de workers ;
une partie de l’observabilité ;
la gestion de tâches longues.

Le SDK vous rend responsable de ces éléments, mais vous donne plus de contrôle.

C’est souvent le vrai arbitrage : moins d’infrastructure à opérer contre plus de contrôle sur l’exécution.

3. Ne comparez pas seulement les prix affichés

Les Managed Agents ajoutent des frais d’exécution par heure de session active.

Le SDK n’a pas ces frais horaires côté Anthropic, mais vous payez :

les machines ;
l’autoscaling ;
le monitoring ;
le sandboxing ;
les ingénieurs ;
l’astreinte.

Une option moins chère sur la facture API peut coûter plus cher en exploitation.

4. Décidez comment vous allez observer l’agent

Avec les Managed Agents, vous récupérez un journal d’événements hébergé.

Avec le SDK, vous devez instrumenter explicitement :

PreToolUse pour tracer les intentions ;
PostToolUse pour tracer les résultats ;
Stop pour analyser les fins de session ;
SessionStart et SessionEnd pour corréler les runs.

Exemple de structure de log utile :

{
  "session_id": "sess_123",
  "tool": "refund_payment",
  "phase": "PreToolUse",
  "amount": 129.99,
  "currency": "EUR",
  "requires_human_approval": true,
  "ticket_id": "SUP-4512"
}

Test et débogage des API appelées par vos agents

Quel que soit le modèle choisi, votre agent sera aussi fiable que les API et serveurs MCP qu’il appelle.

Un agent de remboursement peut parfaitement raisonner, mais s’il appelle deux fois une API de paiement après un timeout ambigu, vous avez un incident.

Testez donc les dépendances avant de connecter l’agent à un client réel.

Couche 1 : contrats d’API

Chaque outil appelé par l’agent est une API avec :

une requête attendue ;
une réponse attendue ;
des erreurs possibles ;
des timeouts ;
des comportements de retry.

Avec Apidog, vous pouvez mocker un service de paiement ou de tickets, définir le schéma attendu, puis exécuter des tests de contrat régulièrement.

Exemple de contrat minimal pour un outil de remboursement :

{
  "transaction_id": "txn_123",
  "amount": 49.99,
  "currency": "EUR",
  "reason": "duplicate_charge",
  "idempotency_key": "refund_SUP-4512_txn_123"
}

Points à tester :

champs obligatoires ;
devise ;
montant maximum ;
clé d’idempotence ;
erreurs 4xx ;
erreurs 5xx ;
timeout après exécution réussie côté serveur.

Pour une approche structurée, voir le guide sur comment tester les agents IA qui appellent des API.

Couche 2 : serveurs MCP

Les Managed Agents et le SDK peuvent utiliser MCP. Un serveur MCP expose des outils, des entrées et des sorties. C’est donc aussi une surface de test.

Défaillances fréquentes :

payload de sortie modifié ;
timeout non géré ;
erreur renvoyée en texte libre au lieu d’un format structuré ;
outil renommé ;
argument facultatif devenu obligatoire ;
pagination oubliée.

Testez chaque outil MCP isolément avant de le connecter à un agent.

Le guide sur le test de serveur MCP avec Apidog explique comment énumérer les outils exposés et les exercer un par un.

Apidog inclut aussi un agent IA et un débogueur A2A pour observer le trafic généré par un agent au lieu de le deviner.

Couche 3 : comportement réel de requête de l’agent

Les agents n’appellent pas les API comme les humains.

Ils peuvent produire :

des rafales de retries ;
des lectures partielles ;
plusieurs appels identiques pendant le raisonnement ;
des boucles sur un même endpoint ;
des séquences inattendues après une erreur.

Rejouez du trafic réaliste contre vos mocks et inspectez les requêtes réellement envoyées.

Objectif : découvrir les comportements dangereux en staging, pas pendant l’incident.

Dans tous les cas, téléchargez Apidog et testez les dépendances de l’agent avant qu’il n’approche un client réel.

Cadre de décision

Répondez aux questions dans l’ordre. Le premier « oui » fort oriente généralement le choix.

Choisissez Claude Managed Agents si :

votre agent s’exécute longtemps ou de manière asynchrone ;
vous ne voulez pas gérer workers, sandboxing et stockage de session ;
votre équipe est petite et l’exploitation est la contrainte principale ;
vous voulez un journal d’événements hébergé et récupérable ;
vos règles de conformité autorisent le bac à sable et l’état de session dans l’environnement Anthropic ou AWS ;
vous acceptez le statut bêta et les fonctionnalités limitées derrière demande d’accès.

Choisissez le SDK Claude Agent si :

l’agent doit s’exécuter dans votre VPC ;
il doit accéder à des bases de données ou services internes ;
l’état de session ne doit pas être détenu par un tiers ;
vous avez besoin de hooks d’audit et de permissions précises ;
vous voulez exécuter les outils personnalisés in-process ;
vous voulez utiliser Bedrock, Vertex ou Azure tout en gardant la boucle chez vous ;
vous prototypez localement sur votre système de fichiers.

Chemin fréquent

Un chemin raisonnable :

Prototyper localement avec le SDK Agent.
Tester les API et serveurs MCP avec des mocks.
Mesurer la durée des sessions et le nombre d’appels d’outils.
Décider si la production doit rester en SDK ou migrer vers Managed Agents.
Traiter la migration comme un vrai projet, pas comme un simple changement de configuration.

Si vous comparez aussi des modèles ou agents de codage, voir la comparaison Claude vs Codex pour 2026.

Cas d’utilisation concrets

Agent de remboursement de paiements

Une équipe support fintech veut traiter les remboursements de bout en bout :

Lire le ticket.
Rechercher la transaction.
Vérifier la politique de remboursement.
Appeler l’API de paiement.
Écrire un résumé dans le ticket.

Ici, l’agent manipule de l’argent. Il faut donc :

un contrat testé pour chaque API ;
une clé d’idempotence ;
une piste d’audit ;
une approbation humaine au-delà d’un seuil.

Le SDK est souvent le choix naturel :

exécution dans le VPC ;
proximité avec le service de paiement ;
état de session conservé en interne ;
hooks PreToolUse pour bloquer ou demander validation.

Exemple de règle :

def pre_tool_use(tool_name, args):
    if tool_name == "refund_payment" and args["amount"] > 100:
        return {
            "action": "require_approval",
            "reason": "Remboursement supérieur au seuil autorisé"
        }

    return {"action": "allow"}

Avant le lancement, l’équipe peut mocker les endpoints de paiement et de grand livre dans Apidog, écrire des tests de contrat, puis rejouer des tickets historiques contre les mocks.

Bug typique à détecter : après une erreur 504, l’agent réessaie un remboursement qui avait en réalité réussi côté prestataire. Sans idempotence et tests de retry, c’est un incident financier.

Agent de triage de tickets support asynchrone

Une entreprise SaaS reçoit des milliers de tickets par jour. Elle veut un agent qui :

Classe le ticket.
Extrait les logs associés.
Rédige une réponse.
Résout ou escalade.

Les tickets arrivent en continu, chaque tâche prend plusieurs minutes et les données sont peu sensibles.

Les Managed Agents conviennent bien :

tâche longue et asynchrone ;
équipe réduite ;
pas besoin de gérer une flotte de workers ;
journal d’événements hébergé par ticket.

Mais l’équipe doit quand même tester les dépendances :

API de logs ;
serveur MCP du système de tickets ;
schémas de réponses ;
timeouts ;
erreurs.

L’hébergement est géré. La qualité des API reste votre responsabilité.

Agent interne de gestion de données derrière le pare-feu

Une équipe plateforme veut un agent capable de répondre à :

« Relance les partitions ETL échouées hier. »

L’agent doit :

Interroger une API interne.
Identifier les partitions échouées.
Exécuter un script de remédiation.
Rapporter le statut.

Les API ne sont pas exposées publiquement et les données sont sensibles.

Le SDK s’impose généralement :

exécution dans le réseau interne ;
accès aux services privés ;
état de session conservé en interne ;
hooks pour journaliser chaque commande ;
intégration avec l’audit existant.

Ici, « s’exécute dans votre processus » n’est pas une préférence. C’est une exigence.

Pour comprendre pourquoi les agents deviennent des consommateurs d’API majeurs, lire l’article sur les agents IA comme nouveaux consommateurs d’API.

Checklist de mise en production

Avant de connecter un agent à des systèmes réels :

[ ] Lister tous les outils appelés par l’agent.
[ ] Identifier les API derrière chaque outil.
[ ] Définir les schémas de requête et réponse.
[ ] Mocker les dépendances critiques.
[ ] Tester les erreurs 4xx, 5xx et timeouts.
[ ] Tester les retries et l’idempotence.
[ ] Ajouter des hooks ou journaux d’audit.
[ ] Définir les seuils nécessitant validation humaine.
[ ] Tester les serveurs MCP isolément.
[ ] Rejouer du trafic réaliste.
[ ] Vérifier résidence des données et contraintes de conformité.
[ ] Confirmer les prix et le statut bêta à la source.

Conclusion

Le choix entre Managed Agents et SDK Agent est surtout une décision d’exploitation et de gouvernance des données.

À retenir :

Managed Agents héberge la boucle et le bac à sable ; le SDK les exécute dans votre processus.
Le coût dépend de la forme de charge : frais d’exécution côté Managed Agents, infrastructure et astreinte côté SDK.
La résidence des données tranche souvent : VPC et données réglementées orientent vers le SDK.
Les petites équipes bénéficient du runtime géré si les contraintes de données le permettent.
Les dépendances doivent être testées dans les deux cas : API, serveurs MCP, retries, timeouts et contrats.
Prototyper avec le SDK puis migrer vers Managed Agents est possible, mais la migration doit être planifiée.
Vérifiez les prix et le statut bêta chez Anthropic avant de vous engager.

Étape suivante : avant de brancher un agent sur une API client ou interne critique, testez ses dépendances. Téléchargez Apidog pour mocker les endpoints, exécuter des tests de contrat et déboguer le trafic réel de l’agent.

FAQ

Quelle est la principale différence entre Claude Managed Agents et le SDK Claude Agent ?

Les Managed Agents sont une API REST hébergée où Anthropic exécute la boucle d’agent et un bac à sable par session. Vous envoyez des événements et recevez des résultats en streaming.

Le SDK Agent est une bibliothèque Python ou TypeScript qui exécute la boucle dans votre propre processus et infrastructure.

Même modèle Claude, propriété opérationnelle différente.

Le SDK Claude Agent est-il le même que l’ancien SDK Claude Code ?

Oui. Le SDK Claude Code a été renommé SDK Claude Agent pour refléter une portée plus large que les tâches de codage. Il expose la boucle d’agent, les outils intégrés et la gestion du contexte utilisés par Claude Code.

Quelle option est la moins chère ?

Cela dépend de la charge de travail.

Les Managed Agents facturent les tokens Claude plus des frais d’exécution pour le temps de session actif.

Le SDK n’ajoute pas ces frais horaires côté Anthropic, mais vous payez et opérez l’infrastructure.

Confirmez les tarifs actuels sur la page de tarification d’Anthropic avant de budgéter.

Puis-je utiliser des serveurs MCP avec les deux options ?

Oui. Les deux peuvent utiliser le Model Context Protocol.

C’est pourquoi il faut tester vos serveurs MCP avant de les connecter à l’agent. Le guide sur le test de serveur MCP avec Apidog montre comment exercer chaque outil exposé.

Comment empêcher les données client de quitter mon infrastructure ?

Utilisez le SDK Agent et exécutez la boucle dans votre propre environnement.

Avec le SDK :

l’exécution des outils reste chez vous ;
l’état de session reste chez vous ;
les fichiers restent chez vous.

Avec les Managed Agents, le bac à sable et le journal d’événements résident dans l’environnement Anthropic ou AWS selon l’option disponible.

Les Claude Managed Agents sont-ils prêts pour la production ?

Ils ont été lancés en bêta publique en avril 2026 et nécessitent l’en-tête bêta :

anthropic-beta: managed-agents-2026-04-01

Certaines fonctionnalités comme les résultats et le multi-agent sont limitées derrière une demande d’aperçu de recherche. Traitez-les comme une bêta et vérifiez la documentation actuelle.

Comment tester un agent avant qu’il n’interagisse avec de vraies API ?

Procédez en trois étapes :

Mockez chaque API et serveur MCP.
Écrivez des tests de contrat sur les requêtes et réponses.
Rejouez un trafic réaliste pour voir ce que l’agent envoie réellement.

Apidog couvre ces cas, avec un agent IA et un débogueur A2A pour inspecter le trafic. Le guide sur comment tester les agents IA qui appellent des API détaille les modes de défaillance.

Puis-je commencer avec une option et passer à l’autre plus tard ?

Oui, mais ce n’est pas un simple changement de configuration.

Les interfaces diffèrent :

SDK : bibliothèque Python ou TypeScript ;
Managed Agents : REST + événements SSE.

L’exécution des outils personnalisés et la gestion de session diffèrent aussi. Planifiez la migration comme un vrai projet.