Claude Agent SDK : intégrer Claude Code dans vos apps

Pour passer de Claude Code comme assistant interactif dans le terminal à Claude Code intégré dans un outil interne, une CI, une pré-revue de PR, un contrôle de contenu ou une console de support, la cible actuelle est Claude Agent SDK.

Beaucoup d’anciens exemples utilisent encore @anthropic-ai/claude-code, claude-code-sdk ou l’expression “Claude Code SDK”. En juin 2026, la documentation officielle indique @anthropic-ai/claude-agent-sdk pour TypeScript et claude-agent-sdk pour Python. Avant de copier un extrait trouvé en ligne, vérifiez l’Agent SDK overview et le Migration Guide.

L’objectif ici n’est pas de créer un chatbot. Nous voulons un agent capable de lire des fichiers, chercher dans un dépôt, appeler des outils MCP, modifier un petit point avec permissions limitées, lancer une commande de test précise et produire un résultat relisible par un humain.

Ce que change l’Agent SDK

Claude Agent SDK permet d’utiliser dans votre programme TypeScript ou Python la boucle agentique de Claude Code. Une boucle agentique signifie que Claude choisit une action, appelle un outil, lit le résultat, puis décide de continuer ou de s’arrêter. Ce n’est donc pas une simple requête API avec une réponse unique.

Sujet	Recommandation actuelle
Package TypeScript	@anthropic-ai/claude-agent-sdk
Package Python	claude-agent-sdk
CLI vs SDK	CLI pour l’humain, SDK pour les apps et l’automatisation
Client SDK vs Agent SDK	Client SDK = boucle d’outils à coder; Agent SDK = boucle Claude Code intégrée
Risque principal	Plus les permissions sont larges, plus les erreurs peuvent être lourdes

Le SDK TypeScript embarque normalement un binaire natif Claude Code comme dépendance optionnelle. Vous n’avez donc pas toujours besoin d’installer la CLI séparément. Si votre package manager ignore les optional dependencies, le SDK peut ne pas trouver le binaire. Corrigez la politique d’installation ou passez explicitement pathToClaudeCodeExecutable.

Installation copiable

Nous utilisons TypeScript avec tsx pour exécuter les exemples sans pipeline de build.

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

Remplacez package.json par cette base :

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

La clé API doit venir de l’environnement. Ne la placez jamais dans le dépôt, les captures, les logs ou les exemples publiés.

export ANTHROPIC_API_KEY="sk-ant-..."

Sous Windows PowerShell :

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Créez ensuite src/read-only-audit.ts. Ce premier agent est volontairement en lecture seule.

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = [
  "Inspecte ce dépôt en mode lecture seule.",
  "Trouve les TODO, dépendances anciennes et zones peu testées.",
  "Retourne une liste priorisée avec des références de fichiers.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Lancez-le :

npm run audit

Commencer par la lecture seule permet de voir si l’agent produit un signal utile avant d’autoriser Edit, Write ou Bash.

Cas d’usage concrets

Claude Agent SDK est pertinent lorsque la tâche demande observation, outils et décision. Pour les workflows de Masa, les cas suivants sont les plus utiles :

Cas	Outils	Résultat	Garde-fou
Pré-revue de PR	Read, Glob, Grep	Risques, tests manquants, points de review	Le commentaire final reste humain
Petite correction	Read, Edit, Bash(npm test)	Diff minimal et tests	Interdire push, deploy, suppression
Triage d’incident	MCP runbook, recherche logs	Hypothèses et vérifications	Outils production en lecture seule
QA d’articles multilingues	Read, Grep	Mojibake, CTA absent, liens anciens	La langue reste relue par un humain

Pour compléter, lisez le guide des permissions, le guide MCP server et les astuces de productivité Claude Code.

Ajouter un outil Runbook avec MCP

MCP signifie Model Context Protocol. C’est une manière standard d’exposer des outils et sources de données à un agent. La documentation officielle MCP montre comment connecter des serveurs MCP depuis l’Agent SDK. On peut aussi définir un petit serveur dans le même processus.

import {
  createSdkMcpServer,
  query,
  tool,
} from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const runbooks: Record<string, string> = {
  billing: "Vérifier paiements échoués, webhooks Stripe et dernier deploy.",
  search: "Vérifier indexation, task status Algolia et limites API.",
  content: "Vérifier sync CMS, slugs par locale et présence de l'image hero.",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "Retourne un runbook d'exploitation en lecture seule pour un service",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "Aucun runbook trouvé.";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "Propose les premiers contrôles pour un incident de publication.",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Le piège fréquent est le nom de l’outil. Dans allowedTools, un outil MCP se nomme mcp__nomServeur__nomOutil. lookup_runbook seul ne suffit pas.

Autoriser l’édition sans tout ouvrir

Quand l’audit en lecture seule fonctionne, vous pouvez autoriser une petite correction. Faites-le avec des limites strictes. Lisez le guide officiel des permissions avant tout agent capable d’écrire ou d’exécuter des commandes.

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = [
  "Corrige une seule petite erreur TypeScript sous src.",
  "Ensuite lance npm test et rapporte le résumé du diff.",
  "Pas de grand refactor et pas de nouvelle dépendance.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

Ce modèle sert à créer un diff relisible avec preuve de test. Il ne doit pas donner à l’agent la responsabilité de push, deploy, release ou toucher des données client.

Pièges et modes d’échec

Premier piège : les anciens noms. Si un extrait utilise @anthropic-ai/claude-code ou ClaudeCodeOptions, vérifiez s’il précède la migration.

Deuxième piège : Bash trop large. Autoriser Bash sans filtre peut déclencher nettoyage, git, deploy ou installation de dépendances. Commencez par Bash(npm test).

Troisième piège : cwd implicite. Local, CI et worker peuvent démarrer dans des dossiers différents. En production, le dépôt cible doit être explicite.

Quatrième piège : traiter l’Agent SDK comme un chat SDK classique. Un agent peut lire beaucoup de fichiers et utiliser plusieurs tours. Consultez le guide officiel de cost tracking, journalisez l’usage et définissez des limites.

Cinquième piège : des outils MCP flous. Nom, description, schema et annotations doivent indiquer clairement quand l’outil s’utilise et s’il est en lecture seule.

Checklist, CTA et vérification

• Les clés API et tokens n’apparaissent pas dans les logs.
• Le premier run utilise seulement Read, Glob, Grep.
• Les agents avec écriture ont cwd, permissions et maxTurns.
• Les outils MCP séparent lecture et actions destructrices.
• Les commandes de test sont précises, pas un shell libre.
• Un humain relit le diff et les tests avant merge.

Claude Agent SDK n’est pas une invitation à tout automatiser. La vraie question est de rendre chaque automatisation vérifiable. C’est aussi crucial pour les contenus monétisés : CTA, liens produits, événements analytics et formulaires peuvent changer ensemble.

Pour commencer seul, utilisez la cheatsheet gratuite. Pour des prompts et templates réutilisables, consultez les produits. Pour un déploiement d’équipe avec permissions, MCP, CI et revue, passez par la formation et consultation Claude Code.

Pour cette mise à jour, j’ai vérifié les pages officielles overview, TypeScript reference, MCP, permissions, migration et cost tracking. Le changement le plus utile est le premier exemple en lecture seule : npm run audit permet d’observer avant d’ajouter MCP, édition et tests. C’est le même ordre que j’utiliserais sur un vrai dépôt.