Vous voilà au douzième et dernier module. Depuis le début de cette formation, vous pilotez Claude Code depuis le terminal : vous tapez, il travaille, vous validez. Aujourd’hui, on soulève le capot. Le moteur qui fait tourner Claude Code devient une brique logicielle que vous pouvez intégrer dans vos propres programmes. À la fin de ce module, vous saurez construire un agent qui travaille pour vous sans terminal — et vous repartirez avec les huit réflexes qui séparent l’utilisateur occasionnel du professionnel.

Ce que vous allez apprendre

• Comprendre ce qu’est l’Agent SDK et pourquoi c’est le moteur de Claude Code
• Écrire un premier agent complet en TypeScript, puis le même en Python
• Maîtriser les options essentielles : outils autorisés, permissions, contexte de travail
• Créer un outil sur mesure branché sur vos propres données
• Mémoriser la boîte à outils du senior : huit réflexes qui résument toute la formation

L’Agent SDK : le moteur de Claude Code dans votre code

Commençons par une définition. Un SDK, pour Software Development Kit, c’est un kit de développement : une bibliothèque prête à l’emploi que vous installez dans vos projets pour profiter d’une technologie sans la réinventer. L’Agent SDK d’Anthropic — anciennement appelé Claude Code SDK, puis renommé Claude Agent SDK — expose exactement ce qui fait la force de Claude Code : la boucle agentique.

La boucle agentique, vous la connaissez sans le savoir. C’est ce cycle que vous observez depuis le premier module : Claude lit votre demande, choisit un outil, agit, observe le résultat, puis recommence jusqu’à ce que la tâche soit terminée. Ajoutez à cela la gestion des permissions, la gestion du contexte et l’accès aux outils, et vous avez le moteur complet.

Voici l’image à retenir : Claude Code, c’est une voiture prête à conduire. L’Agent SDK, c’est le même moteur, livré seul, que vous montez dans le châssis de votre choix. Un bot de revue de code, un assistant support, un agent de supervision : la carrosserie, c’est vous qui la construisez, en TypeScript ou en Python.

Pourquoi est-ce important ? Parce que tout ce que vous avez appris dans cette formation — outils, permissions, MCP, sous-agents, hooks — reste valable. Les concepts sont identiques. Seule l’interface change : au lieu de taper dans un terminal, vous écrivez du code qui pilote l’agent. Si un terme vous échappe en route, le glossaire du site reste votre ami.

Votre premier agent en TypeScript

Passons à la pratique. L’installation tient en une commande, dans n’importe quel projet Node.js :

# Installe l'Agent SDK dans votre projet
npm install @anthropic-ai/claude-agent-sdk

Le cœur du SDK, c’est une seule fonction : query(). Vous lui donnez un prompt et des options, elle vous rend un itérateur asynchrone de messages. Un itérateur asynchrone, c’est comme un tapis roulant : les messages arrivent un par un, au fil du travail de l’agent, et votre code les consomme au fur et à mesure. Voici un agent minimal, complet et fonctionnel :

// agent.ts — votre premier agent en une quinzaine de lignes
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Explore ce projet et résume son architecture en cinq points",
  options: {
    cwd: "/chemin/vers/le/projet",          // le dossier de travail de l'agent
    allowedTools: ["Read", "Glob", "Grep"], // liste blanche : lecture seule
    maxTurns: 10                             // coupe-circuit : dix allers-retours maximum
  }
})) {
  // Chaque étape de l'agent arrive ici, en direct
  console.log(message);
}

C’est tout. La boucle for await consomme le tapis roulant : messages système, actions d’outils, réponses de l’assistant, puis un dernier message de type result qui clôt l’exécution avec la réponse finale. Pour l’authentification, le SDK s’appuie sur votre clé API Anthropic, fournie via la variable d’environnement ANTHROPIC_API_KEY — exactement comme pour le mode headless vu au module précédent.

Le même agent en Python

Vous êtes plutôt Python ? Le SDK existe aussi de ce côté, avec la même philosophie :

# Installe l'Agent SDK Python
pip install claude-agent-sdk

La fonction query() est asynchrone, et les options passent par un objet ClaudeAgentOptions :

# agent.py — le même agent, côté Python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        cwd="/chemin/vers/le/projet",
        allowed_tools=["Read", "Glob", "Grep"],  # liste blanche, lecture seule
        max_turns=10,                             # même coupe-circuit qu'en TypeScript
    )
    async for message in query(
        prompt="Explore ce projet et résume son architecture en cinq points",
        options=options,
    ):
        print(message)  # les messages arrivent au fil de l'eau

asyncio.run(main())

Notez la différence de style : le TypeScript écrit allowedTools, le Python écrit allowed_tools. Les concepts, eux, sont rigoureusement les mêmes. Le SDK Python propose aussi ClaudeSDKClient, une classe pour les conversations longues : elle garde la session ouverte entre plusieurs questions, là où query() repart de zéro à chaque appel.

💡 Astuce — Fixez toujours maxTurns, même sur un agent de confiance. C’est votre disjoncteur : si l’agent part dans une boucle improductive, il s’arrête au bout du nombre d’allers-retours fixé au lieu de consommer des tokens à l’infini. Dix tours suffisent pour la plupart des tâches d’analyse.

Les options qui comptent

Vous venez de croiser trois options. Voici les six qui font quatre-vingt-dix pour cent du travail — et vous allez voir qu’elles racontent toute la formation :

• allowedTools : la liste blanche des outils approuvés sans question. C’est le pendant programmatique du bloc permissions de settings.json vu au module sur la sécurité. Un agent sans humain devant l’écran doit avoir une liste courte et précise.
• permissionMode : les mêmes modes que dans le terminal — default, acceptEdits, plan, bypassPermissions. Oui, le plan mode existe aussi en programmatique : votre agent peut explorer en lecture seule avant d’agir.
• cwd : le dossier de travail, l’équivalent du répertoire où vous lancez claude. L’agent y confine son exploration.
• mcpServers : les serveurs MCP à brancher, comme avec claude mcp add — mais déclarés en code. On y revient dans un instant.
• systemPrompt : le prompt système, autrement dit la personnalité et les consignes de fond de votre agent. C’est le rôle que jouait CLAUDE.md dans vos sessions interactives.
• maxTurns : le nombre maximal de tours de boucle agentique. Votre disjoncteur.

Relisez cette liste. Outils, permissions, contexte, MCP, consignes : ce sont les chapitres de cette formation, condensés dans un objet d’options. Rien de nouveau à apprendre — juste une nouvelle façon de l’exprimer.

⚠️ Piège courant — Ne mettez jamais bypassPermissions dans un agent qui tourne sur votre machine de travail ou en production. Ce mode saute toutes les validations, comme l’option —dangerously-skip-permissions du terminal. Il est réservé aux environnements isolés et jetables : un conteneur de CI, une machine virtuelle sans données sensibles. Partout ailleurs, une liste blanche allowedTools bien pensée fait le travail, en mieux.

Des outils sur mesure : brancher l’agent sur vos données

Jusqu’ici, votre agent utilise les outils intégrés : lire des fichiers, chercher du texte, lancer des commandes. Mais le vrai pouvoir du SDK, c’est de lui donner vos outils à vous. Imaginez un agent support qui interroge votre base clients. Aucun outil intégré ne sait faire cela — alors vous allez le lui apprendre.

Le mécanisme s’appelle le serveur MCP in-process. In-process signifie « dans le même processus » : contrairement aux serveurs MCP classiques du module précédent, qui tournent dans un programme séparé, celui-ci vit directement dans votre code. Pas de processus externe à lancer, pas de configuration réseau. Deux fonctions suffisent : tool() pour décrire un outil, createSdkMcpServer() pour les regrouper en serveur.

// support-agent.ts — un agent support branché sur VOTRE base clients
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

// 1. On décrit l'outil : nom, description, paramètres, puis le code qui s'exécute
const rechercheClient = tool(
  "recherche_client",
  "Recherche un client dans la base interne par son adresse email",
  { email: z.string() },                     // schéma des paramètres, validé par Zod
  async ({ email }) => {
    // Pseudo-code : remplacez par votre vrai accès base de données
    const client = await maBase.clients.trouverParEmail(email);
    return { content: [{ type: "text", text: JSON.stringify(client) }] };
  }
);

// 2. On regroupe les outils dans un serveur MCP in-process
const serveurSupport = createSdkMcpServer({
  name: "support",
  version: "1.0.0",
  tools: [rechercheClient]
});

// 3. On branche le serveur sur l'agent, avec une liste blanche explicite
for await (const message of query({
  prompt: "La cliente marie@exemple.fr signale une facturation en double. Analyse son dossier et propose une réponse.",
  options: {
    mcpServers: { support: serveurSupport },
    allowedTools: ["mcp__support__recherche_client"],
    maxTurns: 15
  }
})) {
  console.log(message);
}

Regardez bien la description de l’outil : c’est elle que l’agent lit pour décider quand l’appeler. Soignez-la comme vous soigneriez la description d’un sous-agent. Côté Python, le principe est identique : un décorateur @tool sur une fonction asynchrone, puis create_sdk_mcp_server pour l’exposer.

⚠️ Piège courant — Dans allowedTools, un outil MCP porte son nom complet : mcp__serveur__outil, avec des doubles tirets bas. Si vous écrivez seulement recherche_client, la liste blanche ne correspond pas et l’outil n’est jamais approuvé. Vous avez déjà croisé cette convention au module MCP : elle s’applique à l’identique dans le SDK.

💡 Astuce — Gardez vos prompts système courts et vos descriptions d’outils précises. Un agent SDK n’a pas d’humain pour rattraper une consigne floue : tout ce qu’il sait tenir dans systemPrompt, les descriptions d’outils et le prompt de départ. Relisez-les à voix haute — si c’est ambigu pour vous, c’est ambigu pour lui.

Des agents dans la vraie vie

À quoi ressemblent les agents construits avec ce SDK ? Voici quatre cas réels, du plus proche du code au plus éloigné.

Le bot de revue de code en CI. À chaque pull request, un agent relit le diff, vérifie les conventions du projet et poste ses remarques. Vous connaissez déjà la version clé en main : /install-github-app configure le dépôt, puis @claude dans une issue ou une pull request déclenche l’action GitHub. Le SDK permet d’aller plus loin : votre propre logique de filtrage, vos propres règles, votre propre format de rapport.

L’agent SRE de diagnostic. SRE, pour Site Reliability Engineer, désigne l’ingénieur qui veille sur la fiabilité des systèmes en production. Un agent SDK peut jouer les premiers secours : à la réception d’une alerte, il consulte les logs via un outil custom, corrèle avec les déploiements récents et rédige un premier diagnostic — avant même qu’un humain ait ouvert son ordinateur portable. L’humain décide, l’agent défriche.

Le pipeline de migration continue. Migrer trois cents fichiers d’une vieille bibliothèque vers une nouvelle, c’est répétitif et vérifiable : exactement le profil d’une tâche pour agent. Un script parcourt les fichiers par petits lots, lance un agent par lot avec des outils d’écriture autorisés, exécute les tests après chaque lot, et s’arrête au premier rouge. Petits pas, vérification systématique : les réflexes du module sur les workflows, automatisés.

L’agent métier, hors code. Rien n’oblige un agent à manipuler du code. Donnez-lui des outils qui lisent vos données métier, et il rédige le rapport hebdomadaire, vérifie la conformité de documents ou prépare des synthèses. La boucle agentique est générique : lire, agir, vérifier, recommencer — quel que soit le métier.

💡 Astuce — Avant de construire un agent SDK complet, prototypez en une ligne avec le mode headless : claude -p avec —allowedTools et —output-format json. Si le prototype fonctionne en ligne de commande, le portage vers le SDK est trivial. S’il échoue, vous venez d’économiser une journée de développement.

La boîte à outils du senior : huit réflexes

Douze modules, huit réflexes. Voici la synthèse de toute cette formation — la liste que je vous invite à relire dans un mois, puis dans six.

1. Le contexte est une ressource : gérez-la. La fenêtre de contexte n’est pas infinie. /compact pour résumer, /clear pour repartir propre, /cost pour mesurer. Un contexte encombré, c’est un agent imprécis.
2. Petits pas vérifiables, tests à l’appui. Une grosse tâche se découpe en étapes courtes, chacune validée par des tests. C’est vrai dans le terminal, c’est vital dans un pipeline automatisé.
3. Plan mode d’abord sur le non-trivial. Toute tâche qui touche plus de deux fichiers mérite une exploration en lecture seule et un plan validé. Shift+Tab dans le terminal, permissionMode plan dans le SDK.
4. L’humain relit, toujours. L’agent propose, vous disposez. Aucune automatisation ne remplace la relecture du diff avant de fusionner. Jamais.
5. CLAUDE.md et settings versionnés : le contrat d’équipe. Les conventions du projet et les permissions vivent dans git, pas dans la tête de chacun. /init pour démarrer, # pour enrichir au fil de l’eau.
6. Deny sur les secrets, hooks en garde-fous. Les règles deny protègent .env et les credentials — elles priment sur tout. Les hooks bloquants (exit 2) attrapent ce que la vigilance humaine laisse passer.
7. Déléguez l’exploration aux sous-agents. Recherche large, audit, lecture de gros volumes : un sous-agent avec son propre contexte, pendant que votre session principale reste concentrée.
8. Mesurez coûts et qualité, adoptez progressivement. /cost pour les tokens, vos métriques habituelles pour la qualité du code. On commence petit, on prouve la valeur, on étend. Pas l’inverse.

Ces huit réflexes tiennent sur une fiche. Le reste — les commandes, les options, la syntaxe — se retrouve en dix secondes avec /help ou dans la documentation officielle sur https://code.claude.com/docs.

Le mot de la fin : votre métier change

Prenons une seconde de recul. Ce que cette formation raconte, au fond, ce n’est pas un outil : c’est un déplacement du métier. Le développeur qui maîtrise ces agents écrit moins de lignes lui-même, mais il décide de plus de choses. Il devient architecte — il découpe les problèmes et fixe le cadre. Relecteur — il juge, corrige, assume la qualité finale. Orchestrateur — il fait travailler des agents en parallèle, chacun dans son couloir, avec les bons garde-fous.

Ce ne sont pas des compétences au rabais. Découper un problème, écrire un contrat d’équipe clair, poser des limites de sécurité, relire avec exigence : c’est précisément ce qui distinguait déjà les meilleurs ingénieurs avant l’IA. Les agents n’ont fait que rendre ces compétences décisives.

Et pour continuer ? Trois pistes. Explorez le dossier intelligence artificielle du site, qui prolonge cette formation côté usages et culture générale. Gardez un œil sur le paysage des modèles — notre comparatif des IA est là pour cela, d’autant que les gammes évoluent vite : à la date de cette formation, la famille Claude 5 est la génération courante, et /model vous permet d’en changer en une commande. Enfin, construisez. Un petit agent, un vrai besoin, cette semaine. C’est en forgeant.

À vous de jouer

Pour ce dernier exercice, vous allez construire votre premier agent SDK de bout en bout : un résumeur de projet, en lecture seule, donc sans risque.

1. Créez un dossier vide, puis initialisez un projet Node.js : npm init -y. Vérifiez que vous avez Node.js 18 ou plus récent.
2. Installez le SDK : npm install @anthropic-ai/claude-agent-sdk. Renseignez votre clé API dans la variable d’environnement ANTHROPIC_API_KEY.
3. Créez un fichier agent.mjs et recopiez l’exemple TypeScript de ce module en l’adaptant : prompt « Explore ce projet et résume son architecture », options cwd pointant vers un de vos vrais projets, allowedTools limité à Read, Glob et Grep, maxTurns à 10.
4. Lancez node agent.mjs et observez le tapis roulant : messages système, appels d’outils, réponse finale. Prenez le temps de lire la structure de chaque message.
5. Cassez quelque chose volontairement : retirez Glob de la liste blanche et relancez. Observez comment l’agent se débrouille — ou échoue. Vous venez de toucher du doigt l’effet réel d’une liste blanche.
6. Défi bonus : ajoutez un outil custom meteo_locale avec tool() et createSdkMcpServer(), qui renvoie une valeur en dur, et demandez à l’agent de l’utiliser. N’oubliez pas le nom complet mcp__serveur__outil dans allowedTools.

En résumé

• L’Agent SDK expose le moteur de Claude Code — boucle agentique, outils, permissions, contexte — dans vos propres programmes TypeScript (npm install @anthropic-ai/claude-agent-sdk) et Python (pip install claude-agent-sdk).
• La fonction query() prend un prompt et des options, et renvoie un itérateur asynchrone de messages que votre code consomme au fil de l’eau.
• Six options font l’essentiel : allowedTools, permissionMode, cwd, mcpServers, systemPrompt, maxTurns — les concepts de toute la formation, en programmatique.
• Les outils sur mesure se définissent en code avec tool() et createSdkMcpServer() : un serveur MCP in-process, sans processus externe, branché sur vos données.
• Un agent sans humain devant l’écran exige des garde-fous stricts : liste blanche courte, maxTurns, jamais de bypassPermissions hors environnement isolé.
• Les huit réflexes du senior tiennent en une phrase : contexte géré, petits pas testés, plan d’abord, relecture humaine, contrat versionné, secrets protégés, exploration déléguée, adoption mesurée.

Cette formation s’achève ici, mais votre pratique commence maintenant : vous avez le moteur, la carrosserie et le code de la route — il ne reste qu’à prendre le volant, et la route est à vous.