> 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. # Herramientas de cliente **Las herramientas de cliente** permiten que tu asistente ejecute funciones del lado del cliente. A diferencia de las [herramientas de webhook](/docs/es/eleven-agents/customization/tools/webhook-tools), las herramientas de cliente permiten al asistente realizar acciones como activar eventos del navegador, ejecutar funciones del lado del cliente o enviar notificaciones a una interfaz. ## Resumen Es posible que las aplicaciones necesiten que los asistentes interactúen directamente con el entorno del usuario. Las herramientas del lado del cliente permiten a tu asistente realizar operaciones del lado del cliente. Estos son algunos ejemplos en los que las herramientas de cliente pueden ser útiles: * **Activar eventos de la interfaz**: permite que un asistente active eventos del navegador, como alertas, modales o notificaciones. * **Interactuar con el DOM**: permite que un asistente manipule el modelo de objetos del documento (DOM) para actualizar contenido dinámicamente o guiar a los usuarios por interfaces complejas. > **Info** > > Para llamar a API del lado del servidor, usa [herramientas de webhook ](/docs/es/eleven-agents/customization/tools/webhook-tools) en su lugar. ## Guía ### Requisitos previos * Una [cuenta de ElevenLabs](https://elevenlabs.io) * Un agente conversacional de ElevenLabs configurado ([crea uno aquí](https://elevenlabs.io/app/agents)) #### Crea una nueva herramienta del lado del cliente Configura una herramienta de cliente llamada `logMessage` con un parámetro de cadena obligatorio `message` ("El mensaje que se registrará en la consola"). #### Añadir desde el panel Ve al panel de tu agente. En la sección **Tools**, haz clic en **Add Tool**. Asegúrate de que **Tool Type** esté configurado como **Client**. Después, configura lo siguiente: | Ajuste | Parámetro | | ----------- | ---------------------------------------------------------------------------------------------- | | Nombre | logMessage | | Descripción | Usa esta herramienta del lado del cliente para registrar un mensaje en el cliente del usuario. | Después, crea un nuevo parámetro `message` con la siguiente configuración: | Ajuste | Parámetro | | ------------- | ----------------------------------------------------------------------------------------- | | Tipo de datos | String | | Identificador | message | | Obligatorio | true | | Descripción | El mensaje que se registrará en la consola. Asegúrate de que sea informativo y relevante. | ![Configuración de la herramienta de cliente logMessage](/docs/_fern-img/f7ed25d49a2a814b76112f3e385d471e0dc8444705e11f2f6fad0bd23f1eae12.webp) #### Añadir mediante la CLI #### Crea un archivo de configuración de la herramienta Guarda lo siguiente como `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"] } } ``` #### Añade la herramienta ```bash elevenlabs tools add "logMessage" --type "client" --config-path ./tool_configs/log_message.json ``` #### Haz referencia a la herramienta desde tu agente Edita `agent_configs/.json` para añadir el ID de la herramienta a `conversation_config.agent.prompt.tool_ids` y, después, envía los cambios: ```bash elevenlabs agents push --agent "" ``` #### Añadir mediante la 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] } }, }, }); ``` #### Registra la herramienta de cliente en tu código A diferencia de las herramientas de webhook, las herramientas de cliente deben registrarse en tu código. Usa el siguiente código para registrar la herramienta de cliente: **`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** > > Los nombres de la herramienta y los parámetros en la configuración del agente distinguen entre mayúsculas y minúsculas y **deben** coincidir con los registrados en tu código. #### Pruebas Inicia una conversación con tu agente y di algo como: > *Registra en la consola un mensaje que diga Hola mundo* Deberías ver un registro de `Hello World` en tu consola. #### Siguientes pasos Ahora que has configurado un evento básico del lado del cliente, puedes: * Explorar herramientas de cliente más complejas, como abrir modales, navegar a páginas o interactuar con el DOM. * Combinar herramientas de cliente con webhooks del lado del servidor para crear interacciones full-stack. * Usar herramientas de cliente para mejorar la interacción del usuario y proporcionar comentarios en tiempo real durante las conversaciones. ### Enviar resultados de herramientas de cliente al contexto de la conversación Cuando quieras que tu agente reciba datos de una herramienta de cliente, asegúrate de marcar la opción **Wait for response** en la configuración de la herramienta. ![Opción Wait for response en la configuración de la herramienta de cliente](/docs/_fern-img/0ecc615fc9f25446b67369fd3e010e34b39549a22146a2483ea17251206caf1e.webp) Una vez añadida la herramienta de cliente, cuando se llame a la función, el agente esperará su respuesta y la añadirá al contexto de la conversación. **`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 }); ``` En este ejemplo, cuando el agente llama a **getCustomerDetails**, la función se ejecutará en el cliente y el agente recibirá los datos devueltos, que después se utilizarán como parte del contexto de la conversación. Los valores de la respuesta también pueden asignarse opcionalmente a variables dinámicas, de forma similar a las [herramientas de webhook](https://elevenlabs.io/docs/eleven-agents/customization/tools/webhook-tools). Ten en cuenta que las herramientas del sistema no pueden actualizar variables dinámicas. ### Resolución de problemas #### Las herramientas no se activan * Asegúrate de que los nombres de la herramienta y los parámetros en la configuración del agente coincidan con los registrados en tu código. * Consulta la transcripción de la conversación en el panel del agente para verificar que se está ejecutando la herramienta. #### Errores en la consola * Abre la consola del navegador para comprobar si hay errores. * Asegúrate de que tu código incluya la gestión de errores necesaria para parámetros indefinidos o inesperados. ## Buenas prácticas #### Usa nombres intuitivos para las herramientas y descripciones detalladas Si ves que el asistente no llama a las herramientas correctas, quizá debas actualizar los nombres y las descripciones de tus herramientas para que el asistente entienda mejor cuándo debe seleccionar cada una. Evita usar abreviaturas o acrónimos para acortar los nombres de las herramientas y los argumentos. También puedes incluir descripciones detalladas de cuándo se debe llamar a una herramienta. Para herramientas complejas, incluye descripciones de cada argumento para ayudar al asistente a saber qué debe pedir al usuario para recopilar ese argumento. #### Usa nombres intuitivos para los parámetros de las herramientas y descripciones detalladas Usa nombres claros y descriptivos para los parámetros de las herramientas. Si procede, especifica en la descripción el formato esperado para un parámetro (por ejemplo, YYYY-mm-dd o dd/mm/yy para una fecha). #### Considera proporcionar información adicional sobre cómo y cuándo llamar a las herramientas en el prompt de sistema de tu asistente Dar instrucciones claras en el prompt de sistema puede mejorar considerablemente la precisión de las llamadas a herramientas del asistente. Por ejemplo, guía al asistente con instrucciones como las siguientes: ```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?'. ``` Proporciona contexto para situaciones complejas. Por ejemplo: ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### Selección del LLM > **Warning** > > Al usar herramientas, recomendamos elegir modelos de alta inteligencia como GPT 6 o Claude Sonnet 5.5. Es importante tener en cuenta que la elección del LLM influye en el éxito de las llamadas a funciones. Algunos LLM pueden tener dificultades para extraer de la conversación los parámetros relevantes.