> 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 webhook Las **herramientas** permiten a tu asistente conectarse a datos y sistemas externos. Puedes definir un conjunto de herramientas a las que el asistente tenga acceso, y este las utilizará cuando corresponda según la conversación. ## Resumen Muchas aplicaciones necesitan que los asistentes llamen a API externas para obtener información en tiempo real. Las herramientas permiten a tu asistente realizar llamadas a funciones externas en aplicaciones de terceros para que puedas obtener información en tiempo real. Estos son algunos ejemplos en los que las herramientas pueden resultar útiles: * **Obtener datos**: permite a un asistente recuperar datos en tiempo real de cualquier base de datos compatible con REST o integración de terceros antes de responder al usuario. * **Realizar acciones**: permite a un asistente activar acciones autenticadas según la conversación, como programar reuniones o iniciar devoluciones de pedidos. > **Info** > > Para interactuar con interfaces de aplicaciones o activar eventos del lado del cliente, usa las [herramientas de cliente](/docs/es/eleven-agents/customization/tools/client-tools). ## Configuración de herramientas Los agentes de ElevenLabs pueden incorporar herramientas para interactuar con API externas. A diferencia de las solicitudes tradicionales, el asistente genera dinámicamente los parámetros de consulta, cuerpo y ruta según la conversación y las descripciones de parámetros que proporciones. Todas las configuraciones de herramientas y las descripciones de parámetros ayudan al asistente a determinar **cuándo** y **cómo** usar estas herramientas. Para organizar el uso de herramientas de forma eficaz, actualiza el prompt del sistema del asistente para especificar la secuencia y la lógica de estas llamadas. Esto incluye: * **Qué herramienta** usar y en qué condiciones. * **Qué parámetros** necesita la herramienta para funcionar correctamente. * **Cómo gestionar** las respuestas. \ #### Configuración Define un `Name` y una `Description` generales que describan el propósito de la herramienta. Esto ayuda al LLM a comprender la herramienta y saber cuándo debe llamarla. > **Info** > > Si la API requiere parámetros de ruta, incluye variables en la ruta de la URL entre llaves > `{}`; por ejemplo: `/api/resource/{id}`, donde `id` es un parámetro de ruta. ![Configuración](/docs/_fern-img/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5.webp) #### Autenticación Configura la autenticación añadiendo encabezados personalizados o utilizando métodos de autenticación integrados mediante conexiones de autenticación. ![Autenticación de la herramienta](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp) #### Encabezados Especifica los encabezados que deben incluirse en la solicitud. ![Encabezados](/docs/_fern-img/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66.webp) #### Parámetros de ruta Incluye variables en la ruta de la URL entre llaves `{}`: * **Ejemplo**: `/api/resource/{id}`, donde `id` es un parámetro de ruta. ![Parámetros de ruta](/docs/_fern-img/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d.webp) #### Parámetros del cuerpo Especifica los parámetros del cuerpo que deben incluirse en la solicitud. ![Parámetros del cuerpo](/docs/_fern-img/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205.webp) ### Tipo de contenido Configura el formato de codificación del cuerpo de la solicitud: * **JSON** (predeterminado): envía los parámetros del cuerpo como `application/json` * **Codificado en URL**: envía los parámetros del cuerpo como `application/x-www-form-urlencoded` El formato codificado en URL resulta útil al integrarse con API que requieren el envío de datos de formulario, como: * Sistemas heredados que solo aceptan solicitudes codificadas como formulario * Rutas de API de tokens OAuth * API de procesamiento de pagos * Integraciones de terceros con requisitos específicos de tipo de contenido > **Info** > > La configuración de tipo de contenido solo se aplica a solicitudes POST, PUT y PATCH con parámetros de cuerpo. #### Parámetros de consulta Especifica los parámetros de consulta que deben incluirse en la solicitud. ![Parámetros de consulta](/docs/_fern-img/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e.webp) #### Asignación dinámica de variables Especifica variables dinámicas que se actualizarán a partir de la respuesta de la herramienta para usarlas más adelante en la conversación. ![Parámetros de consulta](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) ## Guía En esta guía, crearemos un asistente meteorológico que pueda proporcionar información meteorológica en tiempo real para cualquier ubicación. El asistente utilizará sus conocimientos geográficos para convertir los nombres de ubicaciones en coordenadas y obtener datos meteorológicos precisos. #### Configura la herramienta meteorológica La herramienta meteorológica envía solicitudes GET a `https://api.open-meteo.com/v1/forecast` con `latitude` y `longitude` como parámetros de ruta proporcionados por el LLM. #### Añadir desde el panel En la sección **Agent** de la página de configuración de tu agente, selecciona **Add Tool**. Selecciona **Webhook** como tipo de herramienta y, a continuación, configura la integración de la API meteorológica con estos valores: | Campo | Valor | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Nombre | get_weather | | Descripción | Obtiene la previsión meteorológica actual de una ubicación | | Método | 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) | Añade dos parámetros de ruta con el tipo de valor `LLM Prompt`: | Tipo de datos | Identificador | Descripción | | ------------- | ------------- | ---------------------------------------------------- | | string | latitude | La coordenada de latitud de la ubicación solicitada | | string | longitude | La coordenada de longitud de la ubicación solicitada | #### Añadir mediante la CLI #### Crea un archivo de configuración de herramienta Guarda lo siguiente como `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" } } } } ``` #### Añade la herramienta ```bash elevenlabs tools add "get_weather" --type "webhook" --config-path ./tool_configs/get_weather.json ``` #### Haz referencia a la herramienta desde tu agente Edita `agent_configs/.json` y añade el ID de la herramienta a `conversation_config.agent.prompt.tool_ids`; después, envíalo: ```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": "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** > > Esta herramienta no requiere una clave de API. Si fuera necesaria, debería incluirse en los encabezados y almacenarse como secreto. #### Orquestación Configura tu asistente para gestionar consultas meteorológicas de forma inteligente con este prompt del sistema: **`Prompt del sistema`** ```plaintext Prompt del sistema 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** > > Prueba tu asistente preguntando por el tiempo en distintas ubicaciones. El asistente debería > gestionar ubicaciones específicas ("¿Qué tiempo hace en Tokio?") y pedir aclaraciones tras consultas generales ("¿Qué > tiempo hace hoy?"). ## Métodos de autenticación compatibles ElevenLabs Agents admite varios métodos de autenticación para conectar de forma segura tus herramientas con API externas. Los métodos de autenticación se configuran en los ajustes de tu agente y después se conectan a cada herramienta según sea necesario. ![Conexión de autenticación del espacio de trabajo](/docs/_fern-img/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1.webp) Una vez configurados, puedes conectar estos métodos de autenticación a tus herramientas y gestionar encabezados personalizados en la configuración de la herramienta: ![Conexión de autenticación de la herramienta](/docs/_fern-img/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9.webp) #### Credenciales de cliente OAuth2 Gestiona automáticamente el flujo de credenciales de cliente OAuth2. Configúralo con tu ID de cliente, secreto de cliente y URL de token (por ejemplo, `https://api.example.com/oauth/token`). Opcionalmente, especifica ámbitos como valores separados por comas y parámetros JSON adicionales. Configúralo haciendo clic en **Add Auth** en **Workspace Auth Connections**, dentro de la sección **Agent** de la página de configuración de tu agente. #### JWT de OAuth2 Utiliza autenticación JSON Web Token para el flujo JWT Bearer de OAuth 2.0. Requiere tu secreto de firma JWT, URL de token y algoritmo (predeterminado: HS256). Configura las reclamaciones JWT, como emisor, audiencia y sujeto. Opcionalmente, establece el ID de clave, la expiración (predeterminada: 3600 segundos), ámbitos y parámetros adicionales. Configúralo haciendo clic en **Add Auth** en **Workspace Auth Connections**, dentro de la sección **Agent** de la página de configuración de tu agente. #### Autenticación básica Autenticación sencilla mediante nombre de usuario y contraseña para API compatibles con HTTP Basic Auth. Configúrala haciendo clic en **Add Auth** en **Workspace Auth Connections**, dentro de la sección **Agent** de la página de configuración de tu agente. #### Tokens Bearer Autenticación basada en tokens que añade el valor de tu token bearer al encabezado de la solicitud. Configúrala añadiendo un encabezado a la configuración de la herramienta, seleccionando **Secret** como tipo de encabezado y haciendo clic en **Create New Secret**. #### Encabezados personalizados Añade encabezados de autenticación personalizados con cualquier nombre y valor para métodos de autenticación propios. Configúralos añadiendo un encabezado a la configuración de la herramienta y especificando su **nombre** y **valor**. ## 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. ## Sonidos de llamadas a herramientas Puedes configurar audio ambiente para que se reproduzca durante la ejecución de herramientas y mejorar así la experiencia de usuario. Obtén más información sobre los [sonidos de llamadas a herramientas](/docs/es/eleven-agents/customization/tools/tool-configuration/tool-call-sounds).