1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Référence du SDK Agent - Python
6
7> Référence API complète du SDK Agent Python, incluant toutes les fonctions, types et classes.
8
9## Installation
10
11```bash theme={null}
12pip install claude-agent-sdk
13```
14
15## Choisir entre `query()` et `ClaudeSDKClient`
16
17Le SDK Python offre deux façons d'interagir avec Claude Code :
18
19### Comparaison rapide
20
21| Fonctionnalité | `query()` | `ClaudeSDKClient` |
22| :---------------------------- | :-------------------------------------- | :--------------------------------------- |
23| **Session** | Crée une nouvelle session à chaque fois | Réutilise la même session |
24| **Conversation** | Échange unique | Plusieurs échanges dans le même contexte |
25| **Connexion** | Gérée automatiquement | Contrôle manuel |
26| **Entrée en streaming** | ✅ Supportée | ✅ Supportée |
27| **Interruptions** | ❌ Non supportées | ✅ Supportées |
28| **Hooks** | ✅ Supportés | ✅ Supportés |
29| **Outils personnalisés** | ✅ Supportés | ✅ Supportés |
30| **Continuer la conversation** | ❌ Nouvelle session à chaque fois | ✅ Maintient la conversation |
31| **Cas d'usage** | Tâches ponctuelles | Conversations continues |
32
33### Quand utiliser `query()` (nouvelle session à chaque fois)
34
35**Idéal pour :**
36
37* Les questions ponctuelles où vous n'avez pas besoin d'historique de conversation
38* Les tâches indépendantes qui ne nécessitent pas de contexte des échanges précédents
39* Les scripts d'automatisation simples
40* Quand vous voulez un nouveau départ à chaque fois
41
42### Quand utiliser `ClaudeSDKClient` (conversation continue)
43
44**Idéal pour :**
45
46* **Continuer les conversations** - Quand vous avez besoin que Claude se souvienne du contexte
47* **Questions de suivi** - S'appuyer sur les réponses précédentes
48* **Applications interactives** - Interfaces de chat, REPLs
49* **Logique basée sur les réponses** - Quand l'action suivante dépend de la réponse de Claude
50* **Contrôle de session** - Gérer explicitement le cycle de vie de la conversation
51
52## Fonctions
53
54### `query()`
55
56Crée une nouvelle session pour chaque interaction avec Claude Code. Retourne un itérateur asynchrone qui produit les messages au fur et à mesure qu'ils arrivent. Chaque appel à `query()` recommence à zéro sans mémoire des interactions précédentes.
57
58```python theme={null}
59async def query(
60 *,
61 prompt: str | AsyncIterable[dict[str, Any]],
62 options: ClaudeAgentOptions | None = None,
63 transport: Transport | None = None
64) -> AsyncIterator[Message]
65```
66
67#### Paramètres
68
69| Paramètre | Type | Description |
70| :---------- | :--------------------------- | :-------------------------------------------------------------------------------------- |
71| `prompt` | `str \| AsyncIterable[dict]` | Le prompt d'entrée sous forme de chaîne ou d'itérable asynchrone pour le mode streaming |
72| `options` | `ClaudeAgentOptions \| None` | Objet de configuration optionnel (par défaut `ClaudeAgentOptions()` si None) |
73| `transport` | `Transport \| None` | Transport personnalisé optionnel pour communiquer avec le processus CLI |
74
75#### Retours
76
77Retourne un `AsyncIterator[Message]` qui produit les messages de la conversation.
78
79#### Exemple - Avec options
80
81```python theme={null}
82import asyncio
83from claude_agent_sdk import query, ClaudeAgentOptions
84
85
86async def main():
87 options = ClaudeAgentOptions(
88 system_prompt="You are an expert Python developer",
89 permission_mode="acceptEdits",
90 cwd="/home/user/project",
91 )
92
93 async for message in query(prompt="Create a Python web server", options=options):
94 print(message)
95
96
97asyncio.run(main())
98```
99
100### `tool()`
101
102Décorateur pour définir des outils MCP avec sécurité des types.
103
104```python theme={null}
105def tool(
106 name: str,
107 description: str,
108 input_schema: type | dict[str, Any],
109 annotations: ToolAnnotations | None = None
110) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]
111```
112
113#### Paramètres
114
115| Paramètre | Type | Description |
116| :------------- | :----------------------------------------------- | :------------------------------------------------------------------------------- |
117| `name` | `str` | Identifiant unique pour l'outil |
118| `description` | `str` | Description lisible de ce que fait l'outil |
119| `input_schema` | `type \| dict[str, Any]` | Schéma définissant les paramètres d'entrée de l'outil (voir ci-dessous) |
120| `annotations` | [`ToolAnnotations`](#tool-annotations)` \| None` | Annotations MCP optionnelles fournissant des indices comportementaux aux clients |
121
122#### Options de schéma d'entrée
123
1241. **Mappage de type simple** (recommandé) :
125
126 ```python theme={null}
127 {"text": str, "count": int, "enabled": bool}
128 ```
129
1302. **Format JSON Schema** (pour la validation complexe) :
131 ```python theme={null}
132 {
133 "type": "object",
134 "properties": {
135 "text": {"type": "string"},
136 "count": {"type": "integer", "minimum": 0},
137 },
138 "required": ["text"],
139 }
140 ```
141
142#### Retours
143
144Une fonction décorateur qui enveloppe l'implémentation de l'outil et retourne une instance `SdkMcpTool`.
145
146#### Exemple
147
148```python theme={null}
149from claude_agent_sdk import tool
150from typing import Any
151
152
153@tool("greet", "Greet a user", {"name": str})
154async def greet(args: dict[str, Any]) -> dict[str, Any]:
155 return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
156```
157
158#### `ToolAnnotations`
159
160Réexportée depuis `mcp.types` (également disponible via `from claude_agent_sdk import ToolAnnotations`). Tous les champs sont des indices optionnels ; les clients ne doivent pas s'y fier pour les décisions de sécurité.
161
162| Champ | Type | Par défaut | Description |
163| :---------------- | :------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
164| `title` | `str \| None` | `None` | Titre lisible pour l'outil |
165| `readOnlyHint` | `bool \| None` | `False` | Si `True`, l'outil ne modifie pas son environnement |
166| `destructiveHint` | `bool \| None` | `True` | Si `True`, l'outil peut effectuer des mises à jour destructrices (uniquement significatif quand `readOnlyHint` est `False`) |
167| `idempotentHint` | `bool \| None` | `False` | Si `True`, les appels répétés avec les mêmes arguments n'ont pas d'effet supplémentaire (uniquement significatif quand `readOnlyHint` est `False`) |
168| `openWorldHint` | `bool \| None` | `True` | Si `True`, l'outil interagit avec des entités externes (par exemple, recherche web). Si `False`, le domaine de l'outil est fermé (par exemple, un outil de mémoire) |
169
170```python theme={null}
171from claude_agent_sdk import tool, ToolAnnotations
172from typing import Any
173
174
175@tool(
176 "search",
177 "Search the web",
178 {"query": str},
179 annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
180)
181async def search(args: dict[str, Any]) -> dict[str, Any]:
182 return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}
183```
184
185### `create_sdk_mcp_server()`
186
187Crée un serveur MCP en processus qui s'exécute dans votre application Python.
188
189```python theme={null}
190def create_sdk_mcp_server(
191 name: str,
192 version: str = "1.0.0",
193 tools: list[SdkMcpTool[Any]] | None = None
194) -> McpSdkServerConfig
195```
196
197#### Paramètres
198
199| Paramètre | Type | Par défaut | Description |
200| :-------- | :------------------------------ | :--------- | :------------------------------------------------------------ |
201| `name` | `str` | - | Identifiant unique pour le serveur |
202| `version` | `str` | `"1.0.0"` | Chaîne de version du serveur |
203| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | Liste des fonctions d'outil créées avec le décorateur `@tool` |
204
205#### Retours
206
207Retourne un objet `McpSdkServerConfig` qui peut être passé à `ClaudeAgentOptions.mcp_servers`.
208
209#### Exemple
210
211```python theme={null}
212from claude_agent_sdk import tool, create_sdk_mcp_server
213
214
215@tool("add", "Add two numbers", {"a": float, "b": float})
216async def add(args):
217 return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}
218
219
220@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
221async def multiply(args):
222 return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}
223
224
225calculator = create_sdk_mcp_server(
226 name="calculator",
227 version="2.0.0",
228 tools=[add, multiply], # Pass decorated functions
229)
230
231# Use with Claude
232options = ClaudeAgentOptions(
233 mcp_servers={"calc": calculator},
234 allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
235)
236```
237
238### `list_sessions()`
239
240Liste les sessions passées avec métadonnées. Filtrez par répertoire de projet ou listez les sessions dans tous les projets. Synchrone ; retourne immédiatement.
241
242```python theme={null}
243def list_sessions(
244 directory: str | None = None,
245 limit: int | None = None,
246 include_worktrees: bool = True
247) -> list[SDKSessionInfo]
248```
249
250#### Paramètres
251
252| Paramètre | Type | Par défaut | Description |
253| :------------------ | :------------ | :--------- | :---------------------------------------------------------------------------------------------------- |
254| `directory` | `str \| None` | `None` | Répertoire pour lequel lister les sessions. Quand omis, retourne les sessions dans tous les projets |
255| `limit` | `int \| None` | `None` | Nombre maximum de sessions à retourner |
256| `include_worktrees` | `bool` | `True` | Quand `directory` est à l'intérieur d'un dépôt git, inclure les sessions de tous les chemins worktree |
257
258#### Type de retour : `SDKSessionInfo`
259
260| Propriété | Type | Description |
261| :-------------- | :------------ | :--------------------------------------------------------------------------------------- |
262| `session_id` | `str` | Identifiant de session unique |
263| `summary` | `str` | Titre d'affichage : titre personnalisé, résumé généré automatiquement, ou premier prompt |
264| `last_modified` | `int` | Heure de dernière modification en millisecondes depuis l'époque |
265| `file_size` | `int \| None` | Taille du fichier de session en octets (`None` pour les backends de stockage distant) |
266| `custom_title` | `str \| None` | Titre de session défini par l'utilisateur |
267| `first_prompt` | `str \| None` | Premier prompt utilisateur significatif dans la session |
268| `git_branch` | `str \| None` | Branche git à la fin de la session |
269| `cwd` | `str \| None` | Répertoire de travail pour la session |
270| `tag` | `str \| None` | Étiquette de session définie par l'utilisateur (voir [`tag_session()`](#tag-session)) |
271| `created_at` | `int \| None` | Heure de création de la session en millisecondes depuis l'époque |
272
273#### Exemple
274
275Affiche les 10 sessions les plus récentes pour un projet. Les résultats sont triés par `last_modified` décroissant, donc le premier élément est le plus récent. Omettez `directory` pour rechercher dans tous les projets.
276
277```python theme={null}
278from claude_agent_sdk import list_sessions
279
280for session in list_sessions(directory="/path/to/project", limit=10):
281 print(f"{session.summary} ({session.session_id})")
282```
283
284### `get_session_messages()`
285
286Récupère les messages d'une session passée. Synchrone ; retourne immédiatement.
287
288```python theme={null}
289def get_session_messages(
290 session_id: str,
291 directory: str | None = None,
292 limit: int | None = None,
293 offset: int = 0
294) -> list[SessionMessage]
295```
296
297#### Paramètres
298
299| Paramètre | Type | Par défaut | Description |
300| :----------- | :------------ | :--------- | :--------------------------------------------------------------------------- |
301| `session_id` | `str` | requis | L'ID de session pour lequel récupérer les messages |
302| `directory` | `str \| None` | `None` | Répertoire de projet à regarder. Quand omis, recherche dans tous les projets |
303| `limit` | `int \| None` | `None` | Nombre maximum de messages à retourner |
304| `offset` | `int` | `0` | Nombre de messages à ignorer depuis le début |
305
306#### Type de retour : `SessionMessage`
307
308| Propriété | Type | Description |
309| :------------------- | :----------------------------- | :---------------------------- |
310| `type` | `Literal["user", "assistant"]` | Rôle du message |
311| `uuid` | `str` | Identifiant de message unique |
312| `session_id` | `str` | Identifiant de session |
313| `message` | `Any` | Contenu du message brut |
314| `parent_tool_use_id` | `None` | Réservé pour un usage futur |
315
316#### Exemple
317
318```python theme={null}
319from claude_agent_sdk import list_sessions, get_session_messages
320
321sessions = list_sessions(limit=1)
322if sessions:
323 messages = get_session_messages(sessions[0].session_id)
324 for msg in messages:
325 print(f"[{msg.type}] {msg.uuid}")
326```
327
328### `get_session_info()`
329
330Lit les métadonnées d'une seule session par ID sans scanner le répertoire de projet complet. Synchrone ; retourne immédiatement.
331
332```python theme={null}
333def get_session_info(
334 session_id: str,
335 directory: str | None = None,
336) -> SDKSessionInfo | None
337```
338
339#### Paramètres
340
341| Paramètre | Type | Par défaut | Description |
342| :----------- | :------------ | :--------- | :---------------------------------------------------------------------------------------- |
343| `session_id` | `str` | requis | UUID de la session à rechercher |
344| `directory` | `str \| None` | `None` | Chemin du répertoire de projet. Quand omis, recherche dans tous les répertoires de projet |
345
346Retourne [`SDKSessionInfo`](#return-type-sdk-session-info), ou `None` si la session n'est pas trouvée.
347
348#### Exemple
349
350Recherchez les métadonnées d'une seule session sans scanner le répertoire de projet. Utile quand vous avez déjà un ID de session d'une exécution précédente.
351
352```python theme={null}
353from claude_agent_sdk import get_session_info
354
355info = get_session_info("550e8400-e29b-41d4-a716-446655440000")
356if info:
357 print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})")
358```
359
360### `rename_session()`
361
362Renomme une session en ajoutant une entrée de titre personnalisé. Les appels répétés sont sûrs ; le titre le plus récent gagne. Synchrone.
363
364```python theme={null}
365def rename_session(
366 session_id: str,
367 title: str,
368 directory: str | None = None,
369) -> None
370```
371
372#### Paramètres
373
374| Paramètre | Type | Par défaut | Description |
375| :----------- | :------------ | :--------- | :---------------------------------------------------------------------------------------- |
376| `session_id` | `str` | requis | UUID de la session à renommer |
377| `title` | `str` | requis | Nouveau titre. Doit être non-vide après suppression des espaces |
378| `directory` | `str \| None` | `None` | Chemin du répertoire de projet. Quand omis, recherche dans tous les répertoires de projet |
379
380Lève `ValueError` si `session_id` n'est pas un UUID valide ou si `title` est vide ; `FileNotFoundError` si la session ne peut pas être trouvée.
381
382#### Exemple
383
384Renommez la session la plus récente pour qu'elle soit plus facile à trouver plus tard. Le nouveau titre apparaît dans [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) lors des lectures ultérieures.
385
386```python theme={null}
387from claude_agent_sdk import list_sessions, rename_session
388
389sessions = list_sessions(directory="/path/to/project", limit=1)
390if sessions:
391 rename_session(sessions[0].session_id, "Refactor auth module")
392```
393
394### `tag_session()`
395
396Étiquette une session. Passez `None` pour effacer l'étiquette. Les appels répétés sont sûrs ; l'étiquette la plus récente gagne. Synchrone.
397
398```python theme={null}
399def tag_session(
400 session_id: str,
401 tag: str | None,
402 directory: str | None = None,
403) -> None
404```
405
406#### Paramètres
407
408| Paramètre | Type | Par défaut | Description |
409| :----------- | :------------ | :--------- | :---------------------------------------------------------------------------------------- |
410| `session_id` | `str` | requis | UUID de la session à étiqueter |
411| `tag` | `str \| None` | requis | Chaîne d'étiquette, ou `None` pour effacer. Nettoyée Unicode avant stockage |
412| `directory` | `str \| None` | `None` | Chemin du répertoire de projet. Quand omis, recherche dans tous les répertoires de projet |
413
414Lève `ValueError` si `session_id` n'est pas un UUID valide ou si `tag` est vide après nettoyage ; `FileNotFoundError` si la session ne peut pas être trouvée.
415
416#### Exemple
417
418Étiquetez une session, puis filtrez par cette étiquette lors d'une lecture ultérieure. Passez `None` pour effacer une étiquette existante.
419
420```python theme={null}
421from claude_agent_sdk import list_sessions, tag_session
422
423# Tag a session
424tag_session("550e8400-e29b-41d4-a716-446655440000", "needs-review")
425
426# Later: find all sessions with that tag
427for session in list_sessions(directory="/path/to/project"):
428 if session.tag == "needs-review":
429 print(session.summary)
430```
431
432## Classes
433
434### `ClaudeSDKClient`
435
436**Maintient une session de conversation sur plusieurs échanges.** C'est l'équivalent Python de la façon dont la fonction `query()` du SDK TypeScript fonctionne en interne - elle crée un objet client qui peut continuer les conversations.
437
438#### Fonctionnalités clés
439
440* **Continuité de session** : Maintient le contexte de conversation sur plusieurs appels `query()`
441* **Même conversation** : La session conserve les messages précédents
442* **Support des interruptions** : Peut arrêter l'exécution en cours de tâche
443* **Cycle de vie explicite** : Vous contrôlez quand la session commence et se termine
444* **Flux basé sur les réponses** : Peut réagir aux réponses et envoyer des suivis
445* **Outils personnalisés et hooks** : Supporte les outils personnalisés (créés avec le décorateur `@tool`) et les hooks
446
447```python theme={null}
448class ClaudeSDKClient:
449 def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None)
450 async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
451 async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
452 async def receive_messages(self) -> AsyncIterator[Message]
453 async def receive_response(self) -> AsyncIterator[Message]
454 async def interrupt(self) -> None
455 async def set_permission_mode(self, mode: str) -> None
456 async def set_model(self, model: str | None = None) -> None
457 async def rewind_files(self, user_message_id: str) -> None
458 async def get_mcp_status(self) -> McpStatusResponse
459 async def reconnect_mcp_server(self, server_name: str) -> None
460 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
461 async def stop_task(self, task_id: str) -> None
462 async def get_server_info(self) -> dict[str, Any] | None
463 async def disconnect(self) -> None
464```
465
466#### Méthodes
467
468| Méthode | Description |
469| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
470| `__init__(options)` | Initialise le client avec une configuration optionnelle |
471| `connect(prompt)` | Se connecte à Claude avec un prompt initial optionnel ou un flux de messages |
472| `query(prompt, session_id)` | Envoie une nouvelle requête en mode streaming |
473| `receive_messages()` | Reçoit tous les messages de Claude comme un itérateur asynchrone |
474| `receive_response()` | Reçoit les messages jusqu'à et incluant un ResultMessage |
475| `interrupt()` | Envoie un signal d'interruption (fonctionne uniquement en mode streaming) |
476| `set_permission_mode(mode)` | Change le mode de permission pour la session actuelle |
477| `set_model(model)` | Change le modèle pour la session actuelle. Passez `None` pour réinitialiser à la valeur par défaut |
478| `rewind_files(user_message_id)` | Restaure les fichiers à leur état au message utilisateur spécifié. Nécessite `enable_file_checkpointing=True`. Voir [File checkpointing](/fr/agent-sdk/file-checkpointing) |
479| `get_mcp_status()` | Obtient le statut de tous les serveurs MCP configurés. Retourne [`McpStatusResponse`](#mcp-status-response) |
480| `reconnect_mcp_server(server_name)` | Réessaye de se connecter à un serveur MCP qui a échoué ou a été déconnecté |
481| `toggle_mcp_server(server_name, enabled)` | Active ou désactive un serveur MCP en cours de session. La désactivation supprime ses outils |
482| `stop_task(task_id)` | Arrête une tâche de fond en cours d'exécution. Un [`TaskNotificationMessage`](#task-notification-message) avec le statut `"stopped"` suit dans le flux de messages |
483| `get_server_info()` | Obtient les informations du serveur incluant l'ID de session et les capacités |
484| `disconnect()` | Se déconnecte de Claude |
485
486#### Support du gestionnaire de contexte
487
488Le client peut être utilisé comme un gestionnaire de contexte asynchrone pour la gestion automatique de la connexion :
489
490```python theme={null}
491async with ClaudeSDKClient() as client:
492 await client.query("Hello Claude")
493 async for message in client.receive_response():
494 print(message)
495```
496
497> **Important :** Lors de l'itération sur les messages, évitez d'utiliser `break` pour quitter tôt car cela peut causer des problèmes de nettoyage asyncio. À la place, laissez l'itération se terminer naturellement ou utilisez des drapeaux pour suivre quand vous avez trouvé ce que vous cherchiez.
498
499#### Exemple - Continuer une conversation
500
501```python theme={null}
502import asyncio
503from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage
504
505
506async def main():
507 async with ClaudeSDKClient() as client:
508 # First question
509 await client.query("What's the capital of France?")
510
511 # Process response
512 async for message in client.receive_response():
513 if isinstance(message, AssistantMessage):
514 for block in message.content:
515 if isinstance(block, TextBlock):
516 print(f"Claude: {block.text}")
517
518 # Follow-up question - the session retains the previous context
519 await client.query("What's the population of that city?")
520
521 async for message in client.receive_response():
522 if isinstance(message, AssistantMessage):
523 for block in message.content:
524 if isinstance(block, TextBlock):
525 print(f"Claude: {block.text}")
526
527 # Another follow-up - still in the same conversation
528 await client.query("What are some famous landmarks there?")
529
530 async for message in client.receive_response():
531 if isinstance(message, AssistantMessage):
532 for block in message.content:
533 if isinstance(block, TextBlock):
534 print(f"Claude: {block.text}")
535
536
537asyncio.run(main())
538```
539
540#### Exemple - Entrée en streaming avec ClaudeSDKClient
541
542```python theme={null}
543import asyncio
544from claude_agent_sdk import ClaudeSDKClient
545
546
547async def message_stream():
548 """Generate messages dynamically."""
549 yield {
550 "type": "user",
551 "message": {"role": "user", "content": "Analyze the following data:"},
552 }
553 await asyncio.sleep(0.5)
554 yield {
555 "type": "user",
556 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
557 }
558 await asyncio.sleep(0.5)
559 yield {
560 "type": "user",
561 "message": {"role": "user", "content": "What patterns do you see?"},
562 }
563
564
565async def main():
566 async with ClaudeSDKClient() as client:
567 # Stream input to Claude
568 await client.query(message_stream())
569
570 # Process response
571 async for message in client.receive_response():
572 print(message)
573
574 # Follow-up in same session
575 await client.query("Should we be concerned about these readings?")
576
577 async for message in client.receive_response():
578 print(message)
579
580
581asyncio.run(main())
582```
583
584#### Exemple - Utiliser les interruptions
585
586```python theme={null}
587import asyncio
588from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage
589
590
591async def interruptible_task():
592 options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits")
593
594 async with ClaudeSDKClient(options=options) as client:
595 # Start a long-running task
596 await client.query("Count from 1 to 100 slowly, using the bash sleep command")
597
598 # Let it run for a bit
599 await asyncio.sleep(2)
600
601 # Interrupt the task
602 await client.interrupt()
603 print("Task interrupted!")
604
605 # Drain the interrupted task's messages (including its ResultMessage)
606 async for message in client.receive_response():
607 if isinstance(message, ResultMessage):
608 print(f"Interrupted task finished with subtype={message.subtype!r}")
609 # subtype is "error_during_execution" for interrupted tasks
610
611 # Send a new command
612 await client.query("Just say hello instead")
613
614 # Now receive the new response
615 async for message in client.receive_response():
616 if isinstance(message, ResultMessage) and message.subtype == "success":
617 print(f"New result: {message.result}")
618
619
620asyncio.run(interruptible_task())
621```
622
623<Note>
624 **Comportement du buffer après interruption :** `interrupt()` envoie un signal d'arrêt mais ne vide pas le buffer de messages. Les messages déjà produits par la tâche interrompue, incluant son `ResultMessage` (avec `subtype="error_during_execution"`), restent dans le flux. Vous devez les vider avec `receive_response()` avant de lire la réponse à une nouvelle requête. Si vous envoyez une nouvelle requête immédiatement après `interrupt()` et appelez `receive_response()` une seule fois, vous recevrez les messages de la tâche interrompue, pas la réponse de la nouvelle requête.
625</Note>
626
627#### Exemple - Contrôle avancé des permissions
628
629```python theme={null}
630from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
631from claude_agent_sdk.types import (
632 PermissionResultAllow,
633 PermissionResultDeny,
634 ToolPermissionContext,
635)
636
637
638async def custom_permission_handler(
639 tool_name: str, input_data: dict, context: ToolPermissionContext
640) -> PermissionResultAllow | PermissionResultDeny:
641 """Custom logic for tool permissions."""
642
643 # Block writes to system directories
644 if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
645 return PermissionResultDeny(
646 message="System directory write not allowed", interrupt=True
647 )
648
649 # Redirect sensitive file operations
650 if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
651 safe_path = f"./sandbox/{input_data['file_path']}"
652 return PermissionResultAllow(
653 updated_input={**input_data, "file_path": safe_path}
654 )
655
656 # Allow everything else
657 return PermissionResultAllow(updated_input=input_data)
658
659
660async def main():
661 options = ClaudeAgentOptions(
662 can_use_tool=custom_permission_handler, allowed_tools=["Read", "Write", "Edit"]
663 )
664
665 async with ClaudeSDKClient(options=options) as client:
666 await client.query("Update the system config file")
667
668 async for message in client.receive_response():
669 # Will use sandbox path instead
670 print(message)
671
672
673asyncio.run(main())
674```
675
676## Types
677
678<Note>
679 **`@dataclass` vs `TypedDict` :** Ce SDK utilise deux types de types. Les classes décorées avec `@dataclass` (telles que `ResultMessage`, `AgentDefinition`, `TextBlock`) sont des instances d'objet à l'exécution et supportent l'accès par attribut : `msg.result`. Les classes définies avec `TypedDict` (telles que `ThinkingConfigEnabled`, `McpStdioServerConfig`, `SyncHookJSONOutput`) sont **des dicts simples à l'exécution** et nécessitent l'accès par clé : `config["budget_tokens"]`, pas `config.budget_tokens`. La syntaxe d'appel `ClassName(field=value)` fonctionne pour les deux, mais seules les dataclasses produisent des objets avec des attributs.
680</Note>
681
682### `SdkMcpTool`
683
684Définition pour un outil MCP SDK créé avec le décorateur `@tool`.
685
686```python theme={null}
687@dataclass
688class SdkMcpTool(Generic[T]):
689 name: str
690 description: str
691 input_schema: type[T] | dict[str, Any]
692 handler: Callable[[T], Awaitable[dict[str, Any]]]
693 annotations: ToolAnnotations | None = None
694```
695
696| Propriété | Type | Description |
697| :------------- | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
698| `name` | `str` | Identifiant unique pour l'outil |
699| `description` | `str` | Description lisible |
700| `input_schema` | `type[T] \| dict[str, Any]` | Schéma pour la validation d'entrée |
701| `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | Fonction asynchrone qui gère l'exécution de l'outil |
702| `annotations` | `ToolAnnotations \| None` | Annotations MCP optionnelles (par exemple, `readOnlyHint`, `destructiveHint`, `openWorldHint`). De `mcp.types` |
703
704### `Transport`
705
706Classe de base abstraite pour les implémentations de transport personnalisées. Utilisez ceci pour communiquer avec le processus Claude sur un canal personnalisé (par exemple, une connexion distante au lieu d'un sous-processus local).
707
708<Warning>
709 C'est une API interne de bas niveau. L'interface peut changer dans les versions futures. Les implémentations personnalisées doivent être mises à jour pour correspondre à tout changement d'interface.
710</Warning>
711
712```python theme={null}
713from abc import ABC, abstractmethod
714from collections.abc import AsyncIterator
715from typing import Any
716
717
718class Transport(ABC):
719 @abstractmethod
720 async def connect(self) -> None: ...
721
722 @abstractmethod
723 async def write(self, data: str) -> None: ...
724
725 @abstractmethod
726 def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...
727
728 @abstractmethod
729 async def close(self) -> None: ...
730
731 @abstractmethod
732 def is_ready(self) -> bool: ...
733
734 @abstractmethod
735 async def end_input(self) -> None: ...
736```
737
738| Méthode | Description |
739| :---------------- | :--------------------------------------------------------------------------------------- |
740| `connect()` | Connecte le transport et prépare la communication |
741| `write(data)` | Écrit les données brutes (JSON + nouvelle ligne) dans le transport |
742| `read_messages()` | Itérateur asynchrone qui produit les messages JSON analysés |
743| `close()` | Ferme la connexion et nettoie les ressources |
744| `is_ready()` | Retourne `True` si le transport peut envoyer et recevoir |
745| `end_input()` | Ferme le flux d'entrée (par exemple, fermer stdin pour les transports de sous-processus) |
746
747Importation : `from claude_agent_sdk import Transport`
748
749### `ClaudeAgentOptions`
750
751Dataclass de configuration pour les requêtes Claude Code.
752
753```python theme={null}
754@dataclass
755class ClaudeAgentOptions:
756 tools: list[str] | ToolsPreset | None = None
757 allowed_tools: list[str] = field(default_factory=list)
758 system_prompt: str | SystemPromptPreset | None = None
759 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
760 permission_mode: PermissionMode | None = None
761 continue_conversation: bool = False
762 resume: str | None = None
763 max_turns: int | None = None
764 max_budget_usd: float | None = None
765 disallowed_tools: list[str] = field(default_factory=list)
766 model: str | None = None
767 fallback_model: str | None = None
768 betas: list[SdkBeta] = field(default_factory=list)
769 output_format: dict[str, Any] | None = None
770 permission_prompt_tool_name: str | None = None
771 cwd: str | Path | None = None
772 cli_path: str | Path | None = None
773 settings: str | None = None
774 add_dirs: list[str | Path] = field(default_factory=list)
775 env: dict[str, str] = field(default_factory=dict)
776 extra_args: dict[str, str | None] = field(default_factory=dict)
777 max_buffer_size: int | None = None
778 debug_stderr: Any = sys.stderr # Deprecated
779 stderr: Callable[[str], None] | None = None
780 can_use_tool: CanUseTool | None = None
781 hooks: dict[HookEvent, list[HookMatcher]] | None = None
782 user: str | None = None
783 include_partial_messages: bool = False
784 fork_session: bool = False
785 agents: dict[str, AgentDefinition] | None = None
786 setting_sources: list[SettingSource] | None = None
787 sandbox: SandboxSettings | None = None
788 plugins: list[SdkPluginConfig] = field(default_factory=list)
789 max_thinking_tokens: int | None = None # Deprecated: use thinking instead
790 thinking: ThinkingConfig | None = None
791 effort: Literal["low", "medium", "high", "max"] | None = None
792 enable_file_checkpointing: bool = False
793 session_store: SessionStore | None = None
794```
795
796| Propriété | Type | Par défaut | Description |
797| :---------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuration des outils. Utilisez `{"type": "preset", "preset": "claude_code"}` pour les outils par défaut de Claude Code |
799| `allowed_tools` | `list[str]` | `[]` | Outils à approuver automatiquement sans demander. Ceci ne restreint pas Claude à seulement ces outils ; les outils non listés passent par `permission_mode` et `can_use_tool`. Utilisez `disallowed_tools` pour bloquer les outils. Voir [Permissions](/fr/agent-sdk/permissions#allow-and-deny-rules) |
800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuration du prompt système. Passez une chaîne pour un prompt personnalisé, ou utilisez `{"type": "preset", "preset": "claude_code"}` pour le prompt système de Claude Code. Ajoutez `"append"` pour étendre le preset |
801| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configurations de serveur MCP ou chemin vers le fichier de configuration |
802| `permission_mode` | `PermissionMode \| None` | `None` | Mode de permission pour l'utilisation des outils |
803| `continue_conversation` | `bool` | `False` | Continuer la conversation la plus récente |
804| `resume` | `str \| None` | `None` | ID de session à reprendre |
805| `max_turns` | `int \| None` | `None` | Nombre maximum de tours agentiques (allers-retours d'utilisation d'outils) |
806| `max_budget_usd` | `float \| None` | `None` | Arrêtez la requête quand l'estimation du coût côté client atteint cette valeur USD. Comparé à la même estimation que `total_cost_usd` ; voir [Suivi du coût et de l'utilisation](/fr/agent-sdk/cost-tracking) pour les avertissements de précision |
807| `disallowed_tools` | `list[str]` | `[]` | Outils à toujours refuser. Les règles de refus sont vérifiées en premier et remplacent `allowed_tools` et `permission_mode` (incluant `bypassPermissions`) |
808| `enable_file_checkpointing` | `bool` | `False` | Activez le suivi des modifications de fichiers pour le rembobinage. Voir [Sauvegarde de points de contrôle de fichiers](/fr/agent-sdk/file-checkpointing) |
809| `model` | `str \| None` | `None` | Modèle Claude à utiliser |
810| `fallback_model` | `str \| None` | `None` | Modèle de secours à utiliser si le modèle principal échoue |
811| `betas` | `list[SdkBeta]` | `[]` | Fonctionnalités bêta à activer. Voir [`SdkBeta`](#sdk-beta) pour les options disponibles |
812| `output_format` | `dict[str, Any] \| None` | `None` | Format de sortie pour les réponses structurées (par exemple, `{"type": "json_schema", "schema": {...}}`). Voir [Sorties structurées](/fr/agent-sdk/structured-outputs) pour les détails |
813| `permission_prompt_tool_name` | `str \| None` | `None` | Nom de l'outil MCP pour les prompts de permission |
814| `cwd` | `str \| Path \| None` | `None` | Répertoire de travail actuel |
815| `cli_path` | `str \| Path \| None` | `None` | Chemin personnalisé vers l'exécutable CLI de Claude Code |
816| `settings` | `str \| None` | `None` | Chemin vers le fichier de paramètres |
817| `add_dirs` | `list[str \| Path]` | `[]` | Répertoires supplémentaires auxquels Claude peut accéder |
818| `env` | `dict[str, str]` | `{}` | Variables d'environnement fusionnées au-dessus de l'environnement de processus hérité. Voir [Variables d'environnement](/fr/env-vars) pour les variables que le CLI sous-jacent lit |
819| `extra_args` | `dict[str, str \| None]` | `{}` | Arguments CLI supplémentaires à passer directement au CLI |
820| `max_buffer_size` | `int \| None` | `None` | Octets maximum lors de la mise en buffer de la sortie standard du CLI |
821| `debug_stderr` | `Any` | `sys.stderr` | *Déprécié* - Objet de type fichier pour la sortie de débogage. Utilisez plutôt le callback `stderr` |
822| `stderr` | `Callable[[str], None] \| None` | `None` | Fonction de callback pour la sortie stderr du CLI |
823| `can_use_tool` | [`CanUseTool`](#can-use-tool) ` \| None` | `None` | Fonction de callback de permission d'outil. Voir [Types de permission](#can-use-tool) pour les détails |
824| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Configurations de hook pour intercepter les événements |
825| `user` | `str \| None` | `None` | Identifiant utilisateur |
826| `include_partial_messages` | `bool` | `False` | Inclure les événements de streaming de messages partiels. Quand activé, les messages [`StreamEvent`](#stream-event) sont produits |
827| `fork_session` | `bool` | `False` | Quand reprendre avec `resume`, bifurquer vers un nouvel ID de session au lieu de continuer la session originale |
828| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Sous-agents définis programmatiquement |
829| `plugins` | `list[SdkPluginConfig]` | `[]` | Charger les plugins personnalisés à partir de chemins locaux. Voir [Plugins](/fr/agent-sdk/plugins) pour les détails |
830| `sandbox` | [`SandboxSettings`](#sandbox-settings) ` \| None` | `None` | Configurez le comportement du sandbox programmatiquement. Voir [Paramètres du sandbox](#sandbox-settings) pour les détails |
831| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Contrôlez quels paramètres du système de fichiers charger. Passez `[]` pour désactiver les paramètres utilisateur, projet et locaux. Les paramètres de politique gérée se chargent indépendamment. Voir [Utiliser les fonctionnalités de Claude Code](/fr/agent-sdk/claude-code-features#what-settingsources-does-not-control) |
832| `max_thinking_tokens` | `int \| None` | `None` | *Déprécié* - Tokens maximum pour les blocs de réflexion. Utilisez `thinking` à la place |
833| `thinking` | [`ThinkingConfig`](#thinking-config) ` \| None` | `None` | Contrôle le comportement de la réflexion étendue. Prend la priorité sur `max_thinking_tokens` |
834| `effort` | `Literal["low", "medium", "high", "max"] \| None` | `None` | Niveau d'effort pour la profondeur de réflexion |
835| `session_store` | [`SessionStore`](/fr/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Miroir les transcriptions de session vers un backend externe pour que n'importe quel hôte puisse les reprendre. Voir [Persister les sessions vers un stockage externe](/fr/agent-sdk/session-storage) |
836
837### `OutputFormat`
838
839Configuration pour la validation de sortie structurée. Passez ceci comme un `dict` au champ `output_format` sur `ClaudeAgentOptions` :
840
841```python theme={null}
842# Expected dict shape for output_format
843{
844 "type": "json_schema",
845 "schema": {...}, # Your JSON Schema definition
846}
847```
848
849| Champ | Requis | Description |
850| :------- | :----- | :------------------------------------------------------- |
851| `type` | Oui | Doit être `"json_schema"` pour la validation JSON Schema |
852| `schema` | Oui | Définition JSON Schema pour la validation de sortie |
853
854### `SystemPromptPreset`
855
856Configuration pour utiliser le preset de prompt système de Claude Code avec des ajouts optionnels.
857
858```python theme={null}
859class SystemPromptPreset(TypedDict):
860 type: Literal["preset"]
861 preset: Literal["claude_code"]
862 append: NotRequired[str]
863 exclude_dynamic_sections: NotRequired[bool]
864```
865
866| Champ | Requis | Description |
867| :------------------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
868| `type` | Oui | Doit être `"preset"` pour utiliser un preset de prompt système |
869| `preset` | Oui | Doit être `"claude_code"` pour utiliser le prompt système de Claude Code |
870| `append` | Non | Instructions supplémentaires à ajouter au preset de prompt système |
871| `exclude_dynamic_sections` | Non | Déplacez le contexte par session comme le répertoire de travail, le statut git et les chemins de mémoire du prompt système vers le premier message utilisateur. Améliore la réutilisation du cache de prompt entre les utilisateurs et les machines. Voir [Modifier les prompts système](/fr/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |
872
873### `SettingSource`
874
875Contrôle quelles sources de configuration basées sur le système de fichiers le SDK charge les paramètres à partir de.
876
877```python theme={null}
878SettingSource = Literal["user", "project", "local"]
879```
880
881| Valeur | Description | Emplacement |
882| :---------- | :-------------------------------------------------- | :---------------------------- |
883| `"user"` | Paramètres utilisateur globaux | `~/.claude/settings.json` |
884| `"project"` | Paramètres de projet partagés (contrôle de version) | `.claude/settings.json` |
885| `"local"` | Paramètres de projet locaux (gitignored) | `.claude/settings.local.json` |
886
887#### Comportement par défaut
888
889Quand `setting_sources` est omis ou `None`, `query()` charge les mêmes paramètres du système de fichiers que le CLI Claude Code : utilisateur, projet et local. Les paramètres de politique gérée sont chargés dans tous les cas. Voir [Ce que settingSources ne contrôle pas](/fr/agent-sdk/claude-code-features#what-settingsources-does-not-control) pour les entrées qui sont lues indépendamment de cette option, et comment les désactiver.
890
891#### Pourquoi utiliser setting\_sources
892
893**Désactiver les paramètres du système de fichiers :**
894
895```python theme={null}
896# Do not load user, project, or local settings from disk
897from claude_agent_sdk import query, ClaudeAgentOptions
898
899async for message in query(
900 prompt="Analyze this code",
901 options=ClaudeAgentOptions(
902 setting_sources=[]
903 ),
904):
905 print(message)
906```
907
908<Note>
909 Dans le SDK Python 0.1.59 et antérieur, une liste vide était traitée de la même manière que l'omission de l'option, donc `setting_sources=[]` n'a pas désactivé les paramètres du système de fichiers. Mettez à niveau vers une version plus récente si vous avez besoin qu'une liste vide prenne effet. Le SDK TypeScript n'est pas affecté.
910</Note>
911
912**Charger tous les paramètres du système de fichiers explicitement :**
913
914```python theme={null}
915from claude_agent_sdk import query, ClaudeAgentOptions
916
917async for message in query(
918 prompt="Analyze this code",
919 options=ClaudeAgentOptions(
920 setting_sources=["user", "project", "local"]
921 ),
922):
923 print(message)
924```
925
926**Charger uniquement des sources de paramètres spécifiques :**
927
928```python theme={null}
929# Load only project settings, ignore user and local
930async for message in query(
931 prompt="Run CI checks",
932 options=ClaudeAgentOptions(
933 setting_sources=["project"] # Only .claude/settings.json
934 ),
935):
936 print(message)
937```
938
939**Environnements de test et CI :**
940
941```python theme={null}
942# Ensure consistent behavior in CI by excluding local settings
943async for message in query(
944 prompt="Run tests",
945 options=ClaudeAgentOptions(
946 setting_sources=["project"], # Only team-shared settings
947 permission_mode="bypassPermissions",
948 ),
949):
950 print(message)
951```
952
953**Applications SDK uniquement :**
954
955```python theme={null}
956# Define everything programmatically.
957# Pass [] to opt out of filesystem setting sources.
958async for message in query(
959 prompt="Review this PR",
960 options=ClaudeAgentOptions(
961 setting_sources=[],
962 agents={...},
963 mcp_servers={...},
964 allowed_tools=["Read", "Grep", "Glob"],
965 ),
966):
967 print(message)
968```
969
970**Chargement des instructions de projet CLAUDE.md :**
971
972```python theme={null}
973# Load project settings to include CLAUDE.md files
974async for message in query(
975 prompt="Add a new feature following project conventions",
976 options=ClaudeAgentOptions(
977 system_prompt={
978 "type": "preset",
979 "preset": "claude_code", # Use Claude Code's system prompt
980 },
981 setting_sources=["project"], # Loads CLAUDE.md from project
982 allowed_tools=["Read", "Write", "Edit"],
983 ),
984):
985 print(message)
986```
987
988#### Précédence des paramètres
989
990Quand plusieurs sources sont chargées, les paramètres sont fusionnés avec cette précédence (la plus haute à la plus basse) :
991
9921. Paramètres locaux (`.claude/settings.local.json`)
9932. Paramètres de projet (`.claude/settings.json`)
9943. Paramètres utilisateur (`~/.claude/settings.json`)
995
996Les options programmatiques telles que `agents` et `allowed_tools` remplacent les paramètres du système de fichiers utilisateur, projet et local. Les paramètres de politique gérée prennent la priorité sur les options programmatiques.
997
998### `AgentDefinition`
999
1000Configuration pour un sous-agent défini programmatiquement.
1001
1002```python theme={null}
1003@dataclass
1004class AgentDefinition:
1005 description: str
1006 prompt: str
1007 tools: list[str] | None = None
1008 disallowedTools: list[str] | None = None
1009 model: str | None = None
1010 skills: list[str] | None = None
1011 memory: Literal["user", "project", "local"] | None = None
1012 mcpServers: list[str | dict[str, Any]] | None = None
1013 initialPrompt: str | None = None
1014 maxTurns: int | None = None
1015 background: bool | None = None
1016 effort: Literal["low", "medium", "high", "max"] | int | None = None
1017 permissionMode: PermissionMode | None = None
1018```
1019
1020| Champ | Requis | Description |
1021| :---------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1022| `description` | Oui | Description en langage naturel de quand utiliser cet agent |
1023| `prompt` | Oui | Le prompt système de l'agent |
1024| `tools` | Non | Tableau des noms d'outils autorisés. Si omis, hérite de tous les outils |
1025| `disallowedTools` | Non | Tableau des noms d'outils à supprimer de l'ensemble d'outils de l'agent |
1026| `model` | Non | Remplacement de modèle pour cet agent. Accepte un alias tel que `"sonnet"`, `"opus"`, `"haiku"`, ou `"inherit"`, ou un ID de modèle complet. Si omis, utilise le modèle principal |
1027| `skills` | Non | Liste des noms de compétences disponibles pour cet agent |
1028| `memory` | Non | Source de mémoire pour cet agent : `"user"`, `"project"`, ou `"local"` |
1029| `mcpServers` | Non | Serveurs MCP disponibles pour cet agent. Chaque entrée est un nom de serveur ou un dict `{name: config}` en ligne |
1030| `initialPrompt` | Non | Auto-soumis comme le premier tour utilisateur quand cet agent s'exécute comme l'agent du fil principal |
1031| `maxTurns` | Non | Nombre maximum de tours agentiques avant que l'agent s'arrête |
1032| `background` | Non | Exécutez cet agent comme une tâche de fond non-bloquante quand invoqué |
1033| `effort` | Non | Niveau d'effort de raisonnement pour cet agent. Accepte un niveau nommé ou un entier |
1034| `permissionMode` | Non | Mode de permission pour l'exécution des outils dans cet agent. Voir [`PermissionMode`](#permission-mode) |
1035
1036<Note>
1037 Les noms de champs `AgentDefinition` utilisent camelCase, tels que `disallowedTools`, `permissionMode`, et `maxTurns`. Ces noms correspondent directement au format de fil partagé avec le SDK TypeScript. Ceci diffère de `ClaudeAgentOptions`, qui utilise Python snake\_case pour les champs de niveau supérieur équivalents tels que `disallowed_tools` et `permission_mode`. Parce que `AgentDefinition` est une dataclass, passer un mot-clé snake\_case lève une `TypeError` au moment de la construction.
1038</Note>
1039
1040### `PermissionMode`
1041
1042Modes de permission pour contrôler l'exécution des outils.
1043
1044```python theme={null}
1045PermissionMode = Literal[
1046 "default", # Standard permission behavior
1047 "acceptEdits", # Auto-accept file edits
1048 "plan", # Planning mode - no execution
1049 "dontAsk", # Deny anything not pre-approved instead of prompting
1050 "bypassPermissions", # Bypass all permission checks (use with caution)
1051]
1052```
1053
1054### `CanUseTool`
1055
1056Alias de type pour les fonctions de callback de permission d'outil.
1057
1058```python theme={null}
1059CanUseTool = Callable[
1060 [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
1061]
1062```
1063
1064Le callback reçoit :
1065
1066* `tool_name` : Nom de l'outil en cours d'appel
1067* `input_data` : Les paramètres d'entrée de l'outil
1068* `context` : Un `ToolPermissionContext` avec des informations supplémentaires
1069
1070Retourne un `PermissionResult` (soit `PermissionResultAllow` soit `PermissionResultDeny`).
1071
1072### `ToolPermissionContext`
1073
1074Informations de contexte passées aux callbacks de permission d'outil.
1075
1076```python theme={null}
1077@dataclass
1078class ToolPermissionContext:
1079 signal: Any | None = None # Future: abort signal support
1080 suggestions: list[PermissionUpdate] = field(default_factory=list)
1081```
1082
1083| Champ | Type | Description |
1084| :------------ | :----------------------- | :------------------------------------------------ |
1085| `signal` | `Any \| None` | Réservé pour le support futur du signal d'abandon |
1086| `suggestions` | `list[PermissionUpdate]` | Suggestions de mise à jour de permission du CLI |
1087
1088### `PermissionResult`
1089
1090Type union pour les résultats de callback de permission.
1091
1092```python theme={null}
1093PermissionResult = PermissionResultAllow | PermissionResultDeny
1094```
1095
1096### `PermissionResultAllow`
1097
1098Résultat indiquant que l'appel d'outil doit être autorisé.
1099
1100```python theme={null}
1101@dataclass
1102class PermissionResultAllow:
1103 behavior: Literal["allow"] = "allow"
1104 updated_input: dict[str, Any] | None = None
1105 updated_permissions: list[PermissionUpdate] | None = None
1106```
1107
1108| Champ | Type | Par défaut | Description |
1109| :-------------------- | :------------------------------- | :--------- | :-------------------------------------------------- |
1110| `behavior` | `Literal["allow"]` | `"allow"` | Doit être « allow » |
1111| `updated_input` | `dict[str, Any] \| None` | `None` | Entrée modifiée à utiliser à la place de l'original |
1112| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | Mises à jour de permission à appliquer |
1113
1114### `PermissionResultDeny`
1115
1116Résultat indiquant que l'appel d'outil doit être refusé.
1117
1118```python theme={null}
1119@dataclass
1120class PermissionResultDeny:
1121 behavior: Literal["deny"] = "deny"
1122 message: str = ""
1123 interrupt: bool = False
1124```
1125
1126| Champ | Type | Par défaut | Description |
1127| :---------- | :---------------- | :--------- | :----------------------------------------------- |
1128| `behavior` | `Literal["deny"]` | `"deny"` | Doit être « deny » |
1129| `message` | `str` | `""` | Message expliquant pourquoi l'outil a été refusé |
1130| `interrupt` | `bool` | `False` | S'il faut interrompre l'exécution actuelle |
1131
1132### `PermissionUpdate`
1133
1134Configuration pour mettre à jour les permissions programmatiquement.
1135
1136```python theme={null}
1137@dataclass
1138class PermissionUpdate:
1139 type: Literal[
1140 "addRules",
1141 "replaceRules",
1142 "removeRules",
1143 "setMode",
1144 "addDirectories",
1145 "removeDirectories",
1146 ]
1147 rules: list[PermissionRuleValue] | None = None
1148 behavior: Literal["allow", "deny", "ask"] | None = None
1149 mode: PermissionMode | None = None
1150 directories: list[str] | None = None
1151 destination: (
1152 Literal["userSettings", "projectSettings", "localSettings", "session"] | None
1153 ) = None
1154```
1155
1156| Champ | Type | Description |
1157| :------------ | :---------------------------------------- | :---------------------------------------------------------------- |
1158| `type` | `Literal[...]` | Le type d'opération de mise à jour de permission |
1159| `rules` | `list[PermissionRuleValue] \| None` | Règles pour les opérations d'ajout/remplacement/suppression |
1160| `behavior` | `Literal["allow", "deny", "ask"] \| None` | Comportement pour les opérations basées sur les règles |
1161| `mode` | `PermissionMode \| None` | Mode pour l'opération setMode |
1162| `directories` | `list[str] \| None` | Répertoires pour les opérations d'ajout/suppression de répertoire |
1163| `destination` | `Literal[...] \| None` | Où appliquer la mise à jour de permission |
1164
1165### `PermissionRuleValue`
1166
1167Une règle à ajouter, remplacer ou supprimer dans une mise à jour de permission.
1168
1169```python theme={null}
1170@dataclass
1171class PermissionRuleValue:
1172 tool_name: str
1173 rule_content: str | None = None
1174```
1175
1176### `ToolsPreset`
1177
1178Configuration des outils preset pour utiliser l'ensemble d'outils par défaut de Claude Code.
1179
1180```python theme={null}
1181class ToolsPreset(TypedDict):
1182 type: Literal["preset"]
1183 preset: Literal["claude_code"]
1184```
1185
1186### `ThinkingConfig`
1187
1188Contrôle le comportement de la réflexion étendue. Une union de trois configurations :
1189
1190```python theme={null}
1191class ThinkingConfigAdaptive(TypedDict):
1192 type: Literal["adaptive"]
1193
1194
1195class ThinkingConfigEnabled(TypedDict):
1196 type: Literal["enabled"]
1197 budget_tokens: int
1198
1199
1200class ThinkingConfigDisabled(TypedDict):
1201 type: Literal["disabled"]
1202
1203
1204ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled
1205```
1206
1207| Variante | Champs | Description |
1208| :--------- | :---------------------- | :------------------------------------------------------- |
1209| `adaptive` | `type` | Claude décide de manière adaptative quand réfléchir |
1210| `enabled` | `type`, `budget_tokens` | Activez la réflexion avec un budget de tokens spécifique |
1211| `disabled` | `type` | Désactivez la réflexion |
1212
1213Parce que ce sont des classes `TypedDict`, ce sont des dicts simples à l'exécution. Construisez-les soit comme des littéraux dict soit appelez la classe comme un constructeur ; les deux produisent un `dict`. Accédez aux champs avec `config["budget_tokens"]`, pas `config.budget_tokens` :
1214
1215```python theme={null}
1216from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled
1217
1218# Option 1: dict literal (recommended, no import needed)
1219options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})
1220
1221# Option 2: constructor-style (returns a plain dict)
1222config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
1223print(config["budget_tokens"]) # 20000
1224# config.budget_tokens would raise AttributeError
1225```
1226
1227### `SdkBeta`
1228
1229Type littéral pour les fonctionnalités bêta du SDK.
1230
1231```python theme={null}
1232SdkBeta = Literal["context-1m-2025-08-07"]
1233```
1234
1235Utilisez avec le champ `betas` dans `ClaudeAgentOptions` pour activer les fonctionnalités bêta.
1236
1237<Warning>
1238 La bêta `context-1m-2025-08-07` est retirée à partir du 30 avril 2026. Passer cet en-tête avec Claude Sonnet 4.5 ou Sonnet 4 n'a aucun effet, et les requêtes qui dépassent la fenêtre de contexte standard de 200k tokens retournent une erreur. Pour utiliser une fenêtre de contexte de 1M tokens, migrez vers [Claude Sonnet 4.6, Claude Opus 4.6, ou Claude Opus 4.7](https://platform.claude.com/docs/en/about-claude/models/overview), qui incluent 1M de contexte à prix standard sans en-tête bêta requis.
1239</Warning>
1240
1241### `McpSdkServerConfig`
1242
1243Configuration pour les serveurs MCP SDK créés avec `create_sdk_mcp_server()`.
1244
1245```python theme={null}
1246class McpSdkServerConfig(TypedDict):
1247 type: Literal["sdk"]
1248 name: str
1249 instance: Any # MCP Server instance
1250```
1251
1252### `McpServerConfig`
1253
1254Type union pour les configurations de serveur MCP.
1255
1256```python theme={null}
1257McpServerConfig = (
1258 McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
1259)
1260```
1261
1262#### `McpStdioServerConfig`
1263
1264```python theme={null}
1265class McpStdioServerConfig(TypedDict):
1266 type: NotRequired[Literal["stdio"]] # Optional for backwards compatibility
1267 command: str
1268 args: NotRequired[list[str]]
1269 env: NotRequired[dict[str, str]]
1270```
1271
1272#### `McpSSEServerConfig`
1273
1274```python theme={null}
1275class McpSSEServerConfig(TypedDict):
1276 type: Literal["sse"]
1277 url: str
1278 headers: NotRequired[dict[str, str]]
1279```
1280
1281#### `McpHttpServerConfig`
1282
1283```python theme={null}
1284class McpHttpServerConfig(TypedDict):
1285 type: Literal["http"]
1286 url: str
1287 headers: NotRequired[dict[str, str]]
1288```
1289
1290### `McpServerStatusConfig`
1291
1292La configuration d'un serveur MCP telle que rapportée par [`get_mcp_status()`](#methods). C'est l'union de toutes les variantes de transport [`McpServerConfig`](#mcp-server-config) plus une variante de sortie uniquement `claudeai-proxy` pour les serveurs proxifiés via claude.ai.
1293
1294```python theme={null}
1295McpServerStatusConfig = (
1296 McpStdioServerConfig
1297 | McpSSEServerConfig
1298 | McpHttpServerConfig
1299 | McpSdkServerConfigStatus
1300 | McpClaudeAIProxyServerConfig
1301)
1302```
1303
1304`McpSdkServerConfigStatus` est la forme sérialisable de [`McpSdkServerConfig`](#mcp-sdk-server-config) avec seulement les champs `type` (`"sdk"`) et `name` (`str`) ; l'`instance` en processus est omise. `McpClaudeAIProxyServerConfig` a les champs `type` (`"claudeai-proxy"`), `url` (`str`), et `id` (`str`).
1305
1306### `McpStatusResponse`
1307
1308Réponse de [`ClaudeSDKClient.get_mcp_status()`](#methods). Enveloppe la liste des statuts de serveur sous la clé `mcpServers`.
1309
1310```python theme={null}
1311class McpStatusResponse(TypedDict):
1312 mcpServers: list[McpServerStatus]
1313```
1314
1315### `McpServerStatus`
1316
1317Statut d'un serveur MCP connecté, contenu dans [`McpStatusResponse`](#mcp-status-response).
1318
1319```python theme={null}
1320class McpServerStatus(TypedDict):
1321 name: str
1322 status: McpServerConnectionStatus # "connected" | "failed" | "needs-auth" | "pending" | "disabled"
1323 serverInfo: NotRequired[McpServerInfo]
1324 error: NotRequired[str]
1325 config: NotRequired[McpServerStatusConfig]
1326 scope: NotRequired[str]
1327 tools: NotRequired[list[McpToolInfo]]
1328```
1329
1330| Champ | Type | Description |
1331| :----------- | :--------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1332| `name` | `str` | Nom du serveur |
1333| `status` | `str` | L'un de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, ou `"disabled"` |
1334| `serverInfo` | `dict` (optionnel) | Nom et version du serveur (`{"name": str, "version": str}`) |
1335| `error` | `str` (optionnel) | Message d'erreur si le serveur n'a pas pu se connecter |
1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (optionnel) | Configuration du serveur. Même forme que [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, ou SDK), plus une variante `claudeai-proxy` pour les serveurs connectés via claude.ai |
1337| `scope` | `str` (optionnel) | Portée de la configuration |
1338| `tools` | `list` (optionnel) | Outils fournis par ce serveur, chacun avec les champs `name`, `description`, et `annotations` |
1339
1340### `SdkPluginConfig`
1341
1342Configuration pour charger les plugins dans le SDK.
1343
1344```python theme={null}
1345class SdkPluginConfig(TypedDict):
1346 type: Literal["local"]
1347 path: str
1348```
1349
1350| Champ | Type | Description |
1351| :----- | :----------------- | :------------------------------------------------------------------------- |
1352| `type` | `Literal["local"]` | Doit être `"local"` (seuls les plugins locaux sont actuellement supportés) |
1353| `path` | `str` | Chemin absolu ou relatif vers le répertoire du plugin |
1354
1355**Exemple :**
1356
1357```python theme={null}
1358plugins = [
1359 {"type": "local", "path": "./my-plugin"},
1360 {"type": "local", "path": "/absolute/path/to/plugin"},
1361]
1362```
1363
1364Pour des informations complètes sur la création et l'utilisation de plugins, voir [Plugins](/fr/agent-sdk/plugins).
1365
1366## Types de messages
1367
1368### `Message`
1369
1370Type union de tous les messages possibles.
1371
1372```python theme={null}
1373Message = (
1374 UserMessage
1375 | AssistantMessage
1376 | SystemMessage
1377 | ResultMessage
1378 | StreamEvent
1379 | RateLimitEvent
1380)
1381```
1382
1383### `UserMessage`
1384
1385Message d'entrée utilisateur.
1386
1387```python theme={null}
1388@dataclass
1389class UserMessage:
1390 content: str | list[ContentBlock]
1391 uuid: str | None = None
1392 parent_tool_use_id: str | None = None
1393 tool_use_result: dict[str, Any] | None = None
1394```
1395
1396| Champ | Type | Description |
1397| :------------------- | :-------------------------- | :------------------------------------------------------------------------- |
1398| `content` | `str \| list[ContentBlock]` | Contenu du message sous forme de texte ou de blocs de contenu |
1399| `uuid` | `str \| None` | Identifiant de message unique |
1400| `parent_tool_use_id` | `str \| None` | ID d'utilisation d'outil si ce message est une réponse de résultat d'outil |
1401| `tool_use_result` | `dict[str, Any] \| None` | Données de résultat d'outil si applicable |
1402
1403### `AssistantMessage`
1404
1405Message de réponse d'assistant avec blocs de contenu.
1406
1407```python theme={null}
1408@dataclass
1409class AssistantMessage:
1410 content: list[ContentBlock]
1411 model: str
1412 parent_tool_use_id: str | None = None
1413 error: AssistantMessageError | None = None
1414 usage: dict[str, Any] | None = None
1415 message_id: str | None = None
1416```
1417
1418| Champ | Type | Description |
1419| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
1420| `content` | `list[ContentBlock]` | Liste des blocs de contenu dans la réponse |
1421| `model` | `str` | Modèle qui a généré la réponse |
1422| `parent_tool_use_id` | `str \| None` | ID d'utilisation d'outil si c'est une réponse imbriquée |
1423| `error` | [`AssistantMessageError`](#assistant-message-error) ` \| None` | Type d'erreur si la réponse a rencontré une erreur |
1424| `usage` | `dict[str, Any] \| None` | Utilisation de tokens par message (mêmes clés que [`ResultMessage.usage`](#result-message)) |
1425| `message_id` | `str \| None` | ID de message API. Plusieurs messages d'un tour partagent le même ID |
1426
1427### `AssistantMessageError`
1428
1429Types d'erreur possibles pour les messages d'assistant.
1430
1431```python theme={null}
1432AssistantMessageError = Literal[
1433 "authentication_failed",
1434 "billing_error",
1435 "rate_limit",
1436 "invalid_request",
1437 "server_error",
1438 "max_output_tokens",
1439 "unknown",
1440]
1441```
1442
1443### `SystemMessage`
1444
1445Message système avec métadonnées.
1446
1447```python theme={null}
1448@dataclass
1449class SystemMessage:
1450 subtype: str
1451 data: dict[str, Any]
1452```
1453
1454### `ResultMessage`
1455
1456Message de résultat final avec informations de coût et d'utilisation.
1457
1458```python theme={null}
1459@dataclass
1460class ResultMessage:
1461 subtype: str
1462 duration_ms: int
1463 duration_api_ms: int
1464 is_error: bool
1465 num_turns: int
1466 session_id: str
1467 total_cost_usd: float | None = None
1468 usage: dict[str, Any] | None = None
1469 result: str | None = None
1470 stop_reason: str | None = None
1471 structured_output: Any = None
1472 model_usage: dict[str, Any] | None = None
1473```
1474
1475Le dict `usage` contient les clés suivantes quand présentes :
1476
1477| Clé | Type | Description |
1478| ----------------------------- | ----- | --------------------------------------------------------- |
1479| `input_tokens` | `int` | Tokens d'entrée totaux consommés. |
1480| `output_tokens` | `int` | Tokens de sortie totaux générés. |
1481| `cache_creation_input_tokens` | `int` | Tokens utilisés pour créer de nouvelles entrées de cache. |
1482| `cache_read_input_tokens` | `int` | Tokens lus à partir des entrées de cache existantes. |
1483
1484Le dict `model_usage` mappe les noms de modèles à l'utilisation par modèle. Les clés du dict interne utilisent camelCase parce que la valeur est passée inchangée du processus CLI sous-jacent, correspondant au type TypeScript [`ModelUsage`](/fr/agent-sdk/typescript#model-usage) :
1485
1486| Clé | Type | Description |
1487| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
1488| `inputTokens` | `int` | Tokens d'entrée pour ce modèle. |
1489| `outputTokens` | `int` | Tokens de sortie pour ce modèle. |
1490| `cacheReadInputTokens` | `int` | Tokens de lecture de cache pour ce modèle. |
1491| `cacheCreationInputTokens` | `int` | Tokens de création de cache pour ce modèle. |
1492| `webSearchRequests` | `int` | Requêtes de recherche web effectuées par ce modèle. |
1493| `costUSD` | `float` | Coût estimé en USD pour ce modèle, calculé côté client. Voir [Track cost and usage](/fr/agent-sdk/cost-tracking) pour les avertissements de facturation. |
1494| `contextWindow` | `int` | Taille de la fenêtre de contexte pour ce modèle. |
1495| `maxOutputTokens` | `int` | Limite de tokens de sortie maximum pour ce modèle. |
1496
1497### `StreamEvent`
1498
1499Événement de flux pour les mises à jour de messages partiels pendant le streaming. Reçu uniquement quand `include_partial_messages=True` dans `ClaudeAgentOptions`. Importez via `from claude_agent_sdk.types import StreamEvent`.
1500
1501```python theme={null}
1502@dataclass
1503class StreamEvent:
1504 uuid: str
1505 session_id: str
1506 event: dict[str, Any] # The raw Claude API stream event
1507 parent_tool_use_id: str | None = None
1508```
1509
1510| Champ | Type | Description |
1511| :------------------- | :--------------- | :------------------------------------------------------------------------ |
1512| `uuid` | `str` | Identifiant unique pour cet événement |
1513| `session_id` | `str` | Identifiant de session |
1514| `event` | `dict[str, Any]` | Les données d'événement de flux Claude API brutes |
1515| `parent_tool_use_id` | `str \| None` | ID d'utilisation d'outil parent si cet événement provient d'un sous-agent |
1516
1517### `RateLimitEvent`
1518
1519Émis quand le statut de limite de débit change (par exemple, de `"allowed"` à `"allowed_warning"`). Utilisez ceci pour avertir les utilisateurs avant qu'ils ne frappent une limite dure, ou pour reculer quand le statut est `"rejected"`.
1520
1521```python theme={null}
1522@dataclass
1523class RateLimitEvent:
1524 rate_limit_info: RateLimitInfo
1525 uuid: str
1526 session_id: str
1527```
1528
1529| Champ | Type | Description |
1530| :---------------- | :---------------------------------- | :-------------------------------- |
1531| `rate_limit_info` | [`RateLimitInfo`](#rate-limit-info) | État actuel de la limite de débit |
1532| `uuid` | `str` | Identifiant d'événement unique |
1533| `session_id` | `str` | Identifiant de session |
1534
1535### `RateLimitInfo`
1536
1537État de limite de débit porté par [`RateLimitEvent`](#rate-limit-event).
1538
1539```python theme={null}
1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
1541RateLimitType = Literal[
1542 "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage"
1543]
1544
1545
1546@dataclass
1547class RateLimitInfo:
1548 status: RateLimitStatus
1549 resets_at: int | None = None
1550 rate_limit_type: RateLimitType | None = None
1551 utilization: float | None = None
1552 overage_status: RateLimitStatus | None = None
1553 overage_resets_at: int | None = None
1554 overage_disabled_reason: str | None = None
1555 raw: dict[str, Any] = field(default_factory=dict)
1556```
1557
1558| Champ | Type | Description |
1559| :------------------------ | :------------------------ | :------------------------------------------------------------------------------------------------------------------- |
1560| `status` | `RateLimitStatus` | Statut actuel. `"allowed_warning"` signifie approcher la limite ; `"rejected"` signifie que la limite a été atteinte |
1561| `resets_at` | `int \| None` | Timestamp Unix quand la fenêtre de limite de débit se réinitialise |
1562| `rate_limit_type` | `RateLimitType \| None` | Quelle fenêtre de limite de débit s'applique |
1563| `utilization` | `float \| None` | Fraction de la limite de débit consommée (0.0 à 1.0) |
1564| `overage_status` | `RateLimitStatus \| None` | Statut de l'utilisation de dépassement à l'usage, si applicable |
1565| `overage_resets_at` | `int \| None` | Timestamp Unix quand la fenêtre de dépassement se réinitialise |
1566| `overage_disabled_reason` | `str \| None` | Pourquoi le dépassement est indisponible, si le statut est `"rejected"` |
1567| `raw` | `dict[str, Any]` | Dict brut complet du CLI, incluant les champs non modélisés ci-dessus |
1568
1569### `TaskStartedMessage`
1570
1571Émis quand une tâche de fond démarre. Une tâche de fond est tout ce qui est suivi en dehors du tour principal : une commande Bash en arrière-plan, une montre [Monitor](#monitor), un sous-agent généré via l'outil Agent, ou un agent distant. Le champ `task_type` vous dit lequel. Ce nommage n'est pas lié au renommage de l'outil `Task`-à-`Agent`.
1572
1573```python theme={null}
1574@dataclass
1575class TaskStartedMessage(SystemMessage):
1576 task_id: str
1577 description: str
1578 uuid: str
1579 session_id: str
1580 tool_use_id: str | None = None
1581 task_type: str | None = None
1582```
1583
1584| Champ | Type | Description |
1585| :------------ | :------------ | :--------------------------------------------------------------------------------------------------------------------------------- |
1586| `task_id` | `str` | Identifiant unique pour la tâche |
1587| `description` | `str` | Description de la tâche |
1588| `uuid` | `str` | Identifiant de message unique |
1589| `session_id` | `str` | Identifiant de session |
1590| `tool_use_id` | `str \| None` | ID d'utilisation d'outil associé |
1591| `task_type` | `str \| None` | Quel type de tâche de fond : `"local_bash"` pour Bash en arrière-plan et les montres Monitor, `"local_agent"`, ou `"remote_agent"` |
1592
1593### `TaskUsage`
1594
1595Données de tokens et de timing pour une tâche de fond.
1596
1597```python theme={null}
1598class TaskUsage(TypedDict):
1599 total_tokens: int
1600 tool_uses: int
1601 duration_ms: int
1602```
1603
1604### `TaskProgressMessage`
1605
1606Émis périodiquement avec les mises à jour de progression pour une tâche de fond en cours d'exécution.
1607
1608```python theme={null}
1609@dataclass
1610class TaskProgressMessage(SystemMessage):
1611 task_id: str
1612 description: str
1613 usage: TaskUsage
1614 uuid: str
1615 session_id: str
1616 tool_use_id: str | None = None
1617 last_tool_name: str | None = None
1618```
1619
1620| Champ | Type | Description |
1621| :--------------- | :------------ | :----------------------------------------------------- |
1622| `task_id` | `str` | Identifiant unique pour la tâche |
1623| `description` | `str` | Description du statut actuel |
1624| `usage` | `TaskUsage` | Utilisation de tokens pour cette tâche jusqu'à présent |
1625| `uuid` | `str` | Identifiant de message unique |
1626| `session_id` | `str` | Identifiant de session |
1627| `tool_use_id` | `str \| None` | ID d'utilisation d'outil associé |
1628| `last_tool_name` | `str \| None` | Nom du dernier outil utilisé par la tâche |
1629
1630### `TaskNotificationMessage`
1631
1632Émis quand une tâche de fond se termine, échoue, ou est arrêtée. Les tâches de fond incluent les commandes Bash `run_in_background`, les montres Monitor, et les sous-agents en arrière-plan.
1633
1634```python theme={null}
1635@dataclass
1636class TaskNotificationMessage(SystemMessage):
1637 task_id: str
1638 status: TaskNotificationStatus # "completed" | "failed" | "stopped"
1639 output_file: str
1640 summary: str
1641 uuid: str
1642 session_id: str
1643 tool_use_id: str | None = None
1644 usage: TaskUsage | None = None
1645```
1646
1647| Champ | Type | Description |
1648| :------------ | :----------------------- | :------------------------------------------------ |
1649| `task_id` | `str` | Identifiant unique pour la tâche |
1650| `status` | `TaskNotificationStatus` | L'un de `"completed"`, `"failed"`, ou `"stopped"` |
1651| `output_file` | `str` | Chemin vers le fichier de sortie de la tâche |
1652| `summary` | `str` | Résumé du résultat de la tâche |
1653| `uuid` | `str` | Identifiant de message unique |
1654| `session_id` | `str` | Identifiant de session |
1655| `tool_use_id` | `str \| None` | ID d'utilisation d'outil associé |
1656| `usage` | `TaskUsage \| None` | Utilisation de tokens finale pour la tâche |
1657
1658## Types de blocs de contenu
1659
1660### `ContentBlock`
1661
1662Type union de tous les blocs de contenu.
1663
1664```python theme={null}
1665ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
1666```
1667
1668### `TextBlock`
1669
1670Bloc de contenu texte.
1671
1672```python theme={null}
1673@dataclass
1674class TextBlock:
1675 text: str
1676```
1677
1678### `ThinkingBlock`
1679
1680Bloc de contenu de réflexion (pour les modèles avec capacité de réflexion).
1681
1682```python theme={null}
1683@dataclass
1684class ThinkingBlock:
1685 thinking: str
1686 signature: str
1687```
1688
1689### `ToolUseBlock`
1690
1691Bloc de requête d'utilisation d'outil.
1692
1693```python theme={null}
1694@dataclass
1695class ToolUseBlock:
1696 id: str
1697 name: str
1698 input: dict[str, Any]
1699```
1700
1701### `ToolResultBlock`
1702
1703Bloc de résultat d'exécution d'outil.
1704
1705```python theme={null}
1706@dataclass
1707class ToolResultBlock:
1708 tool_use_id: str
1709 content: str | list[dict[str, Any]] | None = None
1710 is_error: bool | None = None
1711```
1712
1713## Types d'erreur
1714
1715### `ClaudeSDKError`
1716
1717Classe d'exception de base pour toutes les erreurs du SDK.
1718
1719```python theme={null}
1720class ClaudeSDKError(Exception):
1721 """Base error for Claude SDK."""
1722```
1723
1724### `CLINotFoundError`
1725
1726Levée quand Claude Code CLI n'est pas installé ou introuvable.
1727
1728```python theme={null}
1729class CLINotFoundError(CLIConnectionError):
1730 def __init__(
1731 self, message: str = "Claude Code not found", cli_path: str | None = None
1732 ):
1733 """
1734 Args:
1735 message: Error message (default: "Claude Code not found")
1736 cli_path: Optional path to the CLI that was not found
1737 """
1738```
1739
1740### `CLIConnectionError`
1741
1742Levée quand la connexion à Claude Code échoue.
1743
1744```python theme={null}
1745class CLIConnectionError(ClaudeSDKError):
1746 """Failed to connect to Claude Code."""
1747```
1748
1749### `ProcessError`
1750
1751Levée quand le processus Claude Code échoue.
1752
1753```python theme={null}
1754class ProcessError(ClaudeSDKError):
1755 def __init__(
1756 self, message: str, exit_code: int | None = None, stderr: str | None = None
1757 ):
1758 self.exit_code = exit_code
1759 self.stderr = stderr
1760```
1761
1762### `CLIJSONDecodeError`
1763
1764Levée quand l'analyse JSON échoue.
1765
1766```python theme={null}
1767class CLIJSONDecodeError(ClaudeSDKError):
1768 def __init__(self, line: str, original_error: Exception):
1769 """
1770 Args:
1771 line: The line that failed to parse
1772 original_error: The original JSON decode exception
1773 """
1774 self.line = line
1775 self.original_error = original_error
1776```
1777
1778## Types de hooks
1779
1780Pour un guide complet sur l'utilisation des hooks avec des exemples et des modèles courants, voir le [guide Hooks](/fr/agent-sdk/hooks).
1781
1782### `HookEvent`
1783
1784Types d'événements de hook supportés.
1785
1786```python theme={null}
1787HookEvent = Literal[
1788 "PreToolUse", # Called before tool execution
1789 "PostToolUse", # Called after tool execution
1790 "PostToolUseFailure", # Called when a tool execution fails
1791 "UserPromptSubmit", # Called when user submits a prompt
1792 "Stop", # Called when stopping execution
1793 "SubagentStop", # Called when a subagent stops
1794 "PreCompact", # Called before message compaction
1795 "Notification", # Called for notification events
1796 "SubagentStart", # Called when a subagent starts
1797 "PermissionRequest", # Called when a permission decision is needed
1798]
1799```
1800
1801<Note>
1802 Le SDK TypeScript supporte des événements de hook supplémentaires non encore disponibles en Python : `SessionStart`, `SessionEnd`, `Setup`, `TeammateIdle`, `TaskCompleted`, `ConfigChange`, `WorktreeCreate`, `WorktreeRemove`, et `PostToolBatch`.
1803</Note>
1804
1805### `HookCallback`
1806
1807Définition de type pour les fonctions de callback de hook.
1808
1809```python theme={null}
1810HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]
1811```
1812
1813Paramètres :
1814
1815* `input` : Entrée de hook fortement typée avec unions discriminées basées sur `hook_event_name` (voir [`HookInput`](#hook-input))
1816* `tool_use_id` : Identifiant d'utilisation d'outil optionnel (pour les hooks liés aux outils)
1817* `context` : Contexte de hook avec des informations supplémentaires
1818
1819Retourne un [`HookJSONOutput`](#hook-json-output) qui peut contenir :
1820
1821* `decision` : `"block"` pour bloquer l'action
1822* `systemMessage` : Message système à ajouter à la transcription
1823* `hookSpecificOutput` : Données de sortie spécifiques au hook
1824
1825### `HookContext`
1826
1827Informations de contexte passées aux callbacks de hook.
1828
1829```python theme={null}
1830class HookContext(TypedDict):
1831 signal: Any | None # Future: abort signal support
1832```
1833
1834### `HookMatcher`
1835
1836Configuration pour faire correspondre les hooks à des événements ou des outils spécifiques.
1837
1838```python theme={null}
1839@dataclass
1840class HookMatcher:
1841 matcher: str | None = (
1842 None # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
1843 )
1844 hooks: list[HookCallback] = field(
1845 default_factory=list
1846 ) # List of callbacks to execute
1847 timeout: float | None = (
1848 None # Timeout in seconds for all hooks in this matcher (default: 60)
1849 )
1850```
1851
1852### `HookInput`
1853
1854Type union de tous les types d'entrée de hook. Le type réel dépend du champ `hook_event_name`.
1855
1856```python theme={null}
1857HookInput = (
1858 PreToolUseHookInput
1859 | PostToolUseHookInput
1860 | PostToolUseFailureHookInput
1861 | UserPromptSubmitHookInput
1862 | StopHookInput
1863 | SubagentStopHookInput
1864 | PreCompactHookInput
1865 | NotificationHookInput
1866 | SubagentStartHookInput
1867 | PermissionRequestHookInput
1868)
1869```
1870
1871### `BaseHookInput`
1872
1873Champs de base présents dans tous les types d'entrée de hook.
1874
1875```python theme={null}
1876class BaseHookInput(TypedDict):
1877 session_id: str
1878 transcript_path: str
1879 cwd: str
1880 permission_mode: NotRequired[str]
1881```
1882
1883| Champ | Type | Description |
1884| :---------------- | :---------------- | :------------------------------------------------- |
1885| `session_id` | `str` | Identifiant de session actuel |
1886| `transcript_path` | `str` | Chemin vers le fichier de transcription de session |
1887| `cwd` | `str` | Répertoire de travail actuel |
1888| `permission_mode` | `str` (optionnel) | Mode de permission actuel |
1889
1890### `PreToolUseHookInput`
1891
1892Données d'entrée pour les événements de hook `PreToolUse`.
1893
1894```python theme={null}
1895class PreToolUseHookInput(BaseHookInput):
1896 hook_event_name: Literal["PreToolUse"]
1897 tool_name: str
1898 tool_input: dict[str, Any]
1899 tool_use_id: str
1900 agent_id: NotRequired[str]
1901 agent_type: NotRequired[str]
1902```
1903
1904| Champ | Type | Description |
1905| :---------------- | :---------------------- | :------------------------------------------------------------------------------------------ |
1906| `hook_event_name` | `Literal["PreToolUse"]` | Toujours « PreToolUse » |
1907| `tool_name` | `str` | Nom de l'outil sur le point d'être exécuté |
1908| `tool_input` | `dict[str, Any]` | Paramètres d'entrée pour l'outil |
1909| `tool_use_id` | `str` | Identifiant unique pour cette utilisation d'outil |
1910| `agent_id` | `str` (optionnel) | Identifiant de sous-agent, présent quand le hook se déclenche à l'intérieur d'un sous-agent |
1911| `agent_type` | `str` (optionnel) | Type de sous-agent, présent quand le hook se déclenche à l'intérieur d'un sous-agent |
1912
1913### `PostToolUseHookInput`
1914
1915Données d'entrée pour les événements de hook `PostToolUse`.
1916
1917```python theme={null}
1918class PostToolUseHookInput(BaseHookInput):
1919 hook_event_name: Literal["PostToolUse"]
1920 tool_name: str
1921 tool_input: dict[str, Any]
1922 tool_response: Any
1923 tool_use_id: str
1924 agent_id: NotRequired[str]
1925 agent_type: NotRequired[str]
1926```
1927
1928| Champ | Type | Description |
1929| :---------------- | :----------------------- | :------------------------------------------------------------------------------------------ |
1930| `hook_event_name` | `Literal["PostToolUse"]` | Toujours « PostToolUse » |
1931| `tool_name` | `str` | Nom de l'outil qui a été exécuté |
1932| `tool_input` | `dict[str, Any]` | Paramètres d'entrée qui ont été utilisés |
1933| `tool_response` | `Any` | Réponse de l'exécution de l'outil |
1934| `tool_use_id` | `str` | Identifiant unique pour cette utilisation d'outil |
1935| `agent_id` | `str` (optionnel) | Identifiant de sous-agent, présent quand le hook se déclenche à l'intérieur d'un sous-agent |
1936| `agent_type` | `str` (optionnel) | Type de sous-agent, présent quand le hook se déclenche à l'intérieur d'un sous-agent |
1937
1938### `PostToolUseFailureHookInput`
1939
1940Données d'entrée pour les événements de hook `PostToolUseFailure`. Appelé quand l'exécution d'un outil échoue.
1941
1942```python theme={null}
1943class PostToolUseFailureHookInput(BaseHookInput):
1944 hook_event_name: Literal["PostToolUseFailure"]
1945 tool_name: str
1946 tool_input: dict[str, Any]
1947 tool_use_id: str
1948 error: str
1949 is_interrupt: NotRequired[bool]
1950 agent_id: NotRequired[str]
1951 agent_type: NotRequired[str]
1952```
1953
1954| Champ | Type | Description |
1955| :---------------- | :------------------------------ | :------------------------------------------------------------------------------------------ |
1956| `hook_event_name` | `Literal["PostToolUseFailure"]` | Toujours « PostToolUseFailure » |
1957| `tool_name` | `str` | Nom de l'outil qui a échoué |
1958| `tool_input` | `dict[str, Any]` | Paramètres d'entrée qui ont été utilisés |
1959| `tool_use_id` | `str` | Identifiant unique pour cette utilisation d'outil |
1960| `error` | `str` | Message d'erreur de l'exécution échouée |
1961| `is_interrupt` | `bool` (optionnel) | Si l'échec a été causé par une interruption |
1962| `agent_id` | `str` (optionnel) | Identifiant de sous-agent, présent quand le hook se déclenche à l'intérieur d'un sous-agent |
1963| `agent_type` | `str` (optionnel) | Type de sous-agent, présent quand le hook se déclenche à l'intérieur d'un sous-agent |
1964
1965### `UserPromptSubmitHookInput`
1966
1967Données d'entrée pour les événements de hook `UserPromptSubmit`.
1968
1969```python theme={null}
1970class UserPromptSubmitHookInput(BaseHookInput):
1971 hook_event_name: Literal["UserPromptSubmit"]
1972 prompt: str
1973```
1974
1975| Champ | Type | Description |
1976| :---------------- | :---------------------------- | :--------------------------------- |
1977| `hook_event_name` | `Literal["UserPromptSubmit"]` | Toujours « UserPromptSubmit » |
1978| `prompt` | `str` | Le prompt soumis par l'utilisateur |
1979
1980### `StopHookInput`
1981
1982Données d'entrée pour les événements de hook `Stop`.
1983
1984```python theme={null}
1985class StopHookInput(BaseHookInput):
1986 hook_event_name: Literal["Stop"]
1987 stop_hook_active: bool
1988```
1989
1990| Champ | Type | Description |
1991| :----------------- | :---------------- | :--------------------------- |
1992| `hook_event_name` | `Literal["Stop"]` | Toujours « Stop » |
1993| `stop_hook_active` | `bool` | Si le hook d'arrêt est actif |
1994
1995### `SubagentStopHookInput`
1996
1997Données d'entrée pour les événements de hook `SubagentStop`.
1998
1999```python theme={null}
2000class SubagentStopHookInput(BaseHookInput):
2001 hook_event_name: Literal["SubagentStop"]
2002 stop_hook_active: bool
2003 agent_id: str
2004 agent_transcript_path: str
2005 agent_type: str
2006```
2007
2008| Champ | Type | Description |
2009| :---------------------- | :------------------------ | :---------------------------------------------------- |
2010| `hook_event_name` | `Literal["SubagentStop"]` | Toujours « SubagentStop » |
2011| `stop_hook_active` | `bool` | Si le hook d'arrêt est actif |
2012| `agent_id` | `str` | Identifiant unique pour le sous-agent |
2013| `agent_transcript_path` | `str` | Chemin vers le fichier de transcription du sous-agent |
2014| `agent_type` | `str` | Type du sous-agent |
2015
2016### `PreCompactHookInput`
2017
2018Données d'entrée pour les événements de hook `PreCompact`.
2019
2020```python theme={null}
2021class PreCompactHookInput(BaseHookInput):
2022 hook_event_name: Literal["PreCompact"]
2023 trigger: Literal["manual", "auto"]
2024 custom_instructions: str | None
2025```
2026
2027| Champ | Type | Description |
2028| :-------------------- | :-------------------------- | :--------------------------------------------- |
2029| `hook_event_name` | `Literal["PreCompact"]` | Toujours « PreCompact » |
2030| `trigger` | `Literal["manual", "auto"]` | Ce qui a déclenché la compaction |
2031| `custom_instructions` | `str \| None` | Instructions personnalisées pour la compaction |
2032
2033### `NotificationHookInput`
2034
2035Données d'entrée pour les événements de hook `Notification`.
2036
2037```python theme={null}
2038class NotificationHookInput(BaseHookInput):
2039 hook_event_name: Literal["Notification"]
2040 message: str
2041 title: NotRequired[str]
2042 notification_type: str
2043```
2044
2045| Champ | Type | Description |
2046| :------------------ | :------------------------ | :--------------------------------- |
2047| `hook_event_name` | `Literal["Notification"]` | Toujours « Notification » |
2048| `message` | `str` | Contenu du message de notification |
2049| `title` | `str` (optionnel) | Titre de la notification |
2050| `notification_type` | `str` | Type de notification |
2051
2052### `SubagentStartHookInput`
2053
2054Données d'entrée pour les événements de hook `SubagentStart`.
2055
2056```python theme={null}
2057class SubagentStartHookInput(BaseHookInput):
2058 hook_event_name: Literal["SubagentStart"]
2059 agent_id: str
2060 agent_type: str
2061```
2062
2063| Champ | Type | Description |
2064| :---------------- | :------------------------- | :------------------------------------ |
2065| `hook_event_name` | `Literal["SubagentStart"]` | Toujours « SubagentStart » |
2066| `agent_id` | `str` | Identifiant unique pour le sous-agent |
2067| `agent_type` | `str` | Type du sous-agent |
2068
2069### `PermissionRequestHookInput`
2070
2071Données d'entrée pour les événements de hook `PermissionRequest`. Permet aux hooks de gérer les décisions de permission programmatiquement.
2072
2073```python theme={null}
2074class PermissionRequestHookInput(BaseHookInput):
2075 hook_event_name: Literal["PermissionRequest"]
2076 tool_name: str
2077 tool_input: dict[str, Any]
2078 permission_suggestions: NotRequired[list[Any]]
2079```
2080
2081| Champ | Type | Description |
2082| :----------------------- | :----------------------------- | :------------------------------------------ |
2083| `hook_event_name` | `Literal["PermissionRequest"]` | Toujours « PermissionRequest » |
2084| `tool_name` | `str` | Nom de l'outil demandant la permission |
2085| `tool_input` | `dict[str, Any]` | Paramètres d'entrée pour l'outil |
2086| `permission_suggestions` | `list[Any]` (optionnel) | Mises à jour de permission suggérées du CLI |
2087
2088### `HookJSONOutput`
2089
2090Type union pour les valeurs de retour de callback de hook.
2091
2092```python theme={null}
2093HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput
2094```
2095
2096#### `SyncHookJSONOutput`
2097
2098Sortie de hook synchrone avec champs de contrôle et de décision.
2099
2100```python theme={null}
2101class SyncHookJSONOutput(TypedDict):
2102 # Control fields
2103 continue_: NotRequired[bool] # Whether to proceed (default: True)
2104 suppressOutput: NotRequired[bool] # Hide stdout from transcript
2105 stopReason: NotRequired[str] # Message when continue is False
2106
2107 # Decision fields
2108 decision: NotRequired[Literal["block"]]
2109 systemMessage: NotRequired[str] # Warning message for user
2110 reason: NotRequired[str] # Feedback for Claude
2111
2112 # Hook-specific output
2113 hookSpecificOutput: NotRequired[HookSpecificOutput]
2114```
2115
2116<Note>
2117 Utilisez `continue_` (avec trait de soulignement) dans le code Python. Il est automatiquement converti en `continue` quand envoyé au CLI.
2118</Note>
2119
2120#### `HookSpecificOutput`
2121
2122Un `TypedDict` contenant le nom d'événement de hook et les champs spécifiques à l'événement. La forme dépend de la valeur `hookEventName`. Pour les détails complets sur les champs disponibles par événement de hook, voir [Control execution with hooks](/fr/agent-sdk/hooks#outputs).
2123
2124Une union discriminée de types de sortie spécifiques à l'événement. Le champ `hookEventName` détermine quels champs sont valides.
2125
2126```python theme={null}
2127class PreToolUseHookSpecificOutput(TypedDict):
2128 hookEventName: Literal["PreToolUse"]
2129 permissionDecision: NotRequired[Literal["allow", "deny", "ask"]]
2130 permissionDecisionReason: NotRequired[str]
2131 updatedInput: NotRequired[dict[str, Any]]
2132 additionalContext: NotRequired[str]
2133
2134
2135class PostToolUseHookSpecificOutput(TypedDict):
2136 hookEventName: Literal["PostToolUse"]
2137 additionalContext: NotRequired[str]
2138 updatedMCPToolOutput: NotRequired[Any]
2139
2140
2141class PostToolUseFailureHookSpecificOutput(TypedDict):
2142 hookEventName: Literal["PostToolUseFailure"]
2143 additionalContext: NotRequired[str]
2144
2145
2146class UserPromptSubmitHookSpecificOutput(TypedDict):
2147 hookEventName: Literal["UserPromptSubmit"]
2148 additionalContext: NotRequired[str]
2149
2150
2151class NotificationHookSpecificOutput(TypedDict):
2152 hookEventName: Literal["Notification"]
2153 additionalContext: NotRequired[str]
2154
2155
2156class SubagentStartHookSpecificOutput(TypedDict):
2157 hookEventName: Literal["SubagentStart"]
2158 additionalContext: NotRequired[str]
2159
2160
2161class PermissionRequestHookSpecificOutput(TypedDict):
2162 hookEventName: Literal["PermissionRequest"]
2163 decision: dict[str, Any]
2164
2165
2166HookSpecificOutput = (
2167 PreToolUseHookSpecificOutput
2168 | PostToolUseHookSpecificOutput
2169 | PostToolUseFailureHookSpecificOutput
2170 | UserPromptSubmitHookSpecificOutput
2171 | NotificationHookSpecificOutput
2172 | SubagentStartHookSpecificOutput
2173 | PermissionRequestHookSpecificOutput
2174)
2175```
2176
2177#### `AsyncHookJSONOutput`
2178
2179Sortie de hook asynchrone qui diffère l'exécution du hook.
2180
2181```python theme={null}
2182class AsyncHookJSONOutput(TypedDict):
2183 async_: Literal[True] # Set to True to defer execution
2184 asyncTimeout: NotRequired[int] # Timeout in milliseconds
2185```
2186
2187<Note>
2188 Utilisez `async_` (avec trait de soulignement) dans le code Python. Il est automatiquement converti en `async` quand envoyé au CLI.
2189</Note>
2190
2191### Exemple d'utilisation de hook
2192
2193Cet exemple enregistre deux hooks : l'un qui bloque les commandes bash dangereuses comme `rm -rf /`, et un autre qui enregistre toute l'utilisation d'outils pour l'audit. Le hook de sécurité s'exécute uniquement sur les commandes Bash (via le `matcher`), tandis que le hook de journalisation s'exécute sur tous les outils.
2194
2195```python theme={null}
2196from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext
2197from typing import Any
2198
2199
2200async def validate_bash_command(
2201 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2202) -> dict[str, Any]:
2203 """Validate and potentially block dangerous bash commands."""
2204 if input_data["tool_name"] == "Bash":
2205 command = input_data["tool_input"].get("command", "")
2206 if "rm -rf /" in command:
2207 return {
2208 "hookSpecificOutput": {
2209 "hookEventName": "PreToolUse",
2210 "permissionDecision": "deny",
2211 "permissionDecisionReason": "Dangerous command blocked",
2212 }
2213 }
2214 return {}
2215
2216
2217async def log_tool_use(
2218 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2219) -> dict[str, Any]:
2220 """Log all tool usage for auditing."""
2221 print(f"Tool used: {input_data.get('tool_name')}")
2222 return {}
2223
2224
2225options = ClaudeAgentOptions(
2226 hooks={
2227 "PreToolUse": [
2228 HookMatcher(
2229 matcher="Bash", hooks=[validate_bash_command], timeout=120
2230 ), # 2 min for validation
2231 HookMatcher(
2232 hooks=[log_tool_use]
2233 ), # Applies to all tools (default 60s timeout)
2234 ],
2235 "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
2236 }
2237)
2238
2239async for message in query(prompt="Analyze this codebase", options=options):
2240 print(message)
2241```
2242
2243## Types d'entrée/sortie d'outil
2244
2245Documentation des schémas d'entrée/sortie pour tous les outils Claude Code intégrés. Bien que le SDK Python n'exporte pas ceux-ci en tant que types, ils représentent la structure des entrées et sorties d'outils dans les messages.
2246
2247### Agent
2248
2249**Nom de l'outil :** `Agent` (précédemment `Task`, qui est toujours accepté comme alias)
2250
2251**Entrée :**
2252
2253```python theme={null}
2254{
2255 "description": str, # A short (3-5 word) description of the task
2256 "prompt": str, # The task for the agent to perform
2257 "subagent_type": str, # The type of specialized agent to use
2258}
2259```
2260
2261**Sortie :**
2262
2263```python theme={null}
2264{
2265 "result": str, # Final result from the subagent
2266 "usage": dict | None, # Token usage statistics
2267 "total_cost_usd": float | None, # Estimated total cost in USD
2268 "duration_ms": int | None, # Execution duration in milliseconds
2269}
2270```
2271
2272### AskUserQuestion
2273
2274**Nom de l'outil :** `AskUserQuestion`
2275
2276Pose des questions de clarification à l'utilisateur pendant l'exécution. Voir [Handle approvals and user input](/fr/agent-sdk/user-input#handle-clarifying-questions) pour les détails d'utilisation.
2277
2278**Entrée :**
2279
2280```python theme={null}
2281{
2282 "questions": [ # Questions to ask the user (1-4 questions)
2283 {
2284 "question": str, # The complete question to ask the user
2285 "header": str, # Very short label displayed as a chip/tag (max 12 chars)
2286 "options": [ # The available choices (2-4 options)
2287 {
2288 "label": str, # Display text for this option (1-5 words)
2289 "description": str, # Explanation of what this option means
2290 }
2291 ],
2292 "multiSelect": bool, # Set to true to allow multiple selections
2293 }
2294 ],
2295 "answers": dict | None, # User answers populated by the permission system
2296}
2297```
2298
2299**Sortie :**
2300
2301```python theme={null}
2302{
2303 "questions": [ # The questions that were asked
2304 {
2305 "question": str,
2306 "header": str,
2307 "options": [{"label": str, "description": str}],
2308 "multiSelect": bool,
2309 }
2310 ],
2311 "answers": dict[str, str], # Maps question text to answer string
2312 # Multi-select answers are comma-separated
2313}
2314```
2315
2316### Bash
2317
2318**Nom de l'outil :** `Bash`
2319
2320**Entrée :**
2321
2322```python theme={null}
2323{
2324 "command": str, # The command to execute
2325 "timeout": int | None, # Optional timeout in milliseconds (max 600000)
2326 "description": str | None, # Clear, concise description (5-10 words)
2327 "run_in_background": bool | None, # Set to true to run in background
2328}
2329```
2330
2331**Sortie :**
2332
2333```python theme={null}
2334{
2335 "output": str, # Combined stdout and stderr output
2336 "exitCode": int, # Exit code of the command
2337 "killed": bool | None, # Whether command was killed due to timeout
2338 "shellId": str | None, # Shell ID for background processes
2339}
2340```
2341
2342### Monitor
2343
2344**Nom de l'outil :** `Monitor`
2345
2346Exécute un script de fond et livre chaque ligne stdout à Claude comme un événement pour qu'il puisse réagir sans interrogation. Monitor suit les mêmes règles de permission que Bash. Voir la [référence de l'outil Monitor](/fr/tools-reference#monitor-tool) pour le comportement et la disponibilité du fournisseur.
2347
2348**Entrée :**
2349
2350```python theme={null}
2351{
2352 "command": str, # Shell script; each stdout line is an event, exit ends the watch
2353 "description": str, # Short description shown in notifications
2354 "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000)
2355 "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop
2356}
2357```
2358
2359**Sortie :**
2360
2361```python theme={null}
2362{
2363 "taskId": str, # ID of the background monitor task
2364 "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent)
2365 "persistent": bool | None, # True when running until TaskStop or session end
2366}
2367```
2368
2369### Edit
2370
2371**Nom de l'outil :** `Edit`
2372
2373**Entrée :**
2374
2375```python theme={null}
2376{
2377 "file_path": str, # The absolute path to the file to modify
2378 "old_string": str, # The text to replace
2379 "new_string": str, # The text to replace it with
2380 "replace_all": bool | None, # Replace all occurrences (default False)
2381}
2382```
2383
2384**Sortie :**
2385
2386```python theme={null}
2387{
2388 "message": str, # Confirmation message
2389 "replacements": int, # Number of replacements made
2390 "file_path": str, # File path that was edited
2391}
2392```
2393
2394### Read
2395
2396**Nom de l'outil :** `Read`
2397
2398**Entrée :**
2399
2400```python theme={null}
2401{
2402 "file_path": str, # The absolute path to the file to read
2403 "offset": int | None, # The line number to start reading from
2404 "limit": int | None, # The number of lines to read
2405}
2406```
2407
2408**Sortie (fichiers texte) :**
2409
2410```python theme={null}
2411{
2412 "content": str, # File contents with line numbers
2413 "total_lines": int, # Total number of lines in file
2414 "lines_returned": int, # Lines actually returned
2415}
2416```
2417
2418**Sortie (images) :**
2419
2420```python theme={null}
2421{
2422 "image": str, # Base64 encoded image data
2423 "mime_type": str, # Image MIME type
2424 "file_size": int, # File size in bytes
2425}
2426```
2427
2428### Write
2429
2430**Nom de l'outil :** `Write`
2431
2432**Entrée :**
2433
2434```python theme={null}
2435{
2436 "file_path": str, # The absolute path to the file to write
2437 "content": str, # The content to write to the file
2438}
2439```
2440
2441**Sortie :**
2442
2443```python theme={null}
2444{
2445 "message": str, # Success message
2446 "bytes_written": int, # Number of bytes written
2447 "file_path": str, # File path that was written
2448}
2449```
2450
2451### Glob
2452
2453**Nom de l'outil :** `Glob`
2454
2455**Entrée :**
2456
2457```python theme={null}
2458{
2459 "pattern": str, # The glob pattern to match files against
2460 "path": str | None, # The directory to search in (defaults to cwd)
2461}
2462```
2463
2464**Sortie :**
2465
2466```python theme={null}
2467{
2468 "matches": list[str], # Array of matching file paths
2469 "count": int, # Number of matches found
2470 "search_path": str, # Search directory used
2471}
2472```
2473
2474### Grep
2475
2476**Nom de l'outil :** `Grep`
2477
2478**Entrée :**
2479
2480```python theme={null}
2481{
2482 "pattern": str, # The regular expression pattern
2483 "path": str | None, # File or directory to search in
2484 "glob": str | None, # Glob pattern to filter files
2485 "type": str | None, # File type to search
2486 "output_mode": str | None, # "content", "files_with_matches", or "count"
2487 "-i": bool | None, # Case insensitive search
2488 "-n": bool | None, # Show line numbers
2489 "-B": int | None, # Lines to show before each match
2490 "-A": int | None, # Lines to show after each match
2491 "-C": int | None, # Lines to show before and after
2492 "head_limit": int | None, # Limit output to first N lines/entries
2493 "multiline": bool | None, # Enable multiline mode
2494}
2495```
2496
2497**Sortie (mode contenu) :**
2498
2499```python theme={null}
2500{
2501 "matches": [
2502 {
2503 "file": str,
2504 "line_number": int | None,
2505 "line": str,
2506 "before_context": list[str] | None,
2507 "after_context": list[str] | None,
2508 }
2509 ],
2510 "total_matches": int,
2511}
2512```
2513
2514**Sortie (mode fichiers\_avec\_correspondances) :**
2515
2516```python theme={null}
2517{
2518 "files": list[str], # Files containing matches
2519 "count": int, # Number of files with matches
2520}
2521```
2522
2523### NotebookEdit
2524
2525**Nom de l'outil :** `NotebookEdit`
2526
2527**Entrée :**
2528
2529```python theme={null}
2530{
2531 "notebook_path": str, # Absolute path to the Jupyter notebook
2532 "cell_id": str | None, # The ID of the cell to edit
2533 "new_source": str, # The new source for the cell
2534 "cell_type": "code" | "markdown" | None, # The type of the cell
2535 "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type
2536}
2537```
2538
2539**Sortie :**
2540
2541```python theme={null}
2542{
2543 "message": str, # Success message
2544 "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed
2545 "cell_id": str | None, # Cell ID that was affected
2546 "total_cells": int, # Total cells in notebook after edit
2547}
2548```
2549
2550### WebFetch
2551
2552**Nom de l'outil :** `WebFetch`
2553
2554**Entrée :**
2555
2556```python theme={null}
2557{
2558 "url": str, # The URL to fetch content from
2559 "prompt": str, # The prompt to run on the fetched content
2560}
2561```
2562
2563**Sortie :**
2564
2565```python theme={null}
2566{
2567 "response": str, # AI model's response to the prompt
2568 "url": str, # URL that was fetched
2569 "final_url": str | None, # Final URL after redirects
2570 "status_code": int | None, # HTTP status code
2571}
2572```
2573
2574### WebSearch
2575
2576**Nom de l'outil :** `WebSearch`
2577
2578**Entrée :**
2579
2580```python theme={null}
2581{
2582 "query": str, # The search query to use
2583 "allowed_domains": list[str] | None, # Only include results from these domains
2584 "blocked_domains": list[str] | None, # Never include results from these domains
2585}
2586```
2587
2588**Sortie :**
2589
2590```python theme={null}
2591{
2592 "results": [{"title": str, "url": str, "snippet": str, "metadata": dict | None}],
2593 "total_results": int,
2594 "query": str,
2595}
2596```
2597
2598### TodoWrite
2599
2600**Nom de l'outil :** `TodoWrite`
2601
2602**Entrée :**
2603
2604```python theme={null}
2605{
2606 "todos": [
2607 {
2608 "content": str, # The task description
2609 "status": "pending" | "in_progress" | "completed", # Task status
2610 "activeForm": str, # Active form of the description
2611 }
2612 ]
2613}
2614```
2615
2616**Sortie :**
2617
2618```python theme={null}
2619{
2620 "message": str, # Success message
2621 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
2622}
2623```
2624
2625### BashOutput
2626
2627**Nom de l'outil :** `BashOutput`
2628
2629**Entrée :**
2630
2631```python theme={null}
2632{
2633 "bash_id": str, # The ID of the background shell
2634 "filter": str | None, # Optional regex to filter output lines
2635}
2636```
2637
2638**Sortie :**
2639
2640```python theme={null}
2641{
2642 "output": str, # New output since last check
2643 "status": "running" | "completed" | "failed", # Current shell status
2644 "exitCode": int | None, # Exit code when completed
2645}
2646```
2647
2648### KillBash
2649
2650**Nom de l'outil :** `KillBash`
2651
2652**Entrée :**
2653
2654```python theme={null}
2655{
2656 "shell_id": str # The ID of the background shell to kill
2657}
2658```
2659
2660**Sortie :**
2661
2662```python theme={null}
2663{
2664 "message": str, # Success message
2665 "shell_id": str, # ID of the killed shell
2666}
2667```
2668
2669### ExitPlanMode
2670
2671**Nom de l'outil :** `ExitPlanMode`
2672
2673**Entrée :**
2674
2675```python theme={null}
2676{
2677 "plan": str # The plan to run by the user for approval
2678}
2679```
2680
2681**Sortie :**
2682
2683```python theme={null}
2684{
2685 "message": str, # Confirmation message
2686 "approved": bool | None, # Whether user approved the plan
2687}
2688```
2689
2690### ListMcpResources
2691
2692**Nom de l'outil :** `ListMcpResources`
2693
2694**Entrée :**
2695
2696```python theme={null}
2697{
2698 "server": str | None # Optional server name to filter resources by
2699}
2700```
2701
2702**Sortie :**
2703
2704```python theme={null}
2705{
2706 "resources": [
2707 {
2708 "uri": str,
2709 "name": str,
2710 "description": str | None,
2711 "mimeType": str | None,
2712 "server": str,
2713 }
2714 ],
2715 "total": int,
2716}
2717```
2718
2719### ReadMcpResource
2720
2721**Nom de l'outil :** `ReadMcpResource`
2722
2723**Entrée :**
2724
2725```python theme={null}
2726{
2727 "server": str, # The MCP server name
2728 "uri": str, # The resource URI to read
2729}
2730```
2731
2732**Sortie :**
2733
2734```python theme={null}
2735{
2736 "contents": [
2737 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}
2738 ],
2739 "server": str,
2740}
2741```
2742
2743## Fonctionnalités avancées avec ClaudeSDKClient
2744
2745### Construire une interface de conversation continue
2746
2747```python theme={null}
2748from claude_agent_sdk import (
2749 ClaudeSDKClient,
2750 ClaudeAgentOptions,
2751 AssistantMessage,
2752 TextBlock,
2753)
2754import asyncio
2755
2756
2757class ConversationSession:
2758 """Maintains a single conversation session with Claude."""
2759
2760 def __init__(self, options: ClaudeAgentOptions | None = None):
2761 self.client = ClaudeSDKClient(options)
2762 self.turn_count = 0
2763
2764 async def start(self):
2765 await self.client.connect()
2766 print("Starting conversation session. Claude will remember context.")
2767 print(
2768 "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session"
2769 )
2770
2771 while True:
2772 user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")
2773
2774 if user_input.lower() == "exit":
2775 break
2776 elif user_input.lower() == "interrupt":
2777 await self.client.interrupt()
2778 print("Task interrupted!")
2779 continue
2780 elif user_input.lower() == "new":
2781 # Disconnect and reconnect for a fresh session
2782 await self.client.disconnect()
2783 await self.client.connect()
2784 self.turn_count = 0
2785 print("Started new conversation session (previous context cleared)")
2786 continue
2787
2788 # Send message - the session retains all previous messages
2789 await self.client.query(user_input)
2790 self.turn_count += 1
2791
2792 # Process response
2793 print(f"[Turn {self.turn_count}] Claude: ", end="")
2794 async for message in self.client.receive_response():
2795 if isinstance(message, AssistantMessage):
2796 for block in message.content:
2797 if isinstance(block, TextBlock):
2798 print(block.text, end="")
2799 print() # New line after response
2800
2801 await self.client.disconnect()
2802 print(f"Conversation ended after {self.turn_count} turns.")
2803
2804
2805async def main():
2806 options = ClaudeAgentOptions(
2807 allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits"
2808 )
2809 session = ConversationSession(options)
2810 await session.start()
2811
2812
2813# Example conversation:
2814# Turn 1 - You: "Create a file called hello.py"
2815# Turn 1 - Claude: "I'll create a hello.py file for you..."
2816# Turn 2 - You: "What's in that file?"
2817# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
2818# Turn 3 - You: "Add a main function to it"
2819# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)
2820
2821asyncio.run(main())
2822```
2823
2824### Utiliser les hooks pour la modification du comportement
2825
2826```python theme={null}
2827from claude_agent_sdk import (
2828 ClaudeSDKClient,
2829 ClaudeAgentOptions,
2830 HookMatcher,
2831 HookContext,
2832)
2833import asyncio
2834from typing import Any
2835
2836
2837async def pre_tool_logger(
2838 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2839) -> dict[str, Any]:
2840 """Log all tool usage before execution."""
2841 tool_name = input_data.get("tool_name", "unknown")
2842 print(f"[PRE-TOOL] About to use: {tool_name}")
2843
2844 # You can modify or block the tool execution here
2845 if tool_name == "Bash" and "rm -rf" in str(input_data.get("tool_input", {})):
2846 return {
2847 "hookSpecificOutput": {
2848 "hookEventName": "PreToolUse",
2849 "permissionDecision": "deny",
2850 "permissionDecisionReason": "Dangerous command blocked",
2851 }
2852 }
2853 return {}
2854
2855
2856async def post_tool_logger(
2857 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2858) -> dict[str, Any]:
2859 """Log results after tool execution."""
2860 tool_name = input_data.get("tool_name", "unknown")
2861 print(f"[POST-TOOL] Completed: {tool_name}")
2862 return {}
2863
2864
2865async def user_prompt_modifier(
2866 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2867) -> dict[str, Any]:
2868 """Add context to user prompts."""
2869 original_prompt = input_data.get("prompt", "")
2870
2871 # Add a timestamp as additional context for Claude to see
2872 from datetime import datetime
2873
2874 timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
2875
2876 return {
2877 "hookSpecificOutput": {
2878 "hookEventName": "UserPromptSubmit",
2879 "additionalContext": f"[Submitted at {timestamp}] Original prompt: {original_prompt}",
2880 }
2881 }
2882
2883
2884async def main():
2885 options = ClaudeAgentOptions(
2886 hooks={
2887 "PreToolUse": [
2888 HookMatcher(hooks=[pre_tool_logger]),
2889 HookMatcher(matcher="Bash", hooks=[pre_tool_logger]),
2890 ],
2891 "PostToolUse": [HookMatcher(hooks=[post_tool_logger])],
2892 "UserPromptSubmit": [HookMatcher(hooks=[user_prompt_modifier])],
2893 },
2894 allowed_tools=["Read", "Write", "Bash"],
2895 )
2896
2897 async with ClaudeSDKClient(options=options) as client:
2898 await client.query("List files in current directory")
2899
2900 async for message in client.receive_response():
2901 # Hooks will automatically log tool usage
2902 pass
2903
2904
2905asyncio.run(main())
2906```
2907
2908### Surveillance de la progression en temps réel
2909
2910```python theme={null}
2911from claude_agent_sdk import (
2912 ClaudeSDKClient,
2913 ClaudeAgentOptions,
2914 AssistantMessage,
2915 ToolUseBlock,
2916 ToolResultBlock,
2917 TextBlock,
2918)
2919import asyncio
2920
2921
2922async def monitor_progress():
2923 options = ClaudeAgentOptions(
2924 allowed_tools=["Write", "Bash"], permission_mode="acceptEdits"
2925 )
2926
2927 async with ClaudeSDKClient(options=options) as client:
2928 await client.query("Create 5 Python files with different sorting algorithms")
2929
2930 # Monitor progress in real-time
2931 async for message in client.receive_response():
2932 if isinstance(message, AssistantMessage):
2933 for block in message.content:
2934 if isinstance(block, ToolUseBlock):
2935 if block.name == "Write":
2936 file_path = block.input.get("file_path", "")
2937 print(f"Creating: {file_path}")
2938 elif isinstance(block, ToolResultBlock):
2939 print("Completed tool execution")
2940 elif isinstance(block, TextBlock):
2941 print(f"Claude says: {block.text[:100]}...")
2942
2943 print("Task completed!")
2944
2945
2946asyncio.run(monitor_progress())
2947```
2948
2949## Exemple d'utilisation
2950
2951### Opérations de fichiers de base (utilisant query)
2952
2953```python theme={null}
2954from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
2955import asyncio
2956
2957
2958async def create_project():
2959 options = ClaudeAgentOptions(
2960 allowed_tools=["Read", "Write", "Bash"],
2961 permission_mode="acceptEdits",
2962 cwd="/home/user/project",
2963 )
2964
2965 async for message in query(
2966 prompt="Create a Python project structure with setup.py", options=options
2967 ):
2968 if isinstance(message, AssistantMessage):
2969 for block in message.content:
2970 if isinstance(block, ToolUseBlock):
2971 print(f"Using tool: {block.name}")
2972
2973
2974asyncio.run(create_project())
2975```
2976
2977### Gestion des erreurs
2978
2979```python theme={null}
2980from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError
2981
2982try:
2983 async for message in query(prompt="Hello"):
2984 print(message)
2985except CLINotFoundError:
2986 print(
2987 "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
2988 )
2989except ProcessError as e:
2990 print(f"Process failed with exit code: {e.exit_code}")
2991except CLIJSONDecodeError as e:
2992 print(f"Failed to parse response: {e}")
2993```
2994
2995### Mode streaming avec client
2996
2997```python theme={null}
2998from claude_agent_sdk import ClaudeSDKClient
2999import asyncio
3000
3001
3002async def interactive_session():
3003 async with ClaudeSDKClient() as client:
3004 # Send initial message
3005 await client.query("What's the weather like?")
3006
3007 # Process responses
3008 async for msg in client.receive_response():
3009 print(msg)
3010
3011 # Send follow-up
3012 await client.query("Tell me more about that")
3013
3014 # Process follow-up response
3015 async for msg in client.receive_response():
3016 print(msg)
3017
3018
3019asyncio.run(interactive_session())
3020```
3021
3022### Utiliser les outils personnalisés avec ClaudeSDKClient
3023
3024```python theme={null}
3025from claude_agent_sdk import (
3026 ClaudeSDKClient,
3027 ClaudeAgentOptions,
3028 tool,
3029 create_sdk_mcp_server,
3030 AssistantMessage,
3031 TextBlock,
3032)
3033import asyncio
3034from typing import Any
3035
3036
3037# Define custom tools with @tool decorator
3038@tool("calculate", "Perform mathematical calculations", {"expression": str})
3039async def calculate(args: dict[str, Any]) -> dict[str, Any]:
3040 try:
3041 result = eval(args["expression"], {"__builtins__": {}})
3042 return {"content": [{"type": "text", "text": f"Result: {result}"}]}
3043 except Exception as e:
3044 return {
3045 "content": [{"type": "text", "text": f"Error: {str(e)}"}],
3046 "is_error": True,
3047 }
3048
3049
3050@tool("get_time", "Get current time", {})
3051async def get_time(args: dict[str, Any]) -> dict[str, Any]:
3052 from datetime import datetime
3053
3054 current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
3055 return {"content": [{"type": "text", "text": f"Current time: {current_time}"}]}
3056
3057
3058async def main():
3059 # Create SDK MCP server with custom tools
3060 my_server = create_sdk_mcp_server(
3061 name="utilities", version="1.0.0", tools=[calculate, get_time]
3062 )
3063
3064 # Configure options with the server
3065 options = ClaudeAgentOptions(
3066 mcp_servers={"utils": my_server},
3067 allowed_tools=["mcp__utils__calculate", "mcp__utils__get_time"],
3068 )
3069
3070 # Use ClaudeSDKClient for interactive tool usage
3071 async with ClaudeSDKClient(options=options) as client:
3072 await client.query("What's 123 * 456?")
3073
3074 # Process calculation response
3075 async for message in client.receive_response():
3076 if isinstance(message, AssistantMessage):
3077 for block in message.content:
3078 if isinstance(block, TextBlock):
3079 print(f"Calculation: {block.text}")
3080
3081 # Follow up with time query
3082 await client.query("What time is it now?")
3083
3084 async for message in client.receive_response():
3085 if isinstance(message, AssistantMessage):
3086 for block in message.content:
3087 if isinstance(block, TextBlock):
3088 print(f"Time: {block.text}")
3089
3090
3091asyncio.run(main())
3092```
3093
3094## Configuration du sandbox
3095
3096### `SandboxSettings`
3097
3098Configuration pour le comportement du sandbox. Utilisez ceci pour activer le sandboxing des commandes et configurer les restrictions réseau programmatiquement.
3099
3100```python theme={null}
3101class SandboxSettings(TypedDict, total=False):
3102 enabled: bool
3103 autoAllowBashIfSandboxed: bool
3104 excludedCommands: list[str]
3105 allowUnsandboxedCommands: bool
3106 network: SandboxNetworkConfig
3107 ignoreViolations: SandboxIgnoreViolations
3108 enableWeakerNestedSandbox: bool
3109```
3110
3111| Propriété | Type | Par défaut | Description |
3112| :-------------------------- | :------------------------------------------------------ | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3113| `enabled` | `bool` | `False` | Activez le mode sandbox pour l'exécution des commandes |
3114| `autoAllowBashIfSandboxed` | `bool` | `True` | Approuvez automatiquement les commandes bash quand le sandbox est activé |
3115| `excludedCommands` | `list[str]` | `[]` | Commandes qui contournent toujours les restrictions du sandbox (par exemple, `["docker"]`). Celles-ci s'exécutent sans sandbox automatiquement sans implication du modèle |
3116| `allowUnsandboxedCommands` | `bool` | `True` | Permettez au modèle de demander l'exécution de commandes en dehors du sandbox. Quand `True`, le modèle peut définir `dangerouslyDisableSandbox` dans l'entrée d'outil, qui revient au [système de permissions](#permissions-fallback-for-unsandboxed-commands) |
3117| `network` | [`SandboxNetworkConfig`](#sandbox-network-config) | `None` | Configuration de sandbox spécifique au réseau |
3118| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandbox-ignore-violations) | `None` | Configurez quelles violations de sandbox ignorer |
3119| `enableWeakerNestedSandbox` | `bool` | `False` | Activez un sandbox imbriqué plus faible pour la compatibilité |
3120
3121#### Exemple d'utilisation
3122
3123```python theme={null}
3124from claude_agent_sdk import query, ClaudeAgentOptions, SandboxSettings
3125
3126sandbox_settings: SandboxSettings = {
3127 "enabled": True,
3128 "autoAllowBashIfSandboxed": True,
3129 "network": {"allowLocalBinding": True},
3130}
3131
3132async for message in query(
3133 prompt="Build and test my project",
3134 options=ClaudeAgentOptions(sandbox=sandbox_settings),
3135):
3136 print(message)
3137```
3138
3139<Warning>
3140 **Sécurité des sockets Unix** : L'option `allowUnixSockets` peut accorder l'accès à des services système puissants. Par exemple, permettre `/var/run/docker.sock` accorde effectivement un accès complet au système hôte via l'API Docker, contournant l'isolation du sandbox. Autorisez uniquement les sockets Unix strictement nécessaires et comprenez les implications de sécurité de chacun.
3141</Warning>
3142
3143### `SandboxNetworkConfig`
3144
3145Configuration spécifique au réseau pour le mode sandbox.
3146
3147```python theme={null}
3148class SandboxNetworkConfig(TypedDict, total=False):
3149 allowedDomains: list[str]
3150 deniedDomains: list[str]
3151 allowManagedDomainsOnly: bool
3152 allowUnixSockets: list[str]
3153 allowAllUnixSockets: bool
3154 allowLocalBinding: bool
3155 allowMachLookup: list[str]
3156 httpProxyPort: int
3157 socksProxyPort: int
3158```
3159
3160| Propriété | Type | Par défaut | Description |
3161| :------------------------ | :---------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
3162| `allowedDomains` | `list[str]` | `[]` | Noms de domaine auxquels les processus en sandbox peuvent accéder |
3163| `deniedDomains` | `list[str]` | `[]` | Noms de domaine auxquels les processus en sandbox ne peuvent pas accéder. Prend la priorité sur `allowedDomains` |
3164| `allowManagedDomainsOnly` | `bool` | `False` | Paramètres gérés uniquement : quand défini dans les paramètres gérés, ignorez `allowedDomains` des sources de paramètres non gérées. N'a aucun effet quand défini via les options SDK |
3165| `allowUnixSockets` | `list[str]` | `[]` | Chemins de socket Unix auxquels les processus peuvent accéder (par exemple, socket Docker) |
3166| `allowAllUnixSockets` | `bool` | `False` | Permettez l'accès à tous les sockets Unix |
3167| `allowLocalBinding` | `bool` | `False` | Permettez aux processus de se lier aux ports locaux (par exemple, pour les serveurs de développement) |
3168| `allowMachLookup` | `list[str]` | `[]` | macOS uniquement : noms de services XPC/Mach à autoriser. Supporte un caractère générique à la fin |
3169| `httpProxyPort` | `int` | `None` | Port du proxy HTTP pour les requêtes réseau |
3170| `socksProxyPort` | `int` | `None` | Port du proxy SOCKS pour les requêtes réseau |
3171
3172<Note>
3173 Le proxy sandbox intégré applique la liste blanche réseau en fonction du nom d'hôte demandé et ne termine pas ou n'inspecte pas le trafic TLS, donc des techniques telles que le [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) peuvent potentiellement le contourner. Voir [Limitations de sécurité du sandboxing](/fr/sandboxing#security-limitations) pour les détails et [Déploiement sécurisé](/fr/agent-sdk/secure-deployment#traffic-forwarding) pour configurer un proxy qui termine TLS.
3174</Note>
3175
3176### `SandboxIgnoreViolations`
3177
3178Configuration pour ignorer les violations de sandbox spécifiques.
3179
3180```python theme={null}
3181class SandboxIgnoreViolations(TypedDict, total=False):
3182 file: list[str]
3183 network: list[str]
3184```
3185
3186| Propriété | Type | Par défaut | Description |
3187| :-------- | :---------- | :--------- | :------------------------------------------------------- |
3188| `file` | `list[str]` | `[]` | Modèles de chemin de fichier pour ignorer les violations |
3189| `network` | `list[str]` | `[]` | Modèles réseau pour ignorer les violations |
3190
3191### Fallback de permissions pour les commandes sans sandbox
3192
3193Quand `allowUnsandboxedCommands` est activé, le modèle peut demander l'exécution de commandes en dehors du sandbox en définissant `dangerouslyDisableSandbox: True` dans l'entrée d'outil. Ces requêtes reviennent au système de permissions existant, ce qui signifie que votre gestionnaire `can_use_tool` sera invoqué, vous permettant d'implémenter une logique d'autorisation personnalisée.
3194
3195<Note>
3196 **`excludedCommands` vs `allowUnsandboxedCommands` :**
3197
3198 * `excludedCommands` : Une liste statique de commandes qui contournent toujours le sandbox automatiquement (par exemple, `["docker"]`). Le modèle n'a aucun contrôle sur ceci.
3199 * `allowUnsandboxedCommands` : Permet au modèle de décider à l'exécution s'il faut demander l'exécution sans sandbox en définissant `dangerouslyDisableSandbox: True` dans l'entrée d'outil.
3200</Note>
3201
3202```python theme={null}
3203from claude_agent_sdk import (
3204 query,
3205 ClaudeAgentOptions,
3206 HookMatcher,
3207 PermissionResultAllow,
3208 PermissionResultDeny,
3209 ToolPermissionContext,
3210)
3211
3212
3213async def can_use_tool(
3214 tool: str, input: dict, context: ToolPermissionContext
3215) -> PermissionResultAllow | PermissionResultDeny:
3216 # Check if the model is requesting to bypass the sandbox
3217 if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
3218 # The model is requesting to run this command outside the sandbox
3219 print(f"Unsandboxed command requested: {input.get('command')}")
3220
3221 if is_command_authorized(input.get("command")):
3222 return PermissionResultAllow()
3223 return PermissionResultDeny(
3224 message="Command not authorized for unsandboxed execution"
3225 )
3226 return PermissionResultAllow()
3227
3228
3229# Required: dummy hook keeps the stream open for can_use_tool
3230async def dummy_hook(input_data, tool_use_id, context):
3231 return {"continue_": True}
3232
3233
3234async def prompt_stream():
3235 yield {
3236 "type": "user",
3237 "message": {"role": "user", "content": "Deploy my application"},
3238 }
3239
3240
3241async def main():
3242 async for message in query(
3243 prompt=prompt_stream(),
3244 options=ClaudeAgentOptions(
3245 sandbox={
3246 "enabled": True,
3247 "allowUnsandboxedCommands": True, # Model can request unsandboxed execution
3248 },
3249 permission_mode="default",
3250 can_use_tool=can_use_tool,
3251 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
3252 ),
3253 ):
3254 print(message)
3255```
3256
3257Ce modèle vous permet de :
3258
3259* **Auditer les requêtes du modèle** : Enregistrez quand le modèle demande l'exécution sans sandbox
3260* **Implémenter des listes blanches** : Autorisez uniquement des commandes spécifiques à s'exécuter sans sandbox
3261* **Ajouter des flux d'approbation** : Nécessitez une autorisation explicite pour les opérations privilégiées
3262
3263<Warning>
3264 Les commandes s'exécutant avec `dangerouslyDisableSandbox: True` ont un accès complet au système. Assurez-vous que votre gestionnaire `can_use_tool` valide ces requêtes avec soin.
3265
3266 Si `permission_mode` est défini sur `bypassPermissions` et `allow_unsandboxed_commands` est activé, le modèle peut exécuter de manière autonome des commandes en dehors du sandbox sans aucun prompt d'approbation. Cette combinaison permet effectivement au modèle d'échapper à l'isolation du sandbox silencieusement.
3267</Warning>
3268
3269## Voir aussi
3270
3271* [Vue d'ensemble du SDK](/fr/agent-sdk/overview) - Concepts généraux du SDK
3272* [Référence du SDK TypeScript](/fr/agent-sdk/typescript) - Documentation du SDK TypeScript
3273* [Référence CLI](/fr/cli-reference) - Interface de ligne de commande
3274* [Flux de travail courants](/fr/common-workflows) - Guides étape par étape
