15| Si vous voulez... | Faites ceci |15| Si vous voulez... | Faites ceci |
16| :- | :- |16| :- | :- |
17| Définir un outil | Utilisez [`@tool`](/docs/fr/agent-sdk/python#tool) (Python) ou [`tool()`](/docs/fr/agent-sdk/typescript#tool) (TypeScript) avec un nom, une description, un schéma et un gestionnaire. Voir [Créer un outil personnalisé](#create-a-custom-tool). |17| Définir un outil | Utilisez [`@tool`](/docs/fr/agent-sdk/python#tool) (Python) ou [`tool()`](/docs/fr/agent-sdk/typescript#tool) (TypeScript) avec un nom, une description, un schéma et un gestionnaire. Voir [Créer un outil personnalisé](#create-a-custom-tool). |
18| Rendre un paramètre facultatif | Déclarez-le comme facultatif dans le schéma et appliquez la valeur par défaut dans le gestionnaire. Voir [Rendre un paramètre facultatif](#make-a-parameter-optional). |
18| Enregistrer un outil auprès de Claude | Enveloppez dans `create_sdk_mcp_server` / `createSdkMcpServer` et transmettez à `mcpServers` dans `query()`. Voir [Appeler un outil personnalisé](#call-a-custom-tool). |19| Enregistrer un outil auprès de Claude | Enveloppez dans `create_sdk_mcp_server` / `createSdkMcpServer` et transmettez à `mcpServers` dans `query()`. Voir [Appeler un outil personnalisé](#call-a-custom-tool). |
19| Pré-approuver un outil | Ajoutez à vos outils autorisés. Voir [Configurer les outils autorisés](#configure-allowed-tools). |20| Pré-approuver un outil | Ajoutez à vos outils autorisés. Voir [Configurer les outils autorisés](#configure-allowed-tools). |
20| Supprimer un outil intégré du contexte de Claude | Transmettez un tableau `tools` listant uniquement les outils intégrés que vous souhaitez. Voir [Configurer les outils autorisés](#configure-allowed-tools). |21| Supprimer un outil intégré du contexte de Claude | Transmettez un tableau `tools` listant uniquement les outils intégrés que vous souhaitez. Voir [Configurer les outils autorisés](#configure-allowed-tools). |
32 33
33* **Nom :** un identifiant unique que Claude utilise pour appeler l'outil.34* **Nom :** un identifiant unique que Claude utilise pour appeler l'outil.
34* **Description :** ce que fait l'outil. Claude lit ceci pour décider quand l'appeler.35* **Description :** ce que fait l'outil. Claude lit ceci pour décider quand l'appeler.
35* **Schéma d'entrée :** les arguments que Claude doit fournir. En TypeScript, c'est toujours un [schéma Zod](https://zod.dev/), et les `args` du gestionnaire sont typés automatiquement à partir de celui-ci. En Python, c'est un dictionnaire mappant les noms aux types, comme `{"latitude": float}`, que le SDK convertit en JSON Schema pour vous. Le décorateur Python accepte également directement un dictionnaire [JSON Schema](https://json-schema.org/understanding-json-schema/about) complet lorsque vous avez besoin d'énumérations, de plages, de champs optionnels ou d'objets imbriqués.36* **Schéma d'entrée :** les arguments que l'outil accepte, déclarés selon le langage :
37 * **TypeScript** : un [schéma Zod](https://zod.dev/). Les `args` du gestionnaire tirent leurs types de celui-ci. Appelez `.describe()` sur un champ pour lui donner une description que Claude voit.
38 * **Python** : un dictionnaire mappant les noms aux types, comme `{"latitude": float}`, que le SDK convertit en JSON Schema pour vous. Enveloppez un type dans `Annotated`, comme `{"latitude": Annotated[float, "Latitude coordinate"]}`, pour donner au champ une description que Claude voit. Le décorateur accepte également directement un dictionnaire [JSON Schema](https://json-schema.org/understanding-json-schema/about) complet lorsque vous avez besoin d'énumérations, de plages, de champs optionnels ou d'objets imbriqués.
36* **Gestionnaire :** la fonction asynchrone qui s'exécute lorsque Claude appelle l'outil. Elle reçoit les arguments validés et doit retourner un objet avec :39* **Gestionnaire :** la fonction asynchrone qui s'exécute lorsque Claude appelle l'outil. Elle reçoit les arguments validés et doit retourner un objet avec :
37 * `content` (obligatoire) : un tableau de blocs de résultats, chacun avec un `type` de `"text"`, `"image"`, `"audio"`, `"resource"` ou `"resource_link"`. Voir [Retourner des images et des ressources](#return-images-and-resources) pour les blocs non-texte.40 * `content` (obligatoire) : un tableau de blocs de résultats, chacun avec un `type` de `"text"`, `"image"`, `"audio"`, `"resource"` ou `"resource_link"`. Voir [Retourner des images et des ressources](#return-images-and-resources) pour les blocs non-texte.
38 * `structuredContent` (optionnel) : un objet JSON contenant le résultat sous forme de données lisibles par machine, retourné aux côtés de `content`. Voir [Retourner des données structurées](#return-structured-data).41 * `structuredContent` (optionnel) : un objet JSON contenant le résultat sous forme de données lisibles par machine, retourné aux côtés de `content`. Voir [Retourner des données structurées](#return-structured-data).
40 43
41Après avoir défini un outil, enveloppez-le dans un serveur avec [`createSdkMcpServer`](/docs/fr/agent-sdk/typescript#createsdkmcpserver) (TypeScript) ou [`create_sdk_mcp_server`](/docs/fr/agent-sdk/python#create_sdk_mcp_server) (Python). Le serveur s'exécute en processus dans votre application, pas en tant que processus séparé.44Après avoir défini un outil, enveloppez-le dans un serveur avec [`createSdkMcpServer`](/docs/fr/agent-sdk/typescript#createsdkmcpserver) (TypeScript) ou [`create_sdk_mcp_server`](/docs/fr/agent-sdk/python#create_sdk_mcp_server) (Python). Le serveur s'exécute en processus dans votre application, pas en tant que processus séparé.
42 45
46Les exemples Python de cette page qui effectuent des requêtes HTTP utilisent [httpx](https://www.python-httpx.org/). Ajoutez-le avec le gestionnaire de paquets utilisé par votre projet :
47
48<Tabs>
49 <Tab title="Python (uv)">
50 ```bash theme={null}
51 uv add httpx
52 ```
53 </Tab>
54
55 <Tab title="Python (pip)">
56 ```bash theme={null}
57 pip install httpx
58 ```
59 </Tab>
60</Tabs>
61
43<h3 id="weather-tool-example">62<h3 id="weather-tool-example">
44 Exemple d'outil météo63 Exemple d'outil météo
45</h3>64</h3>
46 65
47Cet exemple définit un outil `get_temperature` et l'enveloppe dans un serveur MCP. Il configure uniquement l'outil ; pour le transmettre à `query` et l'exécuter, voir [Appeler un outil personnalisé](#call-a-custom-tool) ci-dessous.66Cet exemple définit un outil `get_temperature` et l'enveloppe dans un serveur MCP, sans transmettre le serveur à `query`. Pour exécuter l'outil, voir [Appeler un outil personnalisé](#call-a-custom-tool) ci-dessous.
48 67
49<CodeGroup>68<CodeGroup>
50 ```python Python theme={null}69 ```python Python theme={null}
51 from typing import Any70 from typing import Annotated, Any
52 import httpx71 import httpx
53 from claude_agent_sdk import tool, create_sdk_mcp_server72 from claude_agent_sdk import tool, create_sdk_mcp_server
54 73
57 @tool(76 @tool(
58 "get_temperature",77 "get_temperature",
59 "Get the current temperature at a location",78 "Get the current temperature at a location",
60 {"latitude": float, "longitude": float},79 {
80 "latitude": Annotated[float, "Latitude coordinate"],
81 "longitude": Annotated[float, "Longitude coordinate"],
82 },
61 )83 )
62 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:84 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:
63 async with httpx.AsyncClient() as client:85 async with httpx.AsyncClient() as client:
128 150
129Consultez la référence TypeScript [`tool()`](/docs/fr/agent-sdk/typescript#tool) ou la référence Python [`@tool`](/docs/fr/agent-sdk/python#tool) pour les détails complets des paramètres, y compris les formats de schéma d'entrée JSON et la structure de la valeur de retour.151Consultez la référence TypeScript [`tool()`](/docs/fr/agent-sdk/typescript#tool) ou la référence Python [`@tool`](/docs/fr/agent-sdk/python#tool) pour les détails complets des paramètres, y compris les formats de schéma d'entrée JSON et la structure de la valeur de retour.
130 152
131<Tip>153<h3 id="make-a-parameter-optional">
132 Pour rendre un paramètre optionnel : en TypeScript, ajoutez `.optional()` au champ Zod et appliquez la valeur par défaut dans le gestionnaire. En Python, le schéma dict traite chaque clé comme obligatoire, donc omettez le paramètre du schéma, mentionnez-le dans la chaîne de description, et lisez-le avec `args.get()` dans le gestionnaire. L'outil [`get_precipitation_chance` ci-dessous](#add-more-tools) montre les deux modèles.154 Rendre un paramètre optionnel
133</Tip>155</h3>
156
157Pour rendre un paramètre optionnel, déclarez-le comme optionnel dans le schéma et appliquez la valeur par défaut dans le gestionnaire :
158
159* **TypeScript** : ajoutez `.optional()` au champ Zod.
160* **Python** : le schéma dict exige chaque clé. Utilisez la forme JSON Schema, omettez le paramètre de `required`, et lisez-le avec `args.get()`. Pour un schéma typé avec des clés optionnelles, voir [Classe TypedDict](/docs/fr/agent-sdk/python#input-schema-options).
161
162L'outil [`get_precipitation_chance` ci-dessous](#add-more-tools) montre les deux modèles.
134 163
135<h3 id="call-a-custom-tool">164<h3 id="call-a-custom-tool">
136 Appeler un outil personnalisé165 Appeler un outil personnalisé
182 ```211 ```
183</CodeGroup>212</CodeGroup>
184 213
185Combinez cet extrait avec les définitions d'outil et de serveur de l'[exemple d'outil météo](#weather-tool-example) dans un seul fichier, puis exécutez-le avec `python weather.py` pour Python ou `npx tsx weather.ts` pour TypeScript. Claude appelle `get_temperature` et le script affiche une réponse d'une ligne avec la température actuelle à San Francisco.214Combinez cet extrait avec les définitions d'outil et de serveur de l'[exemple d'outil météo](#weather-tool-example) dans un seul fichier, `weather.py` ou `weather.ts`, puis exécutez-le depuis votre terminal :
215
216<Tabs>
217 <Tab title="TypeScript">
218 ```bash theme={null}
219 npx tsx weather.ts
220 ```
221 </Tab>
222
223 <Tab title="Python (uv)">
224 ```bash theme={null}
225 uv run weather.py
226 ```
227 </Tab>
228
229 <Tab title="Python (pip)">
230 Activez l'environnement virtuel dans lequel vous avez installé le SDK, puis exécutez :
231
232 ```bash theme={null}
233 python weather.py
234 ```
235 </Tab>
236</Tabs>
237
238Claude appelle `get_temperature` et le script affiche une réponse d'une ligne avec la température actuelle à San Francisco.
186 239
187<h3 id="add-more-tools">240<h3 id="add-more-tools">
188 Ajouter plus d'outils241 Ajouter plus d'outils
197 # Define a second tool for the same server250 # Define a second tool for the same server
198 @tool(251 @tool(
199 "get_precipitation_chance",252 "get_precipitation_chance",
200 "Get the hourly precipitation probability for a location. "253 "Get the hourly precipitation probability for a location",
201 "Optionally pass 'hours' (1-24) to control how many hours to return.",254 {
202 {"latitude": float, "longitude": float},255 "type": "object",
256 "properties": {
257 "latitude": {"type": "number"},
258 "longitude": {"type": "number"},
259 "hours": {
260 "type": "integer",
261 "minimum": 1,
262 "maximum": 24,
263 "description": "How many hours of forecast to return",
264 },
265 },
266 # 'hours' is left out of required, so Claude can omit it
267 "required": ["latitude", "longitude"],
268 },
203 )269 )
204 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:270 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:
205 # 'hours' isn't in the schema - read it with .get() to make it optional271 # 'hours' isn't in required - read it with .get() to fall back to a default
206 hours = args.get("hours", 12)272 hours = args.get("hours", 12)
207 async with httpx.AsyncClient() as client:273 async with httpx.AsyncClient() as client:
208 response = await client.get(274 response = await client.get(
