1 
2Le 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.
3 
4Contrairement 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.
5 
6## Architecture
7 
8Le SDK suit une boucle simple : **collecter le contexte, agir, verifier, repeter**.
9 
10```mermaid
11graph TD
12    Input[User Prompt] --> Loop[Agent Loop]
13    Loop --> Reason[Claude Reasons]
14    Reason --> Tool[Call Tool]
15    Tool --> Result[Tool Result]
16    Result --> Loop
17    Reason --> Done[Final Response]
18 
19    subgraph "Built-in Tools"
20        T1[Read / Write / Edit]
21        T2[Bash / Terminal]
22        T3[Glob / Grep]
23        T4[WebSearch / WebFetch]
24    end
25 
26    subgraph "Custom Tools via MCP"
27        M1[Your API]
28        M2[Database]
29        M3[Slack / GitHub / etc.]
30    end
31 
32    Tool --> T1
33    Tool --> M1
34```
35 
36Le 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.
37 
38## Pour commencer
39 
40### Installation
41 
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45 
46# Python
47pip install claude-agent-sdk
48```
49 
50Vous avez besoin d'une cle API Anthropic definie comme `ANTHROPIC_API_KEY` dans votre environnement.
51 
52### Votre premier agent
53 
54```typescript
55import { query } from "@anthropic-ai/claude-agent-sdk";
56 
57const conversation = query({
58  prompt: "Find all TODO comments in the codebase and create a summary",
59  options: {
60    allowedTools: ["Read", "Glob", "Grep"],
61  },
62});
63 
64for await (const message of conversation) {
65  if (message.type === "assistant") {
66    process.stdout.write(message.content);
67  }
68  if (message.type === "result" && message.subtype === "success") {
69    console.log("\nDone:", message.result);
70  }
71}
72```
73 
74C'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.
75 
76### Equivalent Python
77 
78```python
79from claude_agent_sdk import query
80 
81async for message in query(
82    prompt="Find all TODO comments in the codebase and create a summary",
83    options={"allowed_tools": ["Read", "Glob", "Grep"]},
84):
85    if message.type == "assistant":
86        print(message.content, end="")
87    if message.type == "result" and message.subtype == "success":
88        print(f"\nDone: {message.result}")
89```
90 
91## Tools integres
92 
93Le SDK embarque les memes tools disponibles dans Claude Code :
94 
95| Tool | Description |
96|------|-------------|
97| **Read** | Lit le contenu des fichiers |
98| **Write** | Cree de nouveaux fichiers |
99| **Edit** | Effectue des modifications ciblees sur des fichiers existants |
100| **Bash** | Execute des commandes shell |
101| **Glob** | Trouve des fichiers par pattern |
102| **Grep** | Recherche dans le contenu des fichiers avec des regex |
103| **WebSearch** | Effectue des recherches sur le web |
104| **WebFetch** | Recupere une URL et renvoie son contenu |
105| **AskUserQuestion** | Demande une saisie a l'utilisateur |
106 
107Vous 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.
108 
109## Modes de permission
110 
111Les agents executant de vraies commandes sur de vrais systemes, les permissions sont importantes.
112 
113| Mode | Comportement | Cas d'usage |
114|------|----------|----------|
115| `default` | Un callback `canUseTool` personnalise decide pour chaque appel | Controle granulaire |
116| `acceptEdits` | Approuve automatiquement les operations sur les fichiers, demande confirmation pour Bash | Workflows de developpement |
117| `dontAsk` | Refuse tout ce qui n'est pas dans allowedTools | Agents restreints |
118| `bypassPermissions` | Approuve tout automatiquement | Environnements sandbox de confiance |
119| `auto` | Un classificateur du modele evalue la securite | Automatisation equilibree |
120 
121```typescript
122const conversation = query({
123  prompt: "Refactor the auth module to use JWT",
124  options: {
125    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
126    permissionMode: "acceptEdits",
127  },
128});
129```
130 
131En 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.
132 
133## Creer des tools personnalises avec MCP
134 
135La 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.
136 
137### Exemple : tool meteo
138 
139```typescript
140import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
141import { z } from "zod";
142 
143const getTemperature = tool(
144  "get_temperature",
145  "Get the current temperature at a location",
146  {
147    latitude: z.number().describe("Latitude"),
148    longitude: z.number().describe("Longitude"),
149  },
150  async ({ latitude, longitude }) => {
151    const res = await fetch(
152      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
153    );
154    const data = await res.json();
155    return {
156      content: [
157        {
158          type: "text",
159          text: `Current temperature: ${data.current.temperature_2m}C`,
160        },
161      ],
162    };
163  }
164);
165 
166const weatherServer = createSdkMcpServer({
167  name: "weather",
168  version: "1.0.0",
169  tools: [getTemperature],
170});
171 
172for await (const message of query({
173  prompt: "What's the weather like in Rome?",
174  options: {
175    mcpServers: { weather: weatherServer },
176    allowedTools: ["mcp__weather__get_temperature"],
177  },
178})) {
179  if (message.type === "result" && message.subtype === "success") {
180    console.log(message.result);
181  }
182}
183```
184 
185Les 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.
186 
187### Exemple : tool de requete base de donnees
188 
189```typescript
190const queryDb = tool(
191  "query_database",
192  "Run a read-only SQL query against the application database",
193  {
194    sql: z.string().describe("SQL SELECT query to execute"),
195  },
196  async ({ sql }) => {
197    // Validate: only allow SELECT queries
198    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
199      return {
200        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
201      };
202    }
203 
204    const result = await pool.query(sql);
205    return {
206      content: [
207        {
208          type: "text",
209          text: JSON.stringify(result.rows, null, 2),
210        },
211      ],
212    };
213  }
214);
215```
216 
217## Connecter des serveurs MCP externes
218 
219Au-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.
220 
221```typescript
222for await (const message of query({
223  prompt: "Check the latest issues in the frontend repo and summarize them",
224  options: {
225    mcpServers: {
226      github: {
227        command: "npx",
228        args: ["-y", "@modelcontextprotocol/server-github"],
229        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
230      },
231    },
232    allowedTools: ["mcp__github__*"],
233  },
234})) {
235  // ...
236}
237```
238 
239Vous pouvez combiner plusieurs serveurs MCP. L'agent voit tous les tools de tous les serveurs connectes et les utilise selon les besoins.
240 
241```mermaid
242graph LR
243    Agent[Your Agent] --> SDK[Agent SDK]
244    SDK --> InProcess[In-process MCP\nCustom Tools]
245    SDK --> GitHub[GitHub MCP Server]
246    SDK --> Postgres[PostgreSQL MCP Server]
247    SDK --> Slack[Slack MCP Server]
248```
249 
250## Orchestration multi-agents
251 
252Pour 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.
253 
254```typescript
255for await (const message of query({
256  prompt: "Review the PR, check for security issues, and update the changelog",
257  options: {
258    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
259    agents: [
260      {
261        name: "security-reviewer",
262        description: "Reviews code for security vulnerabilities",
263        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
264        allowedTools: ["Read", "Glob", "Grep"],
265      },
266      {
267        name: "changelog-writer",
268        description: "Updates the CHANGELOG.md file based on recent changes",
269        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
270        allowedTools: ["Read", "Edit", "Bash"],
271      },
272    ],
273  },
274})) {
275  // The parent agent will:
276  // 1. Read the PR diff
277  // 2. Delegate security review to security-reviewer
278  // 3. Delegate changelog update to changelog-writer
279  // 4. Synthesize results
280}
281```
282 
283Incluez `"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.
284 
285```mermaid
286graph TD
287    Parent[Parent Agent] --> SR[Security Reviewer\nRead, Glob, Grep]
288    Parent --> CW[Changelog Writer\nRead, Edit, Bash]
289    SR --> Report[Security Report]
290    CW --> Updated[Updated CHANGELOG]
291    Report --> Parent
292    Updated --> Parent
293    Parent --> Final[Final Summary]
294```
295 
296## Sessions et continuite
297 
298Les 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.
299 
300```typescript
301let sessionId: string | undefined;
302 
303// First query
304for await (const message of query({
305  prompt: "Read the project structure and understand the architecture",
306  options: { allowedTools: ["Read", "Glob", "Grep"] },
307})) {
308  if (message.type === "init") {
309    sessionId = message.session_id;
310  }
311}
312 
313// Follow-up query (same session, full context preserved)
314for await (const message of query({
315  prompt: "Now refactor the auth module based on what you learned",
316  resume: sessionId,
317  options: { allowedTools: ["Read", "Edit", "Bash"] },
318})) {
319  // Agent remembers the full project context from the first query
320}
321```
322 
323## Claude Managed Agents
324 
325Si 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.
326 
327```mermaid
328graph LR
329    subgraph "Self-hosted (Agent SDK)"
330        Code[Your Code] --> SDK2[Agent SDK]
331        SDK2 --> API[Claude API]
332        SDK2 --> Tools[Your Tools]
333    end
334 
335    subgraph "Managed Agents"
336        App[Your App] --> MAPI[Managed Agents API]
337        MAPI --> Container[Anthropic-hosted Container]
338        Container --> API2[Claude API]
339        Container --> Tools2[Tools in Container]
340    end
341```
342 
343La 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.
344 
345**Tarifs :**
346- **Agent SDK** : uniquement les tarifs standard par token de l'API Claude. L'hebergement est a votre charge.
347- **Managed Agents** : tarifs par token plus 0,08 $ par heure de session (facturation a la milliseconde).
348 
349## Bonnes pratiques pour la production
350 
351### 1. Toujours sandboxer
352 
353N'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).
354 
355### 2. Limiter l'acces aux tools
356 
357Suivez le principe du moindre privilege. Un agent qui genere des rapports n'a pas besoin de `Bash` ou `Write`.
358 
359```typescript
360// Too permissive
361allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
362 
363// Better: only what's needed
364allowedTools: ["Read", "Glob", "Grep"]
365```
366 
367### 3. Utiliser les hooks comme guardrails
368 
369Les 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.
370 
371```typescript
372const conversation = query({
373  prompt: "Analyze the codebase",
374  options: {
375    allowedTools: ["Read", "Glob", "Grep"],
376    hooks: {
377      PreToolUse: async (toolName, input) => {
378        console.log(`Tool call: ${toolName}`, input);
379        // Return false to block the call
380        if (toolName === "Bash" && input.command.includes("rm")) {
381          return false;
382        }
383        return true;
384      },
385    },
386  },
387});
388```
389 
390### 4. Gerer les erreurs correctement
391 
392L'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.
393 
394```typescript
395for await (const message of conversation) {
396  switch (message.type) {
397    case "assistant":
398      // Agent reasoning
399      break;
400    case "tool_use":
401      // Agent is calling a tool
402      break;
403    case "result":
404      if (message.subtype === "error") {
405        console.error("Agent failed:", message.error);
406      }
407      break;
408  }
409}
410```
411 
412### 5. Surveiller la consommation de tokens
413 
414Les 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.
415 
416## Conclusion
417 
418Le 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.
419 
420Commencez 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.
421 
422L'agent loop est le meme que celui qui fait tourner Claude Code. S'il peut creer du logiciel, vos agents le peuvent aussi.
423 
424> **Checklist pour demarrer :**
425>
426> - [x] Installer le SDK (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Definir `ANTHROPIC_API_KEY` dans votre environnement
428> - [x] Creer un agent simple avec les tools integres (Read, Glob, Grep)
429> - [x] Ajouter un tool personnalise via un serveur MCP in-process
430> - [x] Connecter un serveur MCP externe (GitHub, PostgreSQL, etc.)
431> - [x] Implementer l'orchestration multi-agents avec des sous-agents
432> - [x] Mettre en place un environnement sandbox pour la production
433> - [x] Ajouter des hooks pour le logging et les guardrails
434