> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Outils webhook Les **outils** permettent à votre assistant de se connecter à des données et systèmes externes. Vous pouvez définir un ensemble d'outils auxquels l'assistant a accès, qu'il utilisera lorsque cela est pertinent en fonction de la conversation. ## Présentation De nombreuses applications nécessitent que les assistants appellent des API externes pour obtenir des informations en temps réel. Les outils permettent à votre assistant d'effectuer des appels de fonction externes vers des applications tierces afin d'obtenir des informations en temps réel. Voici quelques exemples où les outils peuvent être utiles : * **Récupérer des données** : permettez à un assistant de récupérer des données en temps réel depuis toute base de données compatible REST ou intégration tierce avant de répondre à l'utilisateur. * **Effectuer une action** : permettez à un assistant de déclencher des actions authentifiées selon la conversation, comme planifier des réunions ou initier des retours de commande. > **Info** > > Pour interagir avec des interfaces utilisateur d'applications ou déclencher des événements côté client, utilisez plutôt les [outils client](/docs/fr/eleven-agents/customization/tools/client-tools). ## Configuration des outils Les agents ElevenLabs peuvent être équipés d'outils pour interagir avec des API externes. Contrairement aux requêtes traditionnelles, l'assistant génère dynamiquement les paramètres de requête, de corps et de chemin selon la conversation et les descriptions de paramètres que vous fournissez. Toutes les configurations d'outils et descriptions de paramètres aident l'assistant à déterminer **quand** et **comment** utiliser ces outils. Pour orchestrer efficacement leur utilisation, mettez à jour le prompt système de l'assistant afin de préciser la séquence et la logique de ces appels. Cela comprend : * **Quel outil** utiliser et dans quelles conditions. * **Quels paramètres** l'outil nécessite pour fonctionner correctement. * **Comment traiter** les réponses. \ #### Configuration Définissez un `Name` et une `Description` de haut niveau pour décrire l'objectif de l'outil. Cela aide le LLM à comprendre l'outil et à savoir quand l'appeler. > **Info** > > Si l'API requiert des paramètres de chemin, incluez des variables dans le chemin de l'URL en les plaçant entre > accolades `{}`, par exemple : `/api/resource/{id}`, où `id` est un paramètre de chemin. ![Configuration](/docs/_fern-img/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5.webp) #### Authentification Configurez l'authentification en ajoutant des en-têtes personnalisés ou en utilisant des méthodes d'authentification prêtes à l'emploi via des connexions d'authentification. ![Authentification de l'outil](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp) #### En-têtes Indiquez les en-têtes à inclure dans la requête. ![En-têtes](/docs/_fern-img/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66.webp) #### Paramètres de chemin Incluez des variables dans le chemin de l'URL en les plaçant entre accolades `{}` : * **Exemple** : `/api/resource/{id}`, où `id` est un paramètre de chemin. ![Paramètres de chemin](/docs/_fern-img/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d.webp) #### Paramètres du corps Indiquez les paramètres du corps à inclure dans la requête. ![Paramètres du corps](/docs/_fern-img/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205.webp) ### Type de contenu Configurez le format d'encodage du corps de la requête : * **JSON** (par défaut) : envoie les paramètres du corps au format `application/json` * **Encodé en URL** : envoie les paramètres du corps au format `application/x-www-form-urlencoded` Le format encodé en URL est utile lors de l'intégration avec des API qui nécessitent l'envoi de données de formulaire, par exemple : * Systèmes hérités qui n'acceptent que les requêtes encodées en formulaire * Points de terminaison de jetons OAuth * API de traitement des paiements * Intégrations tierces avec des exigences spécifiques de type de contenu > **Info** > > Le paramètre de type de contenu s'applique uniquement aux requêtes POST, PUT et PATCH avec des paramètres de corps. #### Paramètres de requête Indiquez les paramètres de requête à inclure dans la requête. ![Paramètres de requête](/docs/_fern-img/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e.webp) #### Attribution de variables dynamiques Indiquez les variables dynamiques à mettre à jour à partir de la réponse de l'outil pour les utiliser plus tard dans la conversation. ![Paramètres de requête](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) ## Guide Dans ce guide, nous allons créer un assistant météo capable de fournir des informations météorologiques en temps réel pour n'importe quel lieu. L'assistant utilisera ses connaissances géographiques pour convertir les noms de lieux en coordonnées et récupérer des données météorologiques précises. #### Configurer l'outil météo L'outil météo envoie des requêtes GET à `https://api.open-meteo.com/v1/forecast`, avec `latitude` et `longitude` comme paramètres de chemin fournis par le LLM. #### Ajouter via le Dashboard Dans la section **Agent** de la page des paramètres de votre agent, choisissez **Add Tool**. Sélectionnez **Webhook** comme type d'outil, puis configurez l'intégration de l'API météo avec les valeurs suivantes : | Champ | Valeur | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Nom | get_weather | | Description | Récupère les prévisions météo actuelles pour un lieu | | Méthode | GET | | URL | [https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\¤t=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m](https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\¤t=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m) | Ajoutez deux paramètres de chemin avec le type de valeur `LLM Prompt` : | Type de données | Identifiant | Description | | --------------- | ----------- | --------------------------------------- | | string | latitude | Coordonnée de latitude du lieu demandé | | string | longitude | Coordonnée de longitude du lieu demandé | #### Ajouter via la CLI #### Créer un fichier de configuration d'outil Enregistrez ce qui suit sous `tool_configs/get_weather.json` : ```json { "type": "webhook", "name": "get_weather", "description": "Gets the current weather forecast for a location", "api_schema": { "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", "method": "GET", "path_params_schema": { "latitude": { "type": "string", "description": "The latitude coordinate for the requested location" }, "longitude": { "type": "string", "description": "The longitude coordinate for the requested location" } } } } ``` #### Ajouter l'outil ```bash elevenlabs tools add "get_weather" --type "webhook" --config-path ./tool_configs/get_weather.json ``` #### Référencer l'outil depuis votre agent Modifiez `agent_configs/.json` et ajoutez l'ID de l'outil à `conversation_config.agent.prompt.tool_ids`, puis envoyez les modifications : ```bash elevenlabs agents push --agent "" ``` #### Ajouter via l'API ```python from elevenlabs import ElevenLabs, ToolRequestModel elevenlabs = ElevenLabs() tool = elevenlabs.conversational_ai.tools.create( request=ToolRequestModel( tool_config={ "type": "webhook", "name": "get_weather", "description": "Gets the current weather forecast for a location", "api_schema": { "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", "method": "GET", "path_params_schema": { "latitude": { "type": "string", "description": "The latitude coordinate for the requested location", }, "longitude": { "type": "string", "description": "The longitude coordinate for the requested location", }, }, }, } ) ) elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", conversation_config={ "agent": {"prompt": {"tool_ids": [tool.id]}}, }, ) ``` ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); const tool = await elevenlabs.conversationalAi.tools.create({ toolConfig: { type: "webhook", name: "get_weather", description: "Gets the current weather forecast for a location", apiSchema: { url: "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", method: "GET", pathParamsSchema: { latitude: { type: "string", description: "The latitude coordinate for the requested location", }, longitude: { type: "string", description: "The longitude coordinate for the requested location", }, }, }, }, }); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { prompt: { toolIds: [tool.id] } }, }, }); ``` > **Warning** > > Une clé API n'est pas requise pour cet outil. Si elle est requise, transmettez-la dans les en-têtes et stockez-la comme secret. #### Orchestration Configurez votre assistant pour traiter intelligemment les requêtes météo avec ce prompt système : **`Prompt système`** ```plaintext Prompt système You are a helpful conversational agent with access to a weather tool. When users ask about weather conditions, use the get_weather tool to fetch accurate, real-time data. The tool requires a latitude and longitude - use your geographic knowledge to convert location names to coordinates accurately. Never ask users for coordinates - you must determine these yourself. Always report weather information conversationally, referring to locations by name only. For weather requests: 1. Extract the location from the user's message 2. Convert the location to coordinates and call get_weather 3. Present the information naturally and helpfully For non-weather queries, provide friendly assistance within your knowledge boundaries. Always be concise, accurate, and helpful. First message: "Hey, how can I help you today?" ``` > **Success** > > Testez votre assistant en posant des questions sur la météo dans différents lieux. L'assistant doit > traiter les lieux précis (« Quel temps fait-il à Tokyo ? ») et demander des précisions après des requêtes générales (« Quel temps fait-il aujourd'hui ? »). ## Méthodes d'authentification prises en charge ElevenLabs Agents prend en charge plusieurs méthodes d'authentification pour connecter de manière sécurisée vos outils à des API externes. Les méthodes d'authentification sont configurées dans les paramètres de votre agent, puis connectées aux outils individuels selon vos besoins. ![Connexion d'authentification du Workspace](/docs/_fern-img/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1.webp) Une fois configurées, vous pouvez connecter ces méthodes d'authentification à vos outils et gérer des en-têtes personnalisés dans la configuration de l'outil : ![Connexion d'authentification de l'outil](/docs/_fern-img/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9.webp) #### Identifiants client OAuth2 Gère automatiquement le flux d'identifiants client OAuth2. Configurez-le avec votre ID client, votre secret client et l'URL de jeton (par exemple, `https://api.example.com/oauth/token`). Vous pouvez également spécifier des portées sous forme de valeurs séparées par des virgules et des paramètres JSON supplémentaires. Configurez-le en cliquant sur **Add Auth** dans **Workspace Auth Connections**, dans la section **Agent** de la page des paramètres de votre agent. #### JWT OAuth2 Utilise l'authentification JSON Web Token pour le flux JWT Bearer OAuth 2.0. Nécessite votre secret de signature JWT, l'URL de jeton et l'algorithme (par défaut : HS256). Configurez les revendications JWT, notamment l'émetteur, l'audience et le sujet. Vous pouvez également définir l'ID de clé, l'expiration (par défaut : 3 600 secondes), les portées et des paramètres supplémentaires. Configurez-le en cliquant sur **Add Auth** dans **Workspace Auth Connections**, dans la section **Agent** de la page des paramètres de votre agent. #### Authentification de base Authentification simple par nom d'utilisateur et mot de passe pour les API qui prennent en charge HTTP Basic Auth. Configurez-la en cliquant sur **Add Auth** dans **Workspace Auth Connections**, dans la section **Agent** de la page des paramètres de votre agent. #### Jetons Bearer Authentification par jeton qui ajoute la valeur de votre jeton Bearer à l'en-tête de la requête. Configurez-la en ajoutant un en-tête à la configuration de l'outil, en sélectionnant **Secret** comme type d'en-tête, puis en cliquant sur **Create New Secret**. #### En-têtes personnalisés Ajoutez des en-têtes d'authentification personnalisés avec le nom et la valeur de votre choix pour les méthodes d'authentification propriétaires. Configurez-les en ajoutant un en-tête à la configuration de l'outil et en indiquant son **nom** et sa **valeur**. ## Bonnes pratiques #### Nommez les outils de manière intuitive, avec des descriptions détaillées Si vous constatez que l'assistant n'appelle pas les bons outils, vous devrez peut-être mettre à jour les noms et descriptions de vos outils afin qu'il comprenne plus clairement quand sélectionner chaque outil. Évitez d'utiliser des abréviations ou des acronymes pour raccourcir les noms des outils et des arguments. Vous pouvez également inclure des descriptions détaillées indiquant quand un outil doit être appelé. Pour les outils complexes, incluez des descriptions pour chacun des arguments afin d'aider l'assistant à savoir ce qu'il doit demander à l'utilisateur pour recueillir cet argument. #### Nommez les paramètres des outils de manière intuitive, avec des descriptions détaillées Utilisez des noms clairs et descriptifs pour les paramètres des outils. Le cas échéant, précisez dans la description le format attendu pour un paramètre, par exemple YYYY-mm-dd ou dd/mm/yy pour une date. #### Envisagez de fournir des informations supplémentaires sur la manière et le moment d'appeler les outils dans le prompt système de votre assistant Des instructions claires dans votre prompt système peuvent améliorer considérablement la précision des appels d'outils de l'assistant. Par exemple, guidez l'assistant avec des instructions comme celles-ci : ```plaintext Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'. ``` Fournissez du contexte pour les scénarios complexes. Par exemple : ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### Sélection du LLM > **Warning** > > Lorsque vous utilisez des outils, nous recommandons de choisir des modèles à haute capacité de raisonnement comme GPT 6 ou Claude Sonnet 5.5. Il est important de noter que le choix du LLM est déterminant pour la réussite des appels de fonction. Certains LLM peuvent rencontrer des difficultés à extraire les paramètres pertinents de la conversation. ## Sons d'appel d'outil Vous pouvez configurer un son d'ambiance à diffuser pendant l'exécution d'un outil afin d'améliorer l'expérience utilisateur. En savoir plus sur les [sons d'appel d'outil](/docs/fr/eleven-agents/customization/tools/tool-configuration/tool-call-sounds).