Construire des agents IA production-ready avec le Claude Agent SDK et TypeScript

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

npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext --outDir dist

{
  "type": "module",
  "scripts": {
    "start": "tsx src/index.ts",
    "build": "tsc"
  }
}

mkdir src

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function main() {
  console.log("Démarrage de l'agent...\n");
 
  for await (const message of query({
    prompt: "Quels fichiers sont dans ce répertoire ? Donne-moi un résumé de la structure du projet.",
    options: {
      allowedTools: ["Bash", "Glob", "Read"],
      maxTurns: 10,
    },
  })) {
    // Gérer les différents types de messages
    if ("result" in message) {
      console.log("\n--- Résultat de l'agent ---");
      console.log(message.result);
    }
  }
}
 
main().catch(console.error);

npx tsx src/index.ts

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function main() {
  for await (const message of query({
    prompt: "Trouve tous les fichiers TypeScript et compte le total de lignes de code.",
    options: {
      allowedTools: ["Bash", "Glob", "Read"],
      maxTurns: 15,
    },
  })) {
    switch (message.type) {
      case "assistant":
        // Texte de raisonnement ou réponse de Claude
        const textBlocks = message.message.content
          .filter((block: { type: string }) => block.type === "text")
          .map((block: { type: string; text: string }) => block.text);
        if (textBlocks.length > 0) {
          console.log("[Claude]", textBlocks.join(""));
        }
        break;
 
      case "tool_use":
        // Claude appelle un outil
        console.log(`[Appel outil] ${message.name}(${JSON.stringify(message.input).slice(0, 100)}...)`);
        break;
 
      case "tool_result":
        // Résultat d'exécution d'un outil
        console.log(`[Résultat outil] ${message.content?.slice(0, 200)}...`);
        break;
 
      case "result":
        if (message.subtype === "success") {
          console.log("\n✓ Agent terminé avec succès");
          console.log(message.result);
        } else {
          console.error("\n✗ Échec de l'agent :", message.error);
        }
        break;
    }
  }
}
 
main().catch(console.error);

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function refactorAgent(targetFile: string, instruction: string) {
  for await (const message of query({
    prompt: `Refactorise le fichier ${targetFile} : ${instruction}`,
    options: {
      allowedTools: ["Read", "Edit", "Glob", "Grep"],
      permissionMode: "acceptEdits", // Auto-approuver les modifications de fichiers
      maxTurns: 20,
    },
  })) {
    if ("result" in message) {
      return message.result;
    }
  }
}
 
// Utilisation
const result = await refactorAgent(
  "src/utils.ts",
  "Extrais toutes les fonctions helpers dans des modules séparés selon leur domaine"
);
console.log(result);

import { query } from "@anthropic-ai/claude-agent-sdk";
import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk/mcp";
 
// Définir des outils personnalisés
const analyticsServer = createSdkMcpServer({
  name: "analytics",
  version: "1.0.0",
  tools: [
    tool(
      "get_page_views",
      "Obtenir les analytics de pages vues pour un chemin URL et une plage de dates",
      {
        type: "object",
        properties: {
          path: { type: "string", description: "Chemin URL (ex: /blog/my-post)" },
          startDate: { type: "string", description: "Date de début (YYYY-MM-DD)" },
          endDate: { type: "string", description: "Date de fin (YYYY-MM-DD)" },
        },
        required: ["path", "startDate", "endDate"],
      },
      async ({ path, startDate, endDate }) => {
        // Votre véritable appel API analytics ici
        const response = await fetch(
          `https://api.analytics.example.com/views?path=${path}&start=${startDate}&end=${endDate}`
        );
        const data = await response.json();
        return JSON.stringify(data);
      }
    ),
    tool(
      "get_top_pages",
      "Obtenir les N pages les plus visitées",
      {
        type: "object",
        properties: {
          limit: { type: "number", description: "Nombre de pages à retourner" },
          period: { type: "string", enum: ["day", "week", "month"], description: "Période" },
        },
        required: ["limit", "period"],
      },
      async ({ limit, period }) => {
        const response = await fetch(
          `https://api.analytics.example.com/top?limit=${limit}&period=${period}`
        );
        const data = await response.json();
        return JSON.stringify(data);
      }
    ),
  ],
});
 
// Utilisation avec entrée streaming (requis pour les serveurs MCP)
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Quelles sont les 10 pages les plus visitées ce mois-ci ? Puis analyse la tendance de la page #1 sur les 30 derniers jours.",
    },
  };
}
 
for await (const message of query({
  prompt: generateMessages(),
  options: {
    mcpServers: {
      analytics: analyticsServer,
    },
    allowedTools: [
      "mcp__analytics__get_page_views",
      "mcp__analytics__get_top_pages",
    ],
    maxTurns: 10,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Liste les issues ouvertes labellisées 'bug' et résume les plus critiques.",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
        },
      },
    },
    allowedTools: ["mcp__github__*"], // Wildcard : autoriser tous les outils GitHub
    maxTurns: 15,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

options: {
  mcpServers: {
    "remote-api": {
      type: "sse",
      url: "https://mcp.example.com/sse",
      headers: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
      },
    },
  },
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
const CODE_REVIEW_PROMPT = `Vous êtes un revieweur de code expert spécialisé en TypeScript et React.
 
Votre processus de review :
1. Lire les fichiers modifiés
2. Vérifier les bugs, problèmes de sécurité et de performance
3. Vérifier que les types TypeScript sont corrects et complets
4. S'assurer des bonnes pratiques React (règles des hooks, props key, usage de memo)
5. Fournir une review structurée avec niveaux de sévérité
 
Format de sortie :
- 🔴 Critique : Doit être corrigé avant le merge
- 🟡 Avertissement : Devrait être corrigé, mais non bloquant
- 🟢 Suggestion : Améliorations appréciables
 
Soyez spécifique. Référencez les numéros de ligne. Suggérez des corrections avec du code.`;
 
async function reviewCode(diffOrPath: string) {
  for await (const message of query({
    prompt: `Reviewez ce code :\n\n${diffOrPath}`,
    options: {
      systemPrompt: CODE_REVIEW_PROMPT,
      allowedTools: ["Read", "Glob", "Grep"],
      maxTurns: 25,
    },
  })) {
    if ("result" in message) {
      return message.result;
    }
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Analyse la couverture de tests de ce projet, puis écris des tests pour toute fonction non couverte dans src/utils/.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Task"],
    agents: {
      "test-analyzer": {
        description: "Analyse la couverture de tests et identifie les chemins de code non testés",
        tools: ["Bash", "Read", "Glob", "Grep"],
        prompt: "Vous êtes un analyste de couverture de tests. Exécutez les outils de couverture, analysez les rapports et identifiez les fonctions non testées.",
        model: "haiku", // Utiliser un modèle plus rapide pour l'analyse
      },
      "test-writer": {
        description: "Écrit des tests unitaires complets pour les fonctions TypeScript",
        tools: ["Read", "Write", "Edit", "Glob"],
        prompt: "Vous êtes un ingénieur de tests. Écrivez des tests unitaires complets avec Vitest incluant le mocking approprié et la couverture des cas limites.",
        model: "sonnet",
      },
    },
    maxTurns: 30,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Migre tous les fichiers JavaScript vers TypeScript avec des types appropriés.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"],
 
    // Limites de tours
    maxTurns: 50,           // Maximum d'appels d'outils avant arrêt
 
    // Contrôles de coût
    maxBudgetUsd: 2.0,      // Arrêter si le coût dépasse $2.00
 
    // Sélection du modèle
    model: "claude-sonnet-4-5-20250929",  // Utiliser un modèle spécifique
 
    // Restrictions d'outils
    disallowedTools: ["WebSearch", "WebFetch"],  // Bloquer des outils spécifiques
 
    // Répertoire de travail
    cwd: "/path/to/project",
 
    // Variables d'environnement disponibles pour l'outil Bash
    env: {
      NODE_ENV: "development",
      DATABASE_URL: process.env.DATABASE_URL!,
    },
 
    // Mode de permissions
    permissionMode: "acceptEdits",
  },
})) {
  // Traiter les messages
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Nettoie et optimise la codebase.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
    canUseTool: async (toolName, input) => {
      // Bloquer les commandes bash destructives
      if (toolName === "Bash") {
        const command = (input as { command: string }).command;
        const dangerous = ["rm -rf", "DROP TABLE", "git push --force"];
        if (dangerous.some((d) => command.includes(d))) {
          return { allowed: false, reason: "Les commandes destructives ne sont pas autorisées" };
        }
      }
 
      // Bloquer l'écriture dans les fichiers critiques
      if (toolName === "Write" || toolName === "Edit") {
        const filePath = (input as { file_path: string }).file_path;
        const protected_paths = [".env", "package-lock.json", "prisma/schema.prisma"];
        if (protected_paths.some((p) => filePath.includes(p))) {
          return { allowed: false, reason: `Impossible de modifier le fichier protégé : ${filePath}` };
        }
      }
 
      return { allowed: true };
    },
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

// src/review-bot.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
 
interface ReviewResult {
  summary: string;
  issues: Array<{
    severity: "critical" | "warning" | "suggestion";
    file: string;
    line?: number;
    message: string;
    suggestion?: string;
  }>;
  score: number;
}
 
const REVIEW_SYSTEM_PROMPT = `Vous êtes un expert en review de code. Analysez les diffs git et fournissez des retours structurés.
 
Règles :
- Concentrez-vous sur les bugs, vulnérabilités de sécurité et problèmes de performance
- Vérifiez la sûreté des types TypeScript
- Vérifiez que la gestion d'erreurs est complète
- Cherchez les conditions de course potentielles dans le code async
- Ne suggérez des améliorations que quand elles apportent une valeur claire
 
Terminez toujours votre review avec un bloc JSON dans ce format exact :
\`\`\`json
{
  "summary": "Résumé en un paragraphe",
  "issues": [
    {
      "severity": "critical|warning|suggestion",
      "file": "path/to/file.ts",
      "line": 42,
      "message": "Description du problème",
      "suggestion": "Comment le corriger"
    }
  ],
  "score": 85
}
\`\`\`
 
Score : 0-100 où 100 est un code parfait.`;
 
async function reviewPullRequest(baseBranch: string = "main"): Promise<ReviewResult | null> {
  let result: string | null = null;
 
  for await (const message of query({
    prompt: `Reviewez le diff git actuel par rapport à ${baseBranch}.
Lisez les fichiers modifiés pour le contexte complet, puis fournissez une review de code structurée.`,
    options: {
      systemPrompt: REVIEW_SYSTEM_PROMPT,
      allowedTools: ["Bash", "Read", "Glob", "Grep"],
      maxTurns: 30,
      maxBudgetUsd: 1.0,
      permissionMode: "acceptEdits",
    },
  })) {
    if ("result" in message && message.subtype === "success") {
      result = message.result;
    }
  }
 
  if (!result) return null;
 
  // Extraire le JSON du résultat
  const jsonMatch = result.match(/```json\n([\s\S]*?)\n```/);
  if (jsonMatch) {
    return JSON.parse(jsonMatch[1]) as ReviewResult;
  }
 
  return null;
}
 
// Lancer la review
async function main() {
  console.log("Démarrage de la review de code...\n");
 
  const review = await reviewPullRequest();
 
  if (review) {
    console.log(`\nScore de review : ${review.score}/100`);
    console.log(`Résumé : ${review.summary}\n`);
 
    for (const issue of review.issues) {
      const icon =
        issue.severity === "critical" ? "🔴" :
        issue.severity === "warning" ? "🟡" : "🟢";
      console.log(`${icon} [${issue.file}${issue.line ? `:${issue.line}` : ""}] ${issue.message}`);
      if (issue.suggestion) {
        console.log(`   Correction : ${issue.suggestion}`);
      }
    }
  }
}
 
main().catch(console.error);

npx tsx src/review-bot.ts

import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";
 
async function interactiveSession() {
  await using session = unstable_v2_createSession({
    model: "claude-sonnet-4-5-20250929",
  });
 
  // Premier tour
  await session.send("Bonjour ! Dans quel projet TypeScript suis-je ?");
  for await (const msg of session.stream()) {
    if (msg.type === "assistant") {
      const text = msg.message.content
        .filter((block: { type: string }) => block.type === "text")
        .map((block: { type: string; text: string }) => block.text)
        .join("");
      console.log(text);
    }
  }
 
  // Deuxième tour — la session se souvient du contexte
  await session.send("Maintenant liste les dépendances principales du package.json");
  for await (const msg of session.stream()) {
    if (msg.type === "assistant") {
      const text = msg.message.content
        .filter((block: { type: string }) => block.type === "text")
        .map((block: { type: string; text: string }) => block.text)
        .join("");
      console.log(text);
    }
  }
}
 
interactiveSession().catch(console.error);

// src/test-agent.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function testAgent() {
  const tests = [
    {
      name: "Liste de fichiers basique",
      prompt: "Liste les fichiers dans le répertoire courant",
      tools: ["Glob"],
      expectResult: true,
    },
    {
      name: "Analyse de code",
      prompt: "Lis package.json et dis-moi le nom du projet",
      tools: ["Read"],
      expectResult: true,
    },
  ];
 
  for (const test of tests) {
    console.log(`\nTest : ${test.name}`);
    let gotResult = false;
 
    for await (const message of query({
      prompt: test.prompt,
      options: {
        allowedTools: test.tools,
        maxTurns: 5,
      },
    })) {
      if ("result" in message) {
        gotResult = true;
        console.log(`  ✓ Résultat : ${message.result.slice(0, 100)}...`);
      }
    }
 
    if (gotResult === test.expectResult) {
      console.log(`  ✓ RÉUSSI`);
    } else {
      console.log(`  ✗ ÉCHOUÉ`);
    }
  }
}
 
testAgent().catch(console.error);

npm install -g @anthropic-ai/claude-code
claude --version  # Vérifier l'installation

// Assurez-vous que les outils nécessaires sont dans la liste autorisée
options: {
  allowedTools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"],
  permissionMode: "acceptEdits",
}

options: {
  maxTurns: 20,        // Arrêter après 20 appels d'outils
  maxBudgetUsd: 0.50,  // Arrêter si le coût dépasse $0.50
}

# Tester le serveur MCP directement
npx -y @modelcontextprotocol/server-github