Creer des agents IA avec le Claude Agent SDK : guide pratique

Le Claude Agent SDK vous donne un acces programmatique au meme agent loop qui fait tourner Claude Code. Vos agents peuvent lire des fichiers, executer des commandes shell, effectuer des recherches web, modifier du code, appeler des API externes via des serveurs MCP et orchestrer des sous-agents - le tout en quelques lignes de TypeScript ou Python.

Contrairement au Client SDK standard d'Anthropic ou vous construisez votre propre tool loop, l'Agent SDK gere l'execution des tools, la gestion du contexte, les retries et l'orchestration en interne. Vous decrivez ce que vous voulez, fournissez les outils, et l'agent se charge du reste.

Architecture

Le SDK suit une boucle simple : collecter le contexte, agir, verifier, repeter.

Le point d'entree principal est query(), qui renvoie un iterateur asynchrone diffusant des messages en streaming pendant que l'agent travaille. Chaque message vous indique ce que fait l'agent : raisonnement, appel d'un tool, reception d'un resultat ou livraison de la sortie finale.

Pour commencer

Installation

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Vous avez besoin d'une cle API Anthropic definie comme ANTHROPIC_API_KEY dans votre environnement.

Votre premier agent

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

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

C'est tout. L'agent utilisera Glob pour trouver les fichiers, Grep pour rechercher les patterns TODO, Read pour inspecter les correspondances, et renverra un resume structure. Vous n'ecrivez pas la logique d'orchestration - le SDK s'en charge.

Equivalent Python

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

Tools integres

Le SDK embarque les memes tools disponibles dans Claude Code :

Vous controlez quels tools l'agent peut utiliser via allowedTools. Si un tool ne figure pas dans la liste, l'agent ne peut pas l'appeler.

Modes de permission

Les agents executant de vraies commandes sur de vrais systemes, les permissions sont importantes.

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

En production, executez toujours les agents dans des environnements sandbox (containers, VM) et utilisez le mode de permission le plus restrictif qui permette encore a l'agent de faire son travail.

Creer des tools personnalises avec MCP

La vraie puissance du SDK reside dans l'extension des agents avec vos propres outils. Les tools personnalises sont definis comme des serveurs MCP in-process - pas de gestion de sous-processus, pas de surcharge reseau.

Exemple : tool meteo

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

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Les tools personnalises suivent la convention de nommage mcp__{nom_serveur}__{nom_tool}. Vous pouvez utiliser des caracteres generiques dans allowedTools : "mcp__weather__*" autorise tous les tools du serveur meteo.

Exemple : tool de requete base de donnees

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

Connecter des serveurs MCP externes

Au-dela des tools in-process, vous pouvez vous connecter a n'importe quel serveur MCP existant - les memes serveurs qui fonctionnent avec Claude Desktop, Cursor et d'autres clients MCP.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

Vous pouvez combiner plusieurs serveurs MCP. L'agent voit tous les tools de tous les serveurs connectes et les utilise selon les besoins.

Orchestration multi-agents

Pour les workflows complexes, vous pouvez definir des sous-agents specialises auxquels l'agent principal delegue. Chaque sous-agent a son propre prompt, ses propres tools et son domaine de competence.

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

Incluez "Agent" dans les allowedTools du parent pour activer la delegation. Les sous-agents s'executent avec leurs propres tools et ne peuvent pas acceder a ceux du parent sauf autorisation explicite.

Sessions et continuite

Les agents peuvent maintenir le contexte entre plusieurs requetes grace aux sessions. Capturez le session_id de la premiere interaction et transmettez-le dans resume pour les requetes suivantes.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

Si vous ne souhaitez pas heberger vous-meme l'infrastructure des agents, les Claude Managed Agents (lances en avril 2026) fournissent un service cloud entierement gere. Anthropic s'occupe des containers, du scaling et met a disposition une API en streaming.

La difference essentielle : avec l'Agent SDK, vous executez l'agent loop dans votre propre infrastructure. Avec les Managed Agents, Anthropic heberge et fait tourner l'agent pour vous. Vous interagissez via une API basee sur des sessions et recevez des evenements via Server-Sent Events.

Tarifs :

• Agent SDK : uniquement les tarifs standard par token de l'API Claude. L'hebergement est a votre charge.
• Managed Agents : tarifs par token plus 0,08 $ par heure de session (facturation a la milliseconde).

Bonnes pratiques pour la production

1. Toujours sandboxer

N'executez jamais des agents avec des permissions illimitees sur une machine de production. Utilisez des containers (Docker, Fly.io, Modal) ou des environnements sandbox (E2B, Vercel Sandbox).

2. Limiter l'acces aux tools

Suivez le principe du moindre privilege. Un agent qui genere des rapports n'a pas besoin de Bash ou Write.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. Utiliser les hooks comme guardrails

Les hooks vous permettent d'intercepter les appels aux tools avant et apres l'execution. Utilisez-les pour le logging, la validation et le rate limiting.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. Gerer les erreurs correctement

L'agent loop peut produire des erreurs - echecs des tools, limites de debit de l'API, depassement de la fenetre de contexte. Verifiez toujours les types de messages.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. Surveiller la consommation de tokens

Les agent loops peuvent consommer une quantite importante de tokens, surtout avec de grandes codebases. Le SDK inclut la compaction automatique du contexte, mais vous devriez tout de meme surveiller la consommation.

Conclusion

Le Claude Agent SDK transforme un LLM d'une machine a repondre aux questions en quelque chose de plus proche d'un developpeur junior. Vos agents peuvent lire, ecrire, executer, verifier et iterer - le meme workflow qu'un humain suit.

Commencez petit : construisez un agent avec quelques tools integres. Ajoutez ensuite des tools MCP personnalises pour votre domaine specifique. Passez a l'orchestration multi-agents quand vos workflows necessitent de la specialisation.

L'agent loop est le meme que celui qui fait tourner Claude Code. S'il peut creer du logiciel, vos agents le peuvent aussi.

Checklist pour demarrer :

• Installer le SDK (npm install @anthropic-ai/claude-agent-sdk)
• Definir ANTHROPIC_API_KEY dans votre environnement
• Creer un agent simple avec les tools integres (Read, Glob, Grep)
• Ajouter un tool personnalise via un serveur MCP in-process
• Connecter un serveur MCP externe (GitHub, PostgreSQL, etc.)
• Implementer l'orchestration multi-agents avec des sous-agents
• Mettre en place un environnement sandbox pour la production
• Ajouter des hooks pour le logging et les guardrails