Agents et automatisation

Le SDK Agent Claude

Le SDK Agent Claude (Software Development Kit) est la bibliothèque officielle d'Anthropic qui vous permet de créer des programmes dans lesquels Claude agit de manière autonome : il lit des entrées, décide quels outils appeler, les exécute, lit les résultats et boucle jusqu'à ce que la tâche soit terminée. C'est différent d'un simple message de chat, car le modèle pilote un flux de travail en plusieurs étapes, pas seulement une réponse unique.

Le SDK est publié sous le nom @anthropic-ai/claude-code-sdk pour JavaScript/TypeScript et offre une interface similaire en Python. Il expose principalement une fonction de streaming appelée query() qui envoie une invite à Claude, diffuse en continu chaque tour d'assistant et chaque bloc d'utilisation d'outil (chaque action discrète que Claude décide d'effectuer), et permet à votre code de réagir à chaque événement en temps réel.

Ce que vous pouvez construire couvre un large spectre :

• Agents de codage sans interface : exécutez Claude Code de manière non interactive dans un pipeline CI/CD (pipeline d'intégration continue, système automatisé de construction et de test) pour écrire, corriger ou réviser du code à chaque commit.
• Intégrations IDE personnalisées : intégrez Claude dans n'importe quel éditeur en redirigeant sa sortie vers votre propre interface au lieu du terminal.
• Pipelines multi-agents : une instance Claude joue le rôle d'orchestrateur et lance des sous-agents, chacun avec des permissions plus limitées et une sous-tâche spécifique.
• Flux d'approbation : interceptez chaque appel d'outil avant son exécution afin qu'un humain (ou un autre modèle) puisse l'approuver, le rejeter ou le modifier.

Le SDK applique le même modèle de permissions que Claude Code interactif : vous déclarez quels outils sont autorisés (lectures de fichiers, commandes shell, serveurs MCP) et l'agent ne peut pas dépasser cette portée. Cela le rend sécurisé pour une utilisation dans des environnements automatisés sans surveillance humaine.

Anatomie d'une boucle agentique

Une boucle agentique est le cycle répétitif qui permet à un modèle d'IA d'effectuer un travail en plusieurs étapes de manière autonome. Au lieu de répondre une seule fois puis de s'arrêter, le modèle passe par quatre phases en boucle jusqu'à ce que la tâche soit terminée ou qu'il décide de s'arrêter.

Les quatre phases sont :

1. Percevoir : le modèle lit son contexte actuel (votre objectif, les résultats précédents, les sorties des outils, la mémoire).
2. Décider : il choisit l'action suivante (appeler un outil, écrire un fichier, poser une question de clarification ou déclarer la tâche terminée).
3. Agir : il exécute cette action, par exemple en lançant une commande shell ou en modifiant un fichier.
4. Observer : il lit le résultat (stdout, message d'erreur, diff de fichier) et l'ajoute au contexte, puis revient à la phase Percevoir.

Claude Code (l'agent de codage CLI et IDE) est construit autour de cette boucle. Chaque itération s'appelle un tour. La boucle se termine quand le modèle émet une réponse texte finale au lieu d'un nouvel appel d'outil, ou quand une condition d'arrêt que vous avez définie est atteinte (budget de tokens, nombre maximal de tours ou sortie explicite).

Comprendre la boucle est essentiel, car chaque dysfonctionnement que vous aurez à déboguer dans un agent (qu'il tourne indéfiniment, abandonne trop tôt ou rate une étape) trouve son origine dans l'une de ces quatre phases qui se déroule mal.

Définir les outils auxquels un agent peut faire confiance

Un outil est une fonction que vous exposez à un agent pour lui permettre d'effectuer des actions au-delà de la génération de texte : interroger une base de données, appeler une API, lire un fichier. L'agent décide quand appeler chaque outil en se basant uniquement sur les informations que vous lui fournissez dans la définition de l'outil. Si cette définition est vague, l'agent devine, et se trompe souvent.

Chaque définition d'outil comporte trois parties que l'agent lit avant de décider s'il doit l'utiliser :

• Nom : court, sans ambiguïté, en snake_case (par exemple get_order_status plutôt que tool1 ou fetch). Le nom seul doit laisser deviner ce que fait l'outil.
• Description : une ou deux phrases expliquant ce que fait l'outil, quand l'utiliser, et quand NE PAS l'utiliser. C'est le champ le plus important. Le modèle le lit comme un contexte de raisonnement, pas simplement comme une documentation.
• Schéma : un objet JSON Schema listant chaque paramètre, son type, s'il est obligatoire, et une courte description de chaque champ. Des descriptions de paramètres ambiguës ou absentes provoquent des hallucinations silencieuses, où l'agent comble les lacunes avec des valeurs d'apparence plausible.

Un outil bien défini est autonome : un autre développeur (ou un autre modèle) doit pouvoir lire la définition seule et savoir exactement quand et comment l'appeler. Traitez la description comme un contrat, pas comme un commentaire.

Automatisation sans interface dans les scripts

Le mode headless consiste à exécuter Claude Code sans aucune invite interactive : pas de clavier, pas de terminal qui attend votre saisie. Vous envoyez les données en entrée par un pipe, Claude les traite, et votre script lit le résultat en sortie. C'est ainsi que vous intégrez Claude dans des pipelines CI, des tâches cron ou tout autre flux de travail automatisé.

Le flag essentiel est --print (raccourci : -p), qui demande à Claude Code d'afficher la réponse finale et de quitter immédiatement. Combinez-le avec --output-format json pour obtenir une sortie structurée que votre script peut analyser de façon fiable. Utilisez --model pour fixer un identifiant de modèle précis afin que votre pipeline n'effectue jamais de mise à niveau silencieuse.

Quelques flags sont importants en automatisation :

• --print : mode non interactif, affiche le résultat et quitte.
• --output-format json : encapsule la réponse dans une enveloppe JSON avec les champs result, cost et session_id.
• --model claude-sonnet-4-6 : fixe le modèle (options : claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5).
• --max-turns N : limite le nombre de tours agentiques pour qu'une boucle infinie ne tourne pas indéfiniment.
• --no-ansi : supprime les codes de couleur pour que les fichiers journaux restent propres.

L'entrée standard fonctionne aussi : envoyez un fichier ou une invite générée directement dans claude via un pipe. Le processus quitte avec le code 0 en cas de succès et un code non nul en cas d'erreur, ce qui permet à votre shell ou script Node de gérer les échecs de la façon habituelle.

Claude dans GitHub Actions

GitHub Actions est une plateforme CI/CD (Intégration Continue / Livraison Continue) intégrée à GitHub. Chaque push, pull request ou déclencheur planifié peut lancer un workflow, un fichier YAML qui exécute des étapes dans un conteneur. Claude peut être l'une de ces étapes, transformant une revue de niveau humain en une vérification automatisée qui s'exécute à chaque pull request sans attendre un coéquipier.

Le point d'entrée officiel est claude-code-action, une GitHub Action open-source publiée par Anthropic. Vous l'ajoutez à votre YAML de workflow, transmettez votre ANTHROPIC_API_KEY comme secret, et l'action lance Claude Code dans un conteneur sans interface graphique. Claude lit le diff, les fichiers de votre dépôt et les instructions que vous fournissez, puis publie ses conclusions sous forme de commentaire de PR ou définit un statut de vérification échoué.

Les schémas d'automatisation courants en CI comprennent :

• Revue de PR à chaque ouverture ou mise à jour : Claude lit le diff et publie un commentaire de revue de code structuré.
• Vérification de sécurité : Claude recherche les secrets codés en dur ou les risques d'injection évidents et fait échouer la vérification si des problèmes sont trouvés.
• Étiquetage automatique : Claude lit le diff et applique des labels GitHub tels que bug, feature ou docs.
• Brouillon de notes de version : À chaque push sur main, Claude résume tous les titres de PR fusionnées en une entrée de changelog.

Le choix du modèle influe sur le coût et la vitesse. Le modèle claude-haiku-4-5 (le plus rapide et le moins cher) gère bien l'étiquetage et les courtes synthèses. claude-sonnet-4-6 est la valeur par défaut recommandée pour les revues complètes de PR. claude-opus-4-8 est réservé aux audits de sécurité approfondis où la précision prime sur le coût plus élevé par token.

Agents cloud planifiés

Le skill /schedule vous permet de créer des agents cloud (aussi appelés routines) qui exécutent Claude Code selon un calendrier récurrent, sans que vous soyez présent. L'agent s'exécute dans le cloud, lit votre dépôt ou vos fichiers, effectue des tâches, et peut valider les résultats ou envoyer des notifications, le tout selon un planning cron (un format de déclenchement basé sur l'heure, comme "chaque jour à 9 h").

Vous invoquez le skill dans Claude Code en tapant /schedule, suivi d'une description en langage naturel de ce que vous souhaitez faire et à quel moment. Claude convertit cette description en une routine planifiée stockée dans votre compte. Vous pouvez aussi l'utiliser pour des exécutions uniques dans le futur ("exécuter une seule fois à 15 h") sans aucun motif récurrent.

Les cas d'usage courants des agents cloud planifiés incluent :

• Des audits SEO ou de performance quotidiens qui commitent un rapport dans votre dépôt chaque matin
• Des vérifications hebdomadaires de dépendances qui ouvrent une pull request lorsque des mises à jour sont trouvées
• Une surveillance horaire d'une API ou d'un service qui vous alerte en cas d'anomalie
• Des tâches de pipeline de données nocturnes qui traitent les journaux et mettent à jour un fichier de tableau de bord

Vous gérez vos routines avec le même skill : listez-les pour voir ce qui est planifié, mettez à jour une routine pour modifier son calendrier ou ses instructions, ou supprimez-en une lorsqu'elle n'est plus nécessaire. Chaque routine s'exécute comme une session d'agent Claude Code complète : elle a accès aux outils, peut lire et écrire des fichiers, et peut appeler des services externes dans les limites de vos permissions configurées.

Le schéma /loop

La skill /loop dans Claude Code vous permet d'exécuter un prompt (ou une autre commande slash) de manière répétée, soit à intervalle fixe, soit à un rythme que le modèle décide lui-même entre chaque itération. Pensez-y comme à une tâche planifiée (cron job) intégrée directement dans votre session Claude, sans planificateur externe.

Pour démarrer une boucle, tapez /loop suivi d'un intervalle optionnel et d'un prompt ou d'une commande. Si vous omettez l'intervalle, Claude s'autorythme : il termine une exécution, décide combien de temps attendre selon le contexte, puis relance. C'est utile pour les tâches de surveillance dont la cadence idéale dépend de ce que le modèle trouve.

Cas d'usage courants pour /loop :

• Interroger un journal de déploiement toutes les 2 minutes jusqu'à l'apparition d'un mot-clé
• Lancer un linter ou une suite de tests à intervalle régulier pendant que vous éditez
• Vérifier un endpoint API pour un changement de statut sans écrire de script shell
• Exécuter une commande slash personnalisée (comme /babysit-prs) selon un calendrier

Pour arrêter une boucle en cours, utilisez /stop ou appuyez sur Ctrl+C. Chaque itération est un tour normal de Claude Code, donc le modèle a accès à tous les outils (lecture de fichiers, commandes shell, récupération web) à chaque cycle.

Agents dans des worktrees isolés

Un git worktree est une deuxième (ou troisième, ou quatrième) copie extraite du même dépôt, qui vit dans son propre répertoire sur le disque et partage le magasin d'objets git sous-jacent. Chaque worktree possède ses propres fichiers de travail et sa propre branche, si bien que les modifications dans un worktree ne peuvent pas toucher un autre tant que vous ne fusionnez pas explicitement.

Lorsque vous exécutez plusieurs agents Claude Code en parallèle, chaque agent modifiant les mêmes fichiers sur la même branche est une recette pour les conflits. Le schéma sûr est : un agent, un worktree, une branche. Les agents travaillent en isolation complète ; vous relisez et fusionnez quand ils ont terminé.

Claude Code intègre deux commandes slash natives pour ce flux de travail :

• /worktree create <name> crée un nouveau worktree et une branche associée, puis y bascule l'agent.
• /worktree list affiche tous les worktrees actifs et l'agent (le cas échéant) qui s'y exécute.
• /worktree remove <name> supprime le répertoire du worktree une fois l'agent terminé.
• La commande git standard fonctionne aussi : git worktree add ../repo-feat-a feat/a crée un worktree manuellement si vous préférez.

Le bénéfice est la mutation parallèle sûre : trois agents peuvent refactoriser trois modules différents en même temps, chacun sur sa propre branche, sans aucun risque qu'un agent écrase les modifications en cours d'un autre. Vous collectez leurs pull requests et fusionnez dans l'ordre.

MCP en production et outils distants

Le Model Context Protocol (MCP) est un standard ouvert qui permet à un agent IA d'appeler des outils externes, de lire des ressources et de recevoir des données structurées, le tout via une interface commune. Au lieu de coder en dur des appels API dans un prompt, vous les exposez sous forme de définitions d'outils MCP que tout agent compatible peut découvrir et invoquer au moment de l'exécution.

Un déploiement MCP en production sépare clairement les responsabilités. Le serveur MCP gère la connexion à votre backend (base de données, API REST, système de fichiers). Le client MCP intégré à Claude Code lit le manifeste du serveur, connaît les outils disponibles et les arguments attendus, et décide quand les appeler. Claude ne voit jamais vos credentials directement : le serveur gère l'authentification et renvoie uniquement les données dont l'agent a besoin.

Enregistrer un serveur MCP distant dans Claude Code nécessite une seule entrée dans les paramètres de votre projet ou paramètres globaux. Le serveur peut tourner en local ou sur un hôte distant via stdio (entrée/sortie standard, pour les processus locaux) ou SSE (Server-Sent Events, le transport HTTP en streaming utilisé pour les serveurs distants). Les bonnes pratiques de fiabilité comprennent :

• Validation du schéma : chaque outil doit déclarer son JSON Schema afin que l'agent puisse former des appels corrects et rejeter les mauvaises réponses tôt.
• Outils idempotents : les opérations d'écriture doivent être sûres à rejouer, car l'agent peut rappeler un outil après un timeout.
• Permissions restreintes : listez uniquement les outils dont l'agent a besoin pour un workflow donné ; une surface plus petite signifie moins d'erreurs et des audits plus simples.
• Réponses d'erreur structurées : renvoyez des objets d'erreur lisibles par machine, et non des chaînes simples, pour que l'agent puisse décider de relancer, d'escalader ou de s'arrêter.

L'état d'esprit de l'exécution parallèle

La plupart des gens confient une tâche à un agent, attendent la réponse, puis donnent la tâche suivante. C'est une pensée sérielle, et c'est lent. L'état d'esprit de l'exécution parallèle traite votre objectif comme un arbre : décomposez-le en branches indépendantes, lancez toutes les branches en même temps, puis fusionnez les résultats.

Le schéma en quatre étapes est décomposer, distribuer, vérifier, synthétiser. Décomposer signifie diviser l'objectif en sous-tâches qui ne partagent aucune dépendance bloquante entre elles. Distribuer signifie les lancer toutes simultanément, soit en demandant à Claude de créer des sous-agents, soit en envoyant plusieurs appels vous-même. Vérifier signifie contrôler chaque résultat avant de lui faire confiance (repérer les mauvaises réponses tôt, pas après la synthèse). Synthétiser signifie combiner les sorties vérifiées en livrable final.

Dans Claude Code, vous pilotez cela avec le flag --dangerously-skip-permissions pour les exécutions non interactives, ou avec le Task tool à l'intérieur d'un prompt d'agent, qui permet à une instance Claude de créer des sous-agents parallèles. La Batch API (l'endpoint dédié d'Anthropic) est la bonne couche quand vous avez besoin de centaines d'appels indépendants à 50 % du coût et sans toucher votre limite de débit par minute.

Schémas courants où cet état d'esprit est rentable :

• Distribution de recherche : envoyez la même question à plusieurs requêtes de recherche à la fois, puis réconciliez.
• Audit multi-fichiers : assignez chaque fichier ou module à un sous-agent séparé, fusionnez les résultats.
• Pipeline de traduction : traduisez en quatre langues simultanément plutôt que séquentiellement.
• Vérification contradictoire : après qu'un sous-agent a écrit une réponse, un second sous-agent la critique avant la synthèse.

Vérification adversariale à grande échelle

Lorsqu'un seul appel IA produit un résultat, vous ne pouvez pas savoir s'il est correct, halluciné ou biaisé par la formulation de votre prompt. La vérification adversariale résout ce problème en faisant tourner plusieurs agents indépendants sur la même tâche, puis en réconciliant leurs sorties, de sorte que les erreurs s'annulent au lieu de se propager silencieusement.

Le schéma de base est un panel de juges : vous envoyez la même question (ou le même élément de preuve) à plusieurs instances de Claude, chacune avec un system prompt ou un réglage de température légèrement différent (la température contrôle le degré d'aléatoire dans les choix de mots du modèle). Chaque juge rend un verdict. Un agrégateur par vote majoritaire choisit ensuite la réponse la plus fréquente. Si le panel est partagé, le système peut escalader vers un modèle plus puissant comme claude-opus-4-8 pour départager, plutôt que d'accepter aveuglément une seule réponse.

À grande échelle, cela devient un pipeline. Une étape de fan-out distribue une tâche à N agents en parallèle simultanément, en utilisant le flag --dangerously-skip-permissions de Claude Code ou un script batch sans interface pour éviter les invites interactives. Une étape de réduction collecte toutes les réponses et applique la règle de vote. La réduction elle-même peut être un appel Claude avec un prompt strict qui ne compte que les verdicts explicites, en ignorant le langage hedging.

Choix de conception clés pour un panel fiable :

• Taille impaire du panel : utilisez 3 ou 5 juges pour éviter les égalités sur les questions binaires.
• Diversité des prompts : variez la formulation entre les juges pour qu'ils ne soient pas tous trompés par le même cadrage.
• Sortie structurée : forcez chaque juge à retourner un label lisible par la machine comme PASS ou FAIL avant toute explication, afin que la réduction parse proprement.
• Pondération par la confiance : demandez optionnellement à chaque juge un score de confiance de 0 à 10 etpondérez le vote en conséquence, plutôt que de traiter tous les votes également.

Quand ne pas utiliser les agents

Un agent est une boucle : le modèle planifie, appelle des outils, lit les résultats, et recommence jusqu'à ce que la tâche soit terminée. Cette boucle a un coût en temps, en tokens, et introduit des points de défaillance à chaque étape. Beaucoup de tâches n'en ont pas besoin.

Une tâche en un seul appel est une tâche pour laquelle vous pouvez fournir tout le contexte nécessaire d'emblée et le modèle peut renvoyer une réponse complète et correcte en un seul appel. L'envelopper dans un agent ajoute une surcharge sans bénéfice. Utilisez l'outil le plus simple qui accomplit le travail.

Optez pour une invite simple (sans agent, sans outils) lorsque la tâche correspond à l'un de ces cas :

• La réponse ne nécessite aucune donnée externe au-delà de ce que vous collez dans le prompt.
• Aucun accès au système de fichiers, au navigateur ou à une API n'est requis.
• La sortie est suffisamment courte pour être relue en une fois.
• Réessayer en cas d'échec est moins coûteux que de construire une logique de reprise dans une boucle d'agent.
• La latence compte et une boucle d'agent aller-retour serait trop lente.

Une règle utile : si vous pourriez répondre vous-même à la question avec un résultat de recherche ou un document collé, un simple chat Claude.ai ou un appel claude en ligne de commande avec une entrée redirigée suffit. Réservez les agents Claude Code et les pipelines multi-étapes aux tâches qui nécessitent vraiment une planification sur de nombreuses étapes inconnues.