> 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 client Les **outils client** permettent à votre assistant d’exécuter des fonctions côté client. Contrairement aux [outils webhook](/docs/fr/eleven-agents/customization/tools/webhook-tools), les outils client permettent à l’assistant d’effectuer des actions telles que le déclenchement d’événements de navigateur, l’exécution de fonctions côté client ou l’envoi de notifications à une interface. ## Vue d’ensemble Les applications peuvent nécessiter que les assistants interagissent directement avec l’environnement de l’utilisateur. Les outils côté client permettent à votre assistant d’effectuer des opérations côté client. Voici quelques exemples où les outils client peuvent être utiles : * **Déclencher des événements d’interface** : permettez à un assistant de déclencher des événements de navigateur, comme des alertes, des fenêtres modales ou des notifications. * **Interagir avec le DOM** : permettez à un assistant de manipuler le Document Object Model (DOM) pour mettre à jour dynamiquement le contenu ou guider les utilisateurs dans des interfaces complexes. > **Info** > > Pour appeler des API côté serveur, utilisez plutôt les [outils webhook](/docs/fr/eleven-agents/customization/tools/webhook-tools). ## Guide ### Prérequis * Un [compte ElevenLabs](https://elevenlabs.io) * Un agent conversationnel ElevenLabs configuré ([créez-en un ici](https://elevenlabs.io/app/agents)) #### Créer un outil côté client Configurez un outil client nommé `logMessage` avec un paramètre de chaîne obligatoire `message` (« Le message à consigner dans la console »). #### Ajouter via le Dashboard Accédez au Dashboard de votre agent. Dans la section **Outils**, cliquez sur **Ajouter un outil**. Assurez-vous que le **type d’outil** est défini sur **Client**. Configurez ensuite les éléments suivants : | Paramètre | Valeur | | ----------- | ---------------------------------------------------------------------------------------- | | Nom | logMessage | | Description | Utilisez cet outil côté client pour consigner un message sur le client de l’utilisateur. | Créez ensuite un paramètre `message` avec la configuration suivante : | Paramètre | Valeur | | --------------- | ------------------------------------------------------------------------------------------------- | | Type de données | Chaîne | | Identifiant | message | | Obligatoire | true | | Description | Le message à consigner dans la console. Veillez à ce que le message soit informatif et pertinent. | ![Configuration de l’outil client logMessage](/docs/_fern-img/f7ed25d49a2a814b76112f3e385d471e0dc8444705e11f2f6fad0bd23f1eae12.webp) #### Ajouter via la CLI #### Créer un fichier de configuration d’outil Enregistrez le contenu suivant dans `tool_configs/log_message.json` : ```json { "type": "client", "name": "logMessage", "description": "Use this client-side tool to log a message to the user's client.", "expects_response": false, "parameters": { "type": "object", "properties": { "message": { "type": "string", "description": "The message to log in the console." } }, "required": ["message"] } } ``` #### Ajouter l’outil ```bash elevenlabs tools add "logMessage" --type "client" --config-path ./tool_configs/log_message.json ``` #### Référencer l’outil depuis votre agent Modifiez `agent_configs/.json` afin d’ajouter 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": "client", "name": "logMessage", "description": "Use this client-side tool to log a message to the user's client.", "expects_response": False, "parameters": { "type": "object", "properties": { "message": { "type": "string", "description": "The message to log in the console.", } }, "required": ["message"], }, } ) ) 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: "client", name: "logMessage", description: "Use this client-side tool to log a message to the user's client.", expectsResponse: false, parameters: { type: "object", properties: { message: { type: "string", description: "The message to log in the console.", }, }, required: ["message"], }, }, }); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { prompt: { toolIds: [tool.id] } }, }, }); ``` #### Enregistrer l’outil client dans votre code Contrairement aux outils webhook, les outils client doivent être enregistrés dans votre code. Utilisez le code suivant pour enregistrer l’outil client : **`Python`** ```python title="Python" focus={4-16} from elevenlabs import ElevenLabs from elevenlabs.conversational_ai.conversation import Conversation, ClientTools def log_message(parameters): message = parameters.get("message") print(message) client_tools = ClientTools() client_tools.register("logMessage", log_message) conversation = Conversation( client=ElevenLabs(api_key="your-api-key"), agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", requires_auth=True, client_tools=client_tools, # ... ) conversation.start_session() ``` **`JavaScript`** ```javascript title="JavaScript" focus={2-10} // ... const conversation = await Conversation.startSession({ // ... clientTools: { logMessage: async ({message}) => { console.log(message); } }, // ... }); ``` **`Swift`** ```swift title="Swift" focus={2-10} // ... var clientTools = ElevenLabsSDK.ClientTools() clientTools.register("logMessage") { parameters async throws -> String? in guard let message = parameters["message"] as? String else { throw ElevenLabsSDK.ClientToolError.invalidParameters } print(message) return message } ``` > **Note** > > Les noms d’outil et de paramètre dans la configuration de l’agent sont sensibles à la casse et **doivent** correspondre à ceux enregistrés dans votre code. #### Tests Démarrez une conversation avec votre agent et dites quelque chose comme : > *Consigne dans la console un message indiquant Hello World* Vous devriez voir un journal `Hello World` apparaître dans votre console. #### Étapes suivantes Maintenant que vous avez configuré un événement côté client de base, vous pouvez : * Explorer des outils client plus complexes, comme l’ouverture de fenêtres modales, la navigation vers des pages ou l’interaction avec le DOM. * Combiner des outils client avec des webhooks côté serveur pour des interactions full stack. * Utiliser des outils client pour renforcer l’engagement des utilisateurs et fournir des retours en temps réel pendant les conversations. ### Transmettre les résultats d’un outil client au contexte de la conversation Lorsque vous souhaitez que votre agent reçoive des données d’un outil client, veillez à cocher l’option **Attendre la réponse** dans la configuration de l’outil. ![Option Attendre la réponse dans la configuration d’un outil client](/docs/_fern-img/0ecc615fc9f25446b67369fd3e010e34b39549a22146a2483ea17251206caf1e.webp) Une fois l’outil client ajouté, lorsque la fonction est appelée, l’agent attend sa réponse et l’ajoute au contexte de la conversation. **`Python`** ```python title="Python" def get_customer_details(): # Fetch customer details (e.g., from an API or database) customer_data = { "id": 123, "name": "Alice", "subscription": "Pro" } # Return the customer data; it can also be a JSON string if needed. return customer_data client_tools = ClientTools() client_tools.register("getCustomerDetails", get_customer_details) conversation = Conversation( client=ElevenLabs(api_key="your-api-key"), agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", requires_auth=True, client_tools=client_tools, # ... ) conversation.start_session() ``` **`JavaScript`** ```javascript title="JavaScript" const clientTools = { getCustomerDetails: async () => { // Fetch customer details (e.g., from an API) const customerData = { id: 123, name: "Alice", subscription: "Pro" }; // Return data directly to the agent. return customerData; } }; // Start the conversation with client tools configured. const conversation = await Conversation.startSession({ clientTools }); ``` Dans cet exemple, lorsque l’agent appelle **getCustomerDetails**, la fonction s’exécute sur le client et l’agent reçoit les données renvoyées, qui sont ensuite utilisées dans le contexte de la conversation. Les valeurs de la réponse peuvent également être affectées à des variables dynamiques, comme avec les [outils webhook](https://elevenlabs.io/docs/eleven-agents/customization/tools/webhook-tools). Notez que les outils système ne peuvent pas mettre à jour les variables dynamiques. ### Résolution des problèmes #### Outils non déclenchés * Assurez-vous que les noms d’outil et de paramètre dans la configuration de l’agent correspondent à ceux enregistrés dans votre code. * Consultez la transcription de la conversation dans le Dashboard de l’agent pour vérifier que l’outil est bien exécuté. #### Erreurs de console * Ouvrez la console du navigateur pour vérifier la présence éventuelle d’erreurs. * Assurez-vous que votre code gère correctement les erreurs liées à des paramètres non définis ou inattendus. ## 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.