Claude Agent SDK : Fonctionnalités et évaluation

Claude Agent SDK est une interface de développement permettant de créer des applications avec lesquelles Claude exécute des flux de travail délimités utilisant des outils. Le SDK peut gérer les sessions, invoquer des outils et coordonner le travail, mais il ne dispense pas des permissions d’application, du contrôle de version, de l’évaluation ni de l’approbation humaine. Il convient de l’utiliser comme composant d’exécution d’agent, et non comme système de production complet.

Pour les équipes qui doivent finaliser un travail basé sur les sources sans posséder d'environnement d'exécution d'agent, Ottermind propose une solution d'espace de travail géré : elle permet de centraliser les fichiers, le contexte de recherche, les décisions et les livrables pendant qu'une personne examine le résultat. Le SDK et l'espace de travail géré répondent à des problématiques opérationnelles différentes.

Recherche et divulgation: Ce guide est basé sur les documents Dépôt Claude Agent SDK, Documentation d'utilisation de l'outil Anthropic et Documentation AWS AgentCore Claude Agent SDK, révisés le 3 septembre 2026. Les API et les limites évoluent ; veuillez vérifier la version actuelle avant toute implémentation.

Les éléments constitutifs de base

Élément constitutif	Responsabilité	Contrôle de l'application
Session	Gère l'état d'exécution et de conversation.	Expiration, isolation et enregistrement d'audit
Modèle	Interprétation du contexte et proposition d'étapes	Version du modèle, budget et contrat de sortie
Outil	Exécution d'une opération délimitée	Schéma, délai d'expiration, autorisation et idempotence
Sous-agent	Gestion d'un rôle véritablement distinct	Périmètre, budget et règles d'escalade
Mode d'autorisation	Contrôle les éléments auxquels l'agent peut accéder ou qu'il peut modifier.	Liste blanche et confirmation humaine.
Résultat.	Renvoie du texte, des données structurées ou des artefacts.	Validation et transmission au réviseur.

Commencer par une tâche réversible.

Prototyper un flux de travail à forte composante lecture, par exemple la transformation de fichiers de référentiel approuvés en une note de modification. Capturer les données d'entrée, l'invite, la version du modèle, les appels d'outils, la sortie, les corrections du réviseur et la décision finale. N'ajouter l'accès en écriture qu'une fois la trace compréhensible et les erreurs récupérables.

Contrat de tâches minimales

Prompt

Objectif : produire un document de synthèse d’implémentation basé sur le code source.
Sources autorisées : uniquement les fichiers du dépôt joint.
Outils autorisés : lister et lire les fichiers ; aucune écriture ni requête réseau.
Résultats : conclusions, modifications proposées, preuves, risques et questions ouvertes.
Arrêter en cas de source requise manquante ou d’autorisations ambiguës.

Sessions et sous-agents

Utilisez une session lorsque le flux de travail nécessite une continuité entre plusieurs étapes. Utilisez un sous-agent uniquement lorsque le rôle, les outils ou les critères d’évaluation diffèrent réellement. L’utilisation de plusieurs agents augmente la coordination, la latence et les risques de défaillance. Transmettez le contexte minimal requis par chaque rôle et renvoyez des résultats structurés avec statut et preuves.

Une architecture pratique

Conservez le SDK derrière un périmètre applicatif avec cinq responsabilités :

Gestionnaire de requêtes : authentifie l’utilisateur, sélectionne le projet autorisé et définit un budget.
Chargeur de contexte : récupère uniquement les fichiers autorisés et enregistre leurs identifiants et dates.
Exécuteur d’agents : démarre la session, fournit les outils et enregistre chaque requête et résultat.
Couche de politique : valide les arguments, bloque les actions non autorisées et demande une confirmation.
Adaptateur de résultat : valide la forme renvoyée et transmet un brouillon au réviseur ou au système suivant.

Cette séparation est importante car le SDK peut aider le modèle à demander un outil, mais c’est votre application qui décide si cette demande est autorisée. N’intégrez pas la logique d’autorisation dans une invite et ne présumez pas qu’un modèle préservera automatiquement les limites des locataires.

Sessions, reprise et échec

Attribuez à chaque exécution un identifiant explicite et un état final, par exemple completed, needs_review, blocked ou failed. Conservez la version du modèle et du SDK, la révision de l’invite, les sources d’entrée, les appels d’outils et la décision du réviseur. En cas d’erreur réseau après une écriture, utilisez une clé d’idempotence et interrogez le système de référence avant de réessayer. Si une session reprend après une modification humaine, incluez le fichier modifié et la raison de la modification plutôt que de rejouer une conversation obscure.

Exemples de conception d'outils

Privilégiez une fonction comme create_draft_task(title, owner, due_date) à un outil shell généraliste. Cette fonction spécialisée permet d'imposer des formats de date, des propriétaires autorisés, la portée du projet et un statut brouillon uniquement. Un outil de recherche de fichiers doit renvoyer les identifiants et des extraits, et non exposer silencieusement l'intégralité d'un disque. Un navigateur doit utiliser une liste blanche et s'arrêter avant l'authentification ou le paiement.

Coûts et latence

Définissez les budgets avant l'exécution : nombre maximal de itérations du modèle, d'appels d'outils, de jetons, de temps écoulé et de sous-agents. Optimisez l'extraction en utilisant un modèle plus petit lorsque la qualité le permet et réservez les raisonnements complexes aux étapes ambiguës. Enregistrez l'utilisation réelle avec le résultat afin qu'une démonstration réussie ne masque pas un flux de travail non rentable. Les tâches longues doivent être asynchrones, annulables et visibles pour l'utilisateur.

SDK ou espace de travail géré

Utilisez le SDK si votre équipe a besoin d'outils spécifiques à l'application, d'un contrôle du déploiement ou d'un environnement d'exécution personnalisé, et qu'elle peut gérer la sécurité, l'observabilité et la maintenance. Un espace de travail géré est un meilleur point de départ si l'objectif principal est de connecter les fichiers, les recherches, les décisions et les livrables pour validation humaine. Le choix repose sur la responsabilité opérationnelle, et non sur l'appellation qui semble la plus autonome.

Exemple : un agent de recherche et de briefing

Imaginez une équipe qui a besoin d'un résumé hebdomadaire de la concurrence. Le gestionnaire de requêtes vérifie l'identité de l'analyste et sélectionne le projet approuvé. Le chargeur de contexte récupère la liste des sources et enregistre la date de récupération. La session de l'agent ne peut appeler que search_approved_sources et draft_brief. La couche de stratégie rejette les requêtes concernant des URL arbitraires, des publications externes ou des fichiers hors du projet. L'adaptateur de résultats exige des sections pour les conclusions, les citations, les incertitudes et les questions ouvertes avant de présenter le brouillon à un relecteur.

L'artefact utile n'est pas seulement le texte final. C'est la trace : quelles sources étaient disponibles, quels outils ont été utilisés, ce qui a été bloqué, ce que le relecteur a modifié et si le résumé a été accepté. Cette trace facilite le débogage, l'analyse des coûts et la mise en place d'un ensemble d'évaluation reproductible lorsque le modèle ou le SDK est modifié.

Gestion des versions et mises à niveau

Épinglez les versions du SDK et du modèle dans chaque environnement. Consultez les notes de version pour connaître les modifications apportées aux modes d'autorisation, aux schémas d'outils, au comportement des sessions et aux modèles pris en charge. Effectuez des tests de régression avant la mise à niveau, notamment un test confirmant que les outils interdits le restent. Conservez une version de restauration et évitez de mettre à niveau en cours de production sans plan de migration.

Liste de vérification pour la préparation à la production

L'authentification et la vérification du locataire sont effectuées avant la récupération du contexte.
Chaque outil possède un schéma précis, un délai d'expiration et un contrôle d'autorisation.
Les sessions disposent d'un budget, d'une annulation, d'une expiration et d'un état final.
Les sorties sont validées avant d'être enregistrées dans le système.
Les actions sensibles nécessitent une approbation humaine explicite.
Les journaux contiennent suffisamment d'informations pour reproduire une panne sans stocker de données confidentielles.
Les cas d'évaluation couvrent la qualité, la sécurité, le coût et la latence.

Limites d'autorisation et de sécurité.

Validez les arguments des outils dans le code applicatif. Gérez les informations d'identification en dehors des invites, limitez l'accès au système de fichiers et au réseau, définissez des délais d'expiration et exigez une confirmation pour l'envoi, la suppression, l'achat ou la modification d'un accès. Consignez chaque appel d'outil important, en précisant l'identité de l'utilisateur et la décision d'approbation.

Évaluez le flux de travail, pas la démo.

Créez un ensemble de tests comprenant des cas normaux, incomplets, contradictoires, conflictuels et sensibles aux permissions. Mesurez la bonne exécution, l'escalade sécurisée, les erreurs d'outil, la latence, le coût et les corrections des réviseurs. Spécifiez les versions du modèle et du SDK pour chaque évaluation.

FAQ

Claude Agent SDK correspond-il à l'utilisation de l'outil API Claude ?

Non. L'utilisation d'outils constitue un modèle d'interaction. Le SDK fournit des composants applicatifs supplémentaires pour les sessions d'agents et les flux de travail, tandis que votre application conserve la gestion des politiques, du stockage, des autorisations et de l'évaluation.

Ai-je besoin de plusieurs agents ?

Généralement pas au début. Un agent unique, doté d'outils spécifiques et de points de contrôle explicites, est plus facile à tester et à exploiter.

Le SDK peut-il modifier des fichiers ou exécuter des commandes en toute sécurité ?

Il peut être connecté à ces outils, mais la sécurité repose sur votre environnement de test (sandbox), vos listes blanches, vos processus de validation, d'examen et de restauration. Ne considérez jamais une commande générée comme pré-approuvée.

Pour une description plus détaillée du périmètre système, consultez Architecture des agents IA et Sécurité des agents IA.