Le SDK Claude Agent en pratique : construire des agents qui fonctionnent vraiment

En novembre dernier, j'ai confié à un client un agent alimenté par Claude censé trier les tickets d'assistance entrants, les router vers le bon département et rédiger des premières réponses. Trois semaines pour le construire. Brillant en staging. Premier jour en production, il a halluciné une politique de remboursement qui n'existe pas, routé dix-sept tickets vers la mauvaise queue, et assuré avec aplomb à un client que sa commande arriverait « jeudi » sans aucun accès aux données d'expédition.

Voilà. J'ai appris certaines choses.

Cet article parle de ce que je sais maintenant, après avoir reconstruit cet agent correctement et en avoir livré plusieurs autres depuis. Pas de la théorie. Les vraies décisions que j'ai prises, les outils que j'ai utilisés, et les erreurs que je ne répéterai pas. Si vous êtes propriétaire d'une agence ou freelance essayant de dépasser le stade de la démo avec le SDK Claude Agent, ce texte est écrit pour vous.

---

Ce que le SDK Claude Agent est réellement (et ce qu'il n'est pas)

Avant toute chose : le SDK n'est pas magique. C'est une façon structurée de donner à Claude accès à des outils, gérer le contexte de la conversation sur plusieurs tours, et orchestrer ce qui revient à une boucle de décision. Claude raisonne sur une tâche, décide d'appeler un outil ou non, reçoit un résultat, raisonne à nouveau, puis appelle un autre outil ou produit une réponse finale.

Cette boucle semble simple. Elle est simple. La complexité réside entièrement dans ce que vous mettez autour.

Le SDK vous fournit la plomberie. Vous êtes toujours responsable de la pression d'eau, du diamètre des tuyaux, et du fait que vous vous êtes souvenu d'arrêter l'alimentation avant de commencer à percer. J'ai vu des propriétaires d'agences confier le SDK à un développeur junior, s'attendre à un produit fini en un sprint, et récupérer quelque chose qui fonctionne techniquement mais s'effondre sur n'importe quelle entrée en dehors du chemin heureux.

À quoi ressemble la boucle en pratique

Vous définissez les outils sous forme de schémas JSON. Claude lit ces schémas, décide quand les utiliser, passe des arguments structurés, et votre code exécute la logique réelle. Claude n'exécute jamais directement du code. Il demande. Votre système fait le travail. Ensuite Claude reçoit le résultat et continue.

Cette séparation est plus importante que la plupart des gens ne le réalisent. Cela signifie que Claude est toujours un orchestrateur, jamais un exécutant. Et cette conception doit influencer chacune de vos décisions architecturales.

---

Concevoir des outils que Claude peut réellement utiliser

C'est là que la plupart des builds échouent. J'ai examiné peut-être quinze bases de code d'agents d'autres développeurs au cours de l'année passée, et le problème le plus courant n'est pas l'ingénierie des invites ou le choix du modèle. C'est les outils mal conçus.

Voici ce que « mal conçu » signifie en pratique :

• Un outil appelé process_data qui fait cinq choses sans rapport selon les paramètres que vous passez
• Des descriptions d'outils qui ressemblent à des commentaires de code interne (« appelle l'endpoint v2 avec les en-têtes d'authentification »)
• Des paramètres nommés type ou mode qui acceptent des chaînes arbitraires au lieu d'énumérations
• Aucune information d'erreur dans la valeur renvoyée, donc Claude n'a aucune idée si l'appel a réussi

Au début de 2023, Seahawk avait un projet de pipeline de contenu où nous avions construit un outil manage_content qui acceptait un paramètre action : create, update, delete, publish, unpublish, archive. Claude choisissait constamment la mauvaise action parce que les distinctions n'étaient pas évidentes à partir du schéma seul. Nous l'avons divisé en six outils distincts. La précision sur cette décision spécifique est passée d'environ 60 % à 94 % dans nos évaluations internes. Un changement.

Les règles que je suis maintenant

1. Un outil, une fonction. Si vous ne pouvez pas décrire l'objectif de l'outil en une phrase sans « et », divisez-le.
2. Utilisez des énumérations autant que possible. Ne laissez pas Claude deviner des chaînes de caractères.
3. Écrivez la description pour Claude, pas pour un développeur humain. Claude ne connaît pas votre base de code. Il sait ce que vous lui dites.
4. Toujours retourner des données structurées avec un champ succès/échec explicite. Ne faites jamais inférer Claude par le silence.
5. Gardez les noms d'outils commençant par un verbe. search_orders, create_draft, fetch_customer_record. Pas orders, draft, customer.

La documentation Anthropic sur tool use approfondit la structure du schéma et vaut la peine d'être lue attentivement, pas en diagonale.

---

La gestion du contexte est le coût caché

Voici quelque chose dont personne ne parle assez. Les tokens ne sont pas gratuits, et les agents sont gourmands.

Chaque tour de boucle inclut l'historique de conversation complet, tous les schémas d'outils, le système prompt, et les résultats des outils. Un agent modérément complexe avec dix outils et un système prompt détaillé pourrait commencer chaque session utilisateur à 3 000-4 000 tokens avant que l'utilisateur n'ait tapé un seul caractère. Ajoutez cinq ou six appels d'outils avec résultats, et vous regardez 15 000-20 000 tokens par tâche résolue. Aux prix actuels de l'API Claude, ça s'accumule rapidement à n'importe quel volume.

Je suis cela de manière obsessionnelle maintenant. Pour chaque agent que je déploie, j'exécute un calcul de coût par résolution lors de l'assurance qualité. Si c'est au-dessus d'un seuil que j'ai accepté avec le client à l'avance, je reviens et je serre le système prompt, je réduis les schémas d'outils, ou je regarde si je peux mettre en cache le contexte statique en utilisant prompt caching, qu'Anthropic a ajouté et que j'utilise genuinely sur chaque projet maintenant. Les tokens éligibles au cache coûtent environ 10 % du taux d'entrée standard lors d'un succès de cache. Sur un agent occupé qui relance le même système prompt des milliers de fois par jour, ce n'est pas une erreur d'arrondi.

Réduire sans casser les choses

La tentation est d'écrire un système prompt riche et détaillé couvrant tous les cas limites. Résistez. Chaque ligne que vous ajoutez coûte des tokens à chaque tour. Écrivez pour le cas courant. Gérez les cas limites dans les valeurs retournées par les outils ou dans des instructions in-context plus courtes injectées au bon moment.

Je coupe aussi sans pitié les descriptions d'outils une fois qu'un agent fonctionne. Si une description dit « Cet outil recherche la base de données de commandes et retourne une liste de commandes correspondant à la requête, y compris l'ID de commande, le nom du client, les articles de ligne, l'état de l'expédition, et les horodatages », je la réduirai à « Rechercher les commandes par chaîne de requête. Retourne les enregistrements de commande correspondants. » Claude est assez intelligent. Il n'a pas besoin de la liste des champs dans la description de l'outil si le schéma de retour documente correctement ces champs.

---

Orchestration multi-agents : quand un agent ne suffit pas

Les systèmes mono-agent se cassent à un certain plafond de complexité. J'ai atteint ce plafond sur un projet pour une société de gestion immobilière au printemps dernier. L'agent devait gérer les demandes de maintenance, communiquer avec les entrepreneurs, mettre à jour une base de données Notion, envoyer des emails templé via SendGrid, et extraire les données de disponibilité d'une API de calendrier personnalisée. Sept outils, dont plusieurs avaient des sous-workflows.

Un agent essayant de coordonner tout cela est devenu peu fiable. Le contexte est devenu désordonné. Claude perdait occasionnellement la trace de quel sous-tâche il travaillait au milieu de la boucle.

La solution était évidente rétrospectivement : orchestrateur plus spécialistes. Un agent Claude de haut niveau gère la classification d'intention et le routage. Les agents sous-spécialistes gèrent des domaines spécifiques (communication, planification, mises à jour de données) et rapportent des résultats structurés. L'orchestrateur ne voit jamais les internals de ce que chaque spécialiste a fait. Il voit juste le résultat.

Ce modèle est décrit dans les propres conseils multi-agents d'Anthropic et il correspond de près à la façon dont vous concevriez une équipe humaine. Un chef de projet n'écrit pas personnellement chaque email et ne met pas à jour chaque feuille de calcul. Il délègue, attend la confirmation, et passe à autre chose.

Notes pratiques sur la conception des sous-agents

• Donnez à chaque sous-agent un système prompt serré et spécifique. Aucune instruction inter-domaines.
• Les sous-agents ne doivent jamais avoir plus d'outils qu'ils n'en ont besoin pour leur domaine. La surcharge d'outils est tout aussi dangereuse chez les sous-agents que chez l'orchestrateur principal.
• Transmettez le contexte explicitement. Ne supposez pas qu'un sous-agent « sait » ce qui s'est passé en amont. Envoyez-lui exactement ce dont il a besoin, rien de plus.

---

Gérer les défaillances avec élégance (car elles se produiront)

Les agents en production échouent. Ils expirent. Les API externes renvoient des 500. Les utilisateurs envoient des entrées que vous n'aviez jamais anticipées. Claude lit occasionnellement mal un schéma d'outil et passe un argument malformé.

La question n'est pas de savoir si votre agent échouera. C'est de savoir s'il échoue en toute sécurité.

Je construis maintenant trois choses dans chaque agent, sans exception :

1. Une logique de réessai avec backoff sur tous les appels d'outils externes. Pas seulement sur les erreurs de limite de débit. Sur toute réponse autre que 200.
2. Un chemin de secours quand l'agent a effectué plus de N appels d'outils sans résoudre la tâche. N varie, mais je la laisse rarement dépasser huit. À ce stade, quelque chose ne va pas et un humain devrait intervenir.
3. Gestion explicite de l'incertitude dans le prompt système. Je dis à Claude : si vous n'avez pas assez d'informations pour agir avec confiance, posez une question de clarification plutôt que de procéder sur des hypothèses.

Ce troisième point a sauvé l'agent de triage des tickets dont j'ai parlé au début. La version reconstruite pose maintenant une question de clarification quand elle est incertaine quant à l'acheminement. Les utilisateurs ne s'en plaignent pas. Ils préfèrent répondre à une question plutôt que de voir leur ticket arriver dans la mauvaise file.

---

Evals : vous ne pouvez pas mettre en production sans elles

Je n'ai pas exécuté d'evals appropriées sur la première version de l'agent de support. C'était vraiment l'erreur. Tout le reste n'était qu'un symptôme.

Les evals n'ont pas besoin d'être sophistiquées. Ce que je fais maintenant, c'est construire un ensemble de 40 à 60 entrées représentatives avant de commencer à construire, couvrant les cas normaux, les cas limites et les entrées adversariales. Je lance l'agent contre toutes après chaque changement significatif. Je suis trois chiffres : le taux d'accomplissement des tâches, la précision des appels d'outils (a-t-il appelé le bon outil avec les bons arguments) et le taux d'hallucination (a-t-il affirmé quelque chose non fondé sur les résultats des outils).

Pour un agent en production, je n'accepte pas de mettre en production en dessous de 88% de taux d'accomplissement des tâches et zéro tolérance pour l'hallucination dans les résultats critiques comme les messages destinés aux clients avec des affirmations spécifiques (dates, prix, politiques).

Le cadre de benchmarking HELM de Stanford vaut le coup d'être examiné pour s'inspirer de la conception des evals, même si vous ne travaillez pas à l'échelle académique. Les catégories qu'ils testent correspondent bien aux exigences réelles de production.

---

Le prompt système est fondamental

J'ai changé d'avis là-dessus au cours de la dernière année. J'avais l'habitude de traiter le prompt système comme du texte de configuration, quelque chose que vous écrivez une fois et oubliez. Maintenant, je le traite comme le fichier le plus important du projet.

Un prompt système bien écrit fait quatre choses :

• Définit clairement l'identité et la portée de l'agent (ce qu'il fait et, de manière critique, ce qu'il ne fait explicitement pas)
• Établit les attentes en matière de ton et de format de sortie
• Gère les modes de défaillance les plus courants de manière proactive (« Si vous ne trouvez pas de commande, dites-le explicitement plutôt que de deviner »)
• Établit les critères d'escalade

La définition de portée est ce que la plupart des développeurs ignorent. Sans elle, Claude essaiera d'être utile de manière que vous n'aviez pas prévue. Sur l'agent de gestion immobilière, le premier prompt système n'excluait pas explicitement les conseils financiers. Un locataire a demandé à l'agent s'il devrait contester une charge. Claude a aimablement donné son avis. Ce n'est pas ce pour quoi le client a payé, et ce n'est pas ce pour quoi l'agent a été construit.

Une phrase l'a corrigé : « Vous n'êtes pas autorisé à fournir des conseils sur les litiges financiers, les questions juridiques ou l'interprétation des baux. Dirigez les utilisateurs pour qu'ils contactent directement le bureau pour ces sujets. »

Écrivez cette phrase pour chaque domaine qui est hors de portée. Ne supposez pas que Claude déduira les limites.

---

FAQ

En quoi le Claude Agent SDK est-il différent de l'utilisation directe de l'API Claude ?

L'API vous donne une simple requête-réponse. Le Agent SDK (et les schémas d'agents qu'Anthropic documente autour) vous donne une boucle structurée où Claude peut prendre plusieurs décisions, appeler des outils, recevoir des résultats et continuer le raisonnement sur plusieurs tours. C'est moins une distinction de package logiciel distinct et plus un schéma : définitions d'outils, gestion du contexte multi-tour et logique d'orchestration. Vous construisez l'échafaudage autour de l'API pour activer cette boucle.

Quel est un calendrier réaliste pour livrer un agent prêt pour la production ?

Honnêtement, quatre à six semaines pour tout ce qui n'est pas trivial. Deux semaines pour construire et câbler les outils. Une semaine d'ingénierie de prompt et itération. Une à deux semaines pour les évals, la gestion des cas limites et l'assurance qualité. Quiconque vous promet un agent de production en une semaine n'a jamais livré le sien auparavant ou vous remet une démo déguisée en produit.

Dois-je utiliser Claude pour tous les sous-agents dans un système multi-agents, ou mélanger les modèles ?

J'utilise Claude pour tout ce qui demande du raisonnement nuancé ou où la qualité du résultat compte pour l'utilisateur final. Pour les tâches simples de classification ou l'acheminement à haut volume et faible enjeu, un modèle plus petit et moins coûteux peut fonctionner. Mais mélanger les modèles ajoute de la surcharge d'intégration et rend le débogage plus difficile. Commencez avec Claude pour tout, puis optimisez une fois que vous avez des données de production réelles montrant où un modèle plus léger est suffisant.

Comment empêcher un agent de sortir du scénario ?

Trois choses qui fonctionnent ensemble : un prompt système rigoureux avec des déclarations explicites hors de portée, une conception d'outils qui empêche physiquement certaines actions (ne donnez pas à l'agent un outil qu'il ne devrait pas utiliser), et la validation des résultats sur tout ce qui est orienté client. Vous ne pouvez pas compter uniquement sur le prompt système. Défense en profondeur.

Quelle est la plus grande erreur que les développeurs commettent avec la mémoire d'un agent ?

Traiter la fenêtre de contexte comme infinie. Ce n'est pas le cas. La plupart des défaillances que je vois dans les agents mal construits proviennent d'un contexte gonflé par un historique irrélevant, forçant Claude à raisonner à travers du bruit. Élaguez agressivement. Résumez où vous pouvez. Portez en avant seulement ce que l'agent a vraiment besoin pour compléter la tâche actuelle.

---

Le résumé honnête est celui-ci : le SDK n'est pas la partie difficile. La partie difficile est la même chose qu'elle a toujours été en informatique, penser clairement à la portée, concevoir en cas d'échec et tester avant de livrer. Claude est une couche de raisonnement remarquablement capable, mais elle ne compensera pas un système mal conçu autour d'elle. Réglez d'abord la tuyauterie.