517 async def set_model(self, model: str | None = None) -> None517 async def set_model(self, model: str | None = None) -> None
518 async def rewind_files(self, user_message_id: str) -> None518 async def rewind_files(self, user_message_id: str) -> None
519 async def get_mcp_status(self) -> McpStatusResponse519 async def get_mcp_status(self) -> McpStatusResponse
520 async def get_context_usage(self) -> ContextUsageResponse
520 async def reconnect_mcp_server(self, server_name: str) -> None521 async def reconnect_mcp_server(self, server_name: str) -> None
521 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None522 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
522 async def stop_task(self, task_id: str) -> None523 async def stop_task(self, task_id: str) -> None
540| `set_model(model)` | Change le modèle pour la session actuelle. Passez `None` pour réinitialiser au [modèle par défaut de Claude Code](/docs/fr/model-config) |541| `set_model(model)` | Change le modèle pour la session actuelle. Passez `None` pour réinitialiser au [modèle par défaut de Claude Code](/docs/fr/model-config) |
541| `rewind_files(user_message_id)` | Restaure les fichiers à leur état au message utilisateur spécifié. Nécessite `enable_file_checkpointing=True`. Voir [File checkpointing](/docs/fr/agent-sdk/file-checkpointing) |542| `rewind_files(user_message_id)` | Restaure les fichiers à leur état au message utilisateur spécifié. Nécessite `enable_file_checkpointing=True`. Voir [File checkpointing](/docs/fr/agent-sdk/file-checkpointing) |
542| `get_mcp_status()` | Obtient le statut de tous les serveurs MCP configurés. Retourne [`McpStatusResponse`](#mcpstatusresponse) |543| `get_mcp_status()` | Obtient le statut de tous les serveurs MCP configurés. Retourne [`McpStatusResponse`](#mcpstatusresponse) |
544| `get_context_usage()` | Obtient une ventilation de l'utilisation de la fenêtre de contexte par catégorie, compétence et outil. Les mêmes données que `/context` affiche dans une session interactive. Retourne [`ContextUsageResponse`](#contextusageresponse). Pour calculer la ventilation, Claude Code effectue plusieurs demandes d'API de comptage de tokens qui n'apparaissent pas dans le flux de messages ; voir [comment ces demandes sont traitées](#contextusageresponse) |
543| `reconnect_mcp_server(server_name)` | Réessaye de se connecter à un serveur MCP qui a échoué ou a été déconnecté |545| `reconnect_mcp_server(server_name)` | Réessaye de se connecter à un serveur MCP qui a échoué ou a été déconnecté |
544| `toggle_mcp_server(server_name, enabled)` | Active ou désactive un serveur MCP en cours de session. La désactivation supprime ses outils |546| `toggle_mcp_server(server_name, enabled)` | Active ou désactive un serveur MCP en cours de session. La désactivation supprime ses outils |
545| `stop_task(task_id)` | Arrête une tâche de fond en cours d'exécution. Un [`TaskNotificationMessage`](#tasknotificationmessage) avec le statut `"stopped"` suit dans le flux de messages |547| `stop_task(task_id)` | Arrête une tâche de fond en cours d'exécution. Un [`TaskNotificationMessage`](#tasknotificationmessage) avec le statut `"stopped"` suit dans le flux de messages |
616 Exemple - Entrée en streaming avec ClaudeSDKClient618 Exemple - Entrée en streaming avec ClaudeSDKClient
617</h4>619</h4>
618 620
621`query()` accepte également un itérable asynchrone de dicts de messages utilisateur, vous permettant d'assembler le prompt au moment de l'envoi ou d'inclure des blocs de contenu tels que des images. Claude Code commence à répondre au premier message cédé dès qu'il arrive, sans attendre que l'itérable se termine, et `receive_response()` s'arrête au `ResultMessage` qui termine cette réponse. Mettez tout ce que Claude doit lire avant de répondre dans un seul message, comme le fait ce générateur, et associez chaque appel `query()` à sa propre boucle `receive_response()`.
622
619```python theme={null}623```python theme={null}
620import asyncio624import asyncio
621from claude_agent_sdk import ClaudeSDKClient625from claude_agent_sdk import ClaudeSDKClient
622 626
623 627
624async def message_stream():628async def message_stream():
625 """Generate messages dynamically."""629 """Assemble the prompt at send time and yield it as one user message."""
626 yield {630 readings = {"Temperature": "25°C", "Humidity": "60%"}
627 "type": "user",631 data = ", ".join(f"{name}: {value}" for name, value in readings.items())
628 "message": {"role": "user", "content": "Analyze the following data:"},
629 }
630 await asyncio.sleep(0.5)
631 yield {
632 "type": "user",
633 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
634 }
635 await asyncio.sleep(0.5)
636 yield {632 yield {
637 "type": "user",633 "type": "user",
638 "message": {"role": "user", "content": "What patterns do you see?"},634 "message": {
635 "role": "user",
636 "content": f"Analyze the following sensor data and describe any patterns you see: {data}",
637 },
639 }638 }
640 639
641 640
1607| `scope` | `str` (optional) | Portée de la configuration |1606| `scope` | `str` (optional) | Portée de la configuration |
1608| `tools` | `list` (optional) | Outils fournis par ce serveur, chacun avec les champs `name`, `description`, et `annotations` |1607| `tools` | `list` (optional) | Outils fournis par ce serveur, chacun avec les champs `name`, `description`, et `annotations` |
1609 1608
1609<h3 id="contextusageresponse">
1610 `ContextUsageResponse`
1611</h3>
1612
1613Réponse de [`ClaudeSDKClient.get_context_usage()`](#methods). Ceci est la même charge utile que Claude Code rend pour la commande `/context` dans une session interactive, donc aux côtés des comptages de tokens elle porte des champs d'affichage tels que `color` et `gridRows` que Claude Code utilise pour dessiner la grille d'utilisation `/context`.
1614
1615Claude Code construit cette charge utile en envoyant plusieurs requêtes à l'API de [comptage de tokens](https://platform.claude.com/docs/en/build-with-claude/token-counting). Ces requêtes n'apparaissent pas dans le flux de messages, donc le suivi des coûts qui lit le flux ne les verra pas. Sur l'API Anthropic, le comptage de tokens n'est pas facturé.
1616
1617```python theme={null}
1618class ContextUsageResponse(TypedDict):
1619 categories: list[ContextUsageCategory]
1620 totalTokens: int
1621 maxTokens: int
1622 rawMaxTokens: int
1623 percentage: float
1624 model: str
1625 isAutoCompactEnabled: bool
1626 memoryFiles: list[dict[str, Any]]
1627 mcpTools: list[dict[str, Any]]
1628 agents: list[dict[str, Any]]
1629 gridRows: list[list[dict[str, Any]]]
1630 autoCompactThreshold: NotRequired[int]
1631 deferredBuiltinTools: NotRequired[list[dict[str, Any]]]
1632 systemTools: NotRequired[list[dict[str, Any]]]
1633 systemPromptSections: NotRequired[list[dict[str, Any]]]
1634 slashCommands: NotRequired[dict[str, Any]]
1635 skills: NotRequired[dict[str, Any]] # skill usage with frontmatter breakdown
1636 messageBreakdown: NotRequired[dict[str, Any]] # message tokens by type
1637 apiUsage: NotRequired[dict[str, Any] | None]
1638```
1639
1640Chaque entrée `ContextUsageCategory` porte `name`, `tokens`, `color`, et un drapeau optionnel `isDeferred`. `totalTokens` est l'utilisation de contexte actuelle de la session, et `maxTokens` est la fenêtre contre laquelle l'utilisation est mesurée. Cette fenêtre est la fenêtre de contexte du modèle, ou la fenêtre de compaction automatique inférieure quand une s'applique, et `rawMaxTokens` porte la même valeur que `maxTokens`. `apiUsage` contient l'utilisation de la dernière réponse API, pas un total cumulé pour la session. Claude Code laisse les clés optionnelles `deferredBuiltinTools`, `systemTools`, et `systemPromptSections` non définies, donc attendez-vous à ce qu'elles soient absentes même si le type les déclare.
1641
1610<h3 id="sdkpluginconfig">1642<h3 id="sdkpluginconfig">
1611 `SdkPluginConfig`1643 `SdkPluginConfig`
1612</h3>1644</h3>
2712 2744
2713Documentation 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.2745Documentation 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.
2714 2746
2747Chaque sortie affichée est la valeur que vous lisez à partir de [`UserMessage.tool_use_result`](#usermessage) pour cet outil. Les noms de clés apparaissent exactement comme Claude Code les émet. Une clé annotée `| None` avec un commentaire « présent quand » ou « optionnel » est omise quand elle ne s'applique pas.
2748
2715<h3 id="agent">2749<h3 id="agent">
2716 Agent2750 Agent
2717</h3>2751</h3>
2885 2919
2886**Nom de l'outil :** `Bash`2920**Nom de l'outil :** `Bash`
2887 2921
2888Pour ce qui définit le plafond au premier plan, voir [Limites de délai d'attente et de sortie](/docs/fr/tools-reference#timeout-and-output-limits). Pour la limite de temps en arrière-plan, voir [Commandes en arrière-plan](/docs/fr/tools-reference#background-commands).2922Pour ce qui définit le plafond au premier plan, voir [Limites de délai d'attente et de sortie](/docs/fr/tools-reference#timeout-and-output-limits). Pour la limite de temps en arrière-plan, voir [Limite de temps pour les commandes en arrière-plan](/docs/fr/tools-reference#time-limit-for-background-commands).
2889 2923
2890**Entrée :**2924**Entrée :**
2891 2925
2962 2996
2963```python theme={null}2997```python theme={null}
2964{2998{
2965 "message": str, # Confirmation message2999 "filePath": str, # The file that was edited
2966 "replacements": int, # Number of replacements made3000 "oldString": str, # The text that was replaced
2967 "file_path": str, # File path that was edited3001 "newString": str, # The text that replaced it
3002 "originalFile": str | None, # File contents before the edit
3003 "structuredPatch": [ # Diff hunks for the change
3004 {
3005 "oldStart": int,
3006 "oldLines": int,
3007 "newStart": int,
3008 "newLines": int,
3009 "lines": list[str],
3010 }
3011 ],
3012 "userModified": bool, # Whether the user changed the proposed edit before accepting it
3013 "replaceAll": bool, # Whether all occurrences were replaced
3014 "gitDiff": { # Optional git diff summary for the file
3015 "filename": str,
3016 "status": "modified" | "added",
3017 "additions": int,
3018 "deletions": int,
3019 "changes": int,
3020 "patch": str,
3021 "repository": str | None, # GitHub owner/repo when available
3022 } | None,
2968}3023}
2969```3024```
2970 3025
2984}3039}
2985```3040```
2986 3041
2987**Sortie (fichiers texte) :**3042La sortie prend l'une des formes suivantes selon ce que Claude a lu. Vérifiez la clé `type` pour les distinguer.
3043
3044**Sortie (type : `"text"`) :**
3045
3046```python theme={null}
3047{
3048 "type": "text",
3049 "file": {
3050 "filePath": str, # The file that was read
3051 "content": str, # The returned content
3052 "numLines": int, # Number of lines in the returned content
3053 "startLine": int, # Line number the content starts at
3054 "totalLines": int, # Total number of lines in the file
3055 "truncatedByTokenCap": bool | None, # Present and True when a whole-file read exceeded the token cap and content is the first page
3056 },
3057}
3058```
3059
3060**Sortie (type : `"image"`) :**
3061
3062```python theme={null}
3063{
3064 "type": "image",
3065 "file": {
3066 "base64": str, # Base64-encoded image data
3067 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # Image MIME type
3068 "originalSize": int, # Original file size in bytes
3069 "dimensions": { # Optional sizing info for coordinate mapping
3070 "originalWidth": int | None, # Optional; original width in pixels
3071 "originalHeight": int | None, # Optional; original height in pixels
3072 "displayWidth": int | None, # Optional; width after resizing
3073 "displayHeight": int | None, # Optional; height after resizing
3074 } | None,
3075 },
3076}
3077```
3078
3079**Sortie (type : `"notebook"`) :**
3080
3081```python theme={null}
3082{
3083 "type": "notebook",
3084 "file": {
3085 "filePath": str, # The notebook that was read
3086 "cells": list, # Notebook cells
3087 },
3088}
3089```
3090
3091**Sortie (type : `"pdf"`) :**
3092
3093```python theme={null}
3094{
3095 "type": "pdf",
3096 "file": {
3097 "filePath": str, # The PDF that was read
3098 "base64": str, # Base64-encoded PDF data
3099 "originalSize": int, # File size in bytes
3100 },
3101}
3102```
3103
3104**Sortie (type : `"parts"`) :**
2988 3105
2989```python theme={null}3106```python theme={null}
2990{3107{
2991 "content": str, # File contents with line numbers3108 "type": "parts",
2992 "total_lines": int, # Total number of lines in file3109 "file": {
2993 "lines_returned": int, # Lines actually returned3110 "filePath": str, # The PDF that was read
3111 "originalSize": int, # File size in bytes
3112 "count": int, # Number of pages extracted as images
3113 "outputDir": str, # Directory containing the extracted page images
3114 },
3115 "firstPage": int | None, # Optional document page number of the first extracted page
2994}3116}
2995```3117```
2996 3118
2997**Sortie (images) :**3119**Sortie (type : `"file_unchanged"`) :**
2998 3120
2999```python theme={null}3121```python theme={null}
3000{3122{
3001 "image": str, # Base64 encoded image data3123 "type": "file_unchanged", # The file is unchanged since Claude last read it in this session, so the content isn't repeated
3002 "mime_type": str, # Image MIME type3124 "file": {
3003 "file_size": int, # File size in bytes3125 "filePath": str,
3126 },
3127 "source": "seeded" | None, # Present when the earlier copy came from a CLAUDE.md or memory file loaded at startup rather than a Read call
3004}3128}
3005```3129```
3006 3130
3023 3147
3024```python theme={null}3148```python theme={null}
3025{3149{
3026 "message": str, # Success message3150 "type": "create" | "update", # Whether the write created a new file or overwrote an existing one
3027 "bytes_written": int, # Number of bytes written3151 "filePath": str, # The file that was written
3028 "file_path": str, # File path that was written3152 "content": str, # The content that was written
3153 "structuredPatch": [ # Diff hunks; empty for a new file, when nothing changed, or when Claude Code skipped the diff
3154 {
3155 "oldStart": int,
3156 "oldLines": int,
3157 "newStart": int,
3158 "newLines": int,
3159 "lines": list[str],
3160 }
3161 ],
3162 "originalFile": str | None, # Previous content; None for a new file or when the previous content was too large to include
3163 "gitDiff": { # Optional git diff summary for the file
3164 "filename": str,
3165 "status": "modified" | "added",
3166 "additions": int,
3167 "deletions": int,
3168 "changes": int,
3169 "patch": str,
3170 "repository": str | None, # GitHub owner/repo when available
3171 } | None,
3172 "userModified": bool | None, # Optional; whether the user edited the proposed content before accepting it
3029}3173}
3030```3174```
3031 3175
3048 3192
3049```python theme={null}3193```python theme={null}
3050{3194{
3051 "matches": list[str], # Array of matching file paths3195 "durationMs": int, # Time taken to run the search, in milliseconds
3052 "count": int, # Number of matches found3196 "numFiles": int, # Number of paths returned, after any truncation
3053 "search_path": str, # Search directory used3197 "filenames": list[str], # Matching file paths
3198 "truncated": bool, # Whether the results were truncated at the 100-file limit
3199 "totalMatches": int | None, # Optional total number of matching files before truncation; a lower bound when countIsComplete is False
3200 "countIsComplete": bool | None, # Optional; whether totalMatches is exact
3054}3201}
3055```3202```
3056 3203
3204`totalMatches` et `countIsComplete` nécessitent Claude Code v2.1.191 ou ultérieur.
3205
3057<h3 id="grep">3206<h3 id="grep">
3058 Grep3207 Grep
3059</h3>3208</h3>
3074 "-B": int | None, # Lines to show before each match3223 "-B": int | None, # Lines to show before each match
3075 "-A": int | None, # Lines to show after each match3224 "-A": int | None, # Lines to show after each match
3076 "-C": int | None, # Lines to show before and after3225 "-C": int | None, # Lines to show before and after
3226 "context": int | None, # Lines to show before and after; -C is an alias
3227 "-o": bool | None, # Print only the matched parts of each line
3077 "head_limit": int | None, # Limit output to first N lines/entries3228 "head_limit": int | None, # Limit output to first N lines/entries
3229 "offset": int | None, # Skip first N lines/entries before applying head_limit
3078 "multiline": bool | None, # Enable multiline mode3230 "multiline": bool | None, # Enable multiline mode
3079}3231}
3080```3232```
3081 3233
3082**Sortie (mode contenu) :**3234**Sortie :**
3083 3235
3084```python theme={null}3236```python theme={null}
3085{3237{
3086 "matches": [3238 "mode": "content" | "files_with_matches" | "count" | None, # The output mode that was used
3087 {3239 "numFiles": int, # Number of files in the result; always 0 in content mode
3088 "file": str,3240 "filenames": list[str], # Matching files in files_with_matches mode; empty in the other modes
3089 "line_number": int | None,3241 "content": str | None, # Matching lines in content mode, or per-file counts in count mode
3090 "line": str,3242 "numLines": int | None, # Number of lines in content, present in content mode
3091 "before_context": list[str] | None,3243 "numMatches": int | None, # Total match count, present in count mode
3092 "after_context": list[str] | None,3244 "totalFiles": int | None, # Optional total before head_limit and offset, in files_with_matches mode
3093 }3245 "totalLines": int | None, # Optional total before head_limit and offset, in content mode
3094 ],3246 "appliedLimit": int | None, # Present when head_limit truncated the result
3095 "total_matches": int,3247 "appliedOffset": int | None, # Present when an offset was applied
3096}3248}
3097```3249```
3098 3250
3099**Sortie (mode fichiers\_avec\_correspondances) :**3251Grep retourne cette forme de dict dans chaque mode de sortie. Les clés optionnelles présentes dépendent de `output_mode`.
3100 3252
3101```python theme={null}3253`totalFiles` nécessite Claude Code v2.1.208 ou ultérieur. `totalLines` nécessite Claude Code v2.1.210 ou ultérieur.
3102{
3103 "files": list[str], # Files containing matches
3104 "count": int, # Number of files with matches
3105}
3106```
3107 3254
3108<h3 id="notebookedit">3255<h3 id="notebookedit">
3109 NotebookEdit3256 NotebookEdit
3127 3274
3128```python theme={null}3275```python theme={null}
3129{3276{
3130 "message": str, # Success message3277 "new_source": str, # The source written to the cell
3131 "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed3278 "old_source": str | None, # Previous cell source, present for replace and delete
3132 "cell_id": str | None, # Cell ID that was affected3279 "cell_id": str | None, # ID of the edited cell, when available
3133 "total_cells": int, # Total cells in notebook after edit3280 "cell_type": "code" | "markdown", # The cell type
3281 "language": str, # The notebook's programming language
3282 "edit_mode": str, # The edit mode that was used
3283 "error": str | None, # Error message when the operation failed
3284 "notebook_path": str, # The notebook file
3285 "original_file": str, # Notebook content before the edit
3286 "updated_file": str, # Notebook content after the edit
3134}3287}
3135```3288```
3136 3289
3228 3381
3229```python theme={null}3382```python theme={null}
3230{3383{
3231 "message": str, # Success message3384 "oldTodos": [ # The todo list before the update
3232 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},3385 {
3386 "content": str,
3387 "status": "pending" | "in_progress" | "completed",
3388 "activeForm": str,
3389 }
3390 ],
3391 "newTodos": [ # The todo list after the update
3392 {
3393 "content": str,
3394 "status": "pending" | "in_progress" | "completed",
3395 "activeForm": str,
3396 }
3397 ],
3233}3398}
3234```3399```
3235 3400
3401 3566
3402```python theme={null}3567```python theme={null}
3403{3568{
3404 "message": str, # Confirmation message3569 "plan": str | None, # The plan that was presented to the user
3405 "approved": bool | None, # Whether user approved the plan3570 "isAgent": bool, # True when a subagent called the tool
3571 "filePath": str | None, # Present when the plan was saved to a file
3572 "hasTaskTool": bool | None, # Optional; whether the Agent tool is available in the current context
3573 "planWasEdited": bool | None, # Present and True when the user edited the plan before approving
3574 "awaitingLeaderApproval": bool | None, # Present and True when a teammate sent the plan to the team lead for approval
3575 "requestId": str | None, # Optional ID of that approval request
3406}3576}
3407```3577```
3408 3578
3420}3590}
3421```3591```
3422 3592
3593Le résultat est une liste plutôt qu'un dict, donc `tool_use_result` contient une `list` pour cet outil.
3594
3423**Sortie :**3595**Sortie :**
3424 3596
3425```python theme={null}3597```python theme={null}
3426{3598[ # One entry per resource
3427 "resources": [
3428 {3599 {
3429 "uri": str,3600 "uri": str, # Resource URI
3430 "name": str,3601 "name": str, # Resource name
3431 "description": str | None,3602 "mimeType": str | None, # Optional MIME type
3432 "mimeType": str | None,3603 "description": str | None, # Optional description
3433 "server": str,3604 "server": str, # Server that provides this resource
3434 }3605 }
3435 ],3606]
3436 "total": int,
3437}
3438```3607```
3439 3608
3440<h3 id="readmcpresource">3609<h3 id="readmcpresource">
3457```python theme={null}3626```python theme={null}
3458{3627{
3459 "contents": [3628 "contents": [
3460 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}3629 {
3630 "uri": str, # Resource URI
3631 "mimeType": str | None, # Optional MIME type
3632 "text": str | None, # Text content, or a note about the binary content
3633 "blobSavedTo": str | None, # Present when Claude Code saved binary content to disk; path of the saved file
3634 }
3461 ],3635 ],
3462 "server": str,3636 "error": str | None, # Present when the server couldn't read the resource
3463}3637}
3464```3638```
3465 3639
