> ## Documentation Index
> Fetch the complete documentation index at: https://help.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Herramientas para VoiceAgent
> Configura Herramientas para que tu VoiceAgent realice acciones en tiempo real a través de la API
En este artículo aprenderás cómo las **Herramientas de VoiceAgent** permiten realizar acciones en tiempo real durante llamadas en directo, al permitir que tu VoiceAgent interactúe directamente con sistemas externos a través de la API.
Al aprovechar las Herramientas, puedes convertir a tu VoiceAgent en un solucionador de problemas totalmente capaz, mejorando la automatización y ofreciendo experiencias de cliente más rápidas e inteligentes.
**Nivel de usuario:** Admin
***
¿Qué son las Herramientas?
Las Herramientas permiten que tu VoiceAgent realice acciones específicas durante una llamada, haciendo solicitudes a la API de sistemas de terceros. Puedes configurar exactamente qué hace cada herramienta y cuándo debe activarse en función de la conversación.
**Por ejemplo**:
* Un cliente pregunta: «¿Dónde está mi pedido?» → el VoiceAgent usa una herramienta para obtener la información de seguimiento más reciente.
* Un paciente dice: «¿Puedo cambiar mi cita al viernes?» → el VoiceAgent llama a tu API de reservas para comprobar la disponibilidad y reprogramarla.
**Otros casos de uso de ejemplo:**
* **Obtener datos:**
* Consultar los detalles de un ticket de soporte
* Acceder a información de precios o disponibilidad en tiempo real
* **Ejecutar acciones:**
* Actualizar un contacto en el CRM
* Iniciar un reembolso
***
Cómo crear una Herramienta
Para empezar, ve a **Dashboard > VoiceAgents > Gestión de herramientas**, y luego haz clic en el botón ➕ de la esquina superior derecha o selecciona **Crear una herramienta** para abrir el panel de configuración donde puedes definir cómo funciona tu nueva herramienta.
A continuación se explica cómo configurar cada parte:
Referencia de los campos de la herramienta
| **Campo** | **Descripción** |
| - | - |
| **Nombre de la herramienta** | Un nombre claro y descriptivo que ayuda al VoiceAgent a decidir cuándo usar esta herramienta. Usa nombres como `book_meeting`, `update_contact` o `trigger_refund`. Solo se permiten los siguientes caracteres: `a-z`, `A-Z`, `0-9`, `_`, `-` |
| **Descripción de la herramienta** | Describe en lenguaje natural qué hace la herramienta y cuándo debe usarse. Esto ayuda a la IA a entender en qué situaciones debe activar la herramienta. |
| **Mensaje de espera de respuesta** | Un mensaje breve que el VoiceAgent reproduce mientras espera la respuesta de la API. Esto ayuda a gestionar el silencio durante la ejecución. Ejemplo: `Dame un momento, estoy comprobando eso.` |
| **Método y endpoint** | El método HTTP y el endpoint de la API que llamará la herramienta. Por ejemplo: `GET https://api.example.com/orders` |
| **Encabezados** | Define los encabezados que requiera la API. Suelen ser constantes como `Authorization`, `Content-Type` o encabezados de versión. |
| **Parámetros de ruta** | Se usan para rellenar valores dinámicos dentro de la URL del endpoint (por ejemplo, `#{{customer_id}}` en [`https://api.acme.com/#{{customer_id}}/orders`](https://api.acme.com//orders)). |
| **Parámetros del cuerpo** | Disponible solo para los métodos `POST`, `PUT` y `PATCH`. Define los campos que se enviarán en el cuerpo de la solicitud. |
Cómo funcionan los parámetros
Al definir una herramienta, los parámetros ayudan al VoiceAgent a pasar los valores correctos a tu API. Hay tres tipos principales de parámetros que puedes usar tanto en las definiciones de ruta como en las del cuerpo:
Tipos de parámetros
| **Tipo** | **Descripción** |
| - | - |
| **Constante** | Un valor fijo que permanece igual en cada llamada a la API. Es útil cuando conoces el valor exacto que quieres enviar cada vez. |
| **Parámetro** | Un valor dinámico enviado desde tu system prompt. Aquí haces referencia a un nombre de variable que debe coincidir con el enviado en la solicitud a la API que activa la herramienta. |
| **LLM Prompt** | Una instrucción en lenguaje natural para la IA sobre cómo extraer un valor de la conversación. Es la mejor opción cuando el valor depende de lo que dice quien llama. |
Cada parámetro también tiene un **tipo de dato** que controla cómo se formatea el valor en la solicitud a la API. Los tipos disponibles son:
* **String, Integer, Number, Boolean** funcionan como valores escalares simples.
- **List** envía el valor como un array JSON (por ejemplo, `"recipients": ["a@b.com", "c@d.com"]`). Al seleccionar List, también eliges un tipo de elemento (List of String, List of Integer, etc.). Si el agente extrae un único valor, este se incluye automáticamente en un array de un solo elemento en lugar de generar un error.
* **Object** envía el valor como un objeto JSON. Ten en cuenta que los parámetros de tipo objeto son solo descriptivos: al agente se le indica que el parámetro es un objeto y ve tu descripción, pero no conoce los nombres de campo específicos, por lo que no puede aplicar una estructura interna. Esto funciona bien para payloads simples de traspaso directo.
Parámetros de ruta
Son valores que se colocan directamente en la URL. Se definen usando llaves dentro de la URL del endpoint, como `#{{customer_id}}`.
Así es como funciona en la práctica:
**Endpoint de ejemplo:**\
[`https://api.acme.com/#{{customer_id}}/orders`](https://api.acme.com//orders)
En este caso, `customer_id` se convierte en un parámetro de ruta.
**Si se define como Parámetro:**
| Parámetro | Origen del valor |
| - | - |
| `customer_id` | Variable `customer_identifier` del system prompt |
**Ejemplo de solicitud de activación**:
```
{
"call_number": "++44123123123",
"voice_agent_id": "6819f0e147851f618cd6aed6",
"call_properties": {
"system_prompt": {
"variables": {
"customer_identifier": "abc123",
}
}
}
}
```
Esto genera una llamada a:\
[`https://api.acme.com/abc123/orders`](https://api.acme.com/abc123/orders)
**Para extraer mediante LLM Prompt:**\
Usa una instrucción clara como:\
*«*Extrae el ID de cliente que menciona quien llama si lo proporciona. Si no lo proporciona de forma proactiva, pídeselo.*»*
Parámetros del cuerpo
Para los métodos `POST`, `PUT` y `PATCH`, es posible que necesites enviar un cuerpo de solicitud. Estos funcionan igual que los parámetros de ruta y también pueden usar constantes, variables del system prompt o LLM Prompts.
**Los objetos anidados** se pueden definir usando notación de puntos.
**Ejemplo de definición:**
| **Parámetro** | **Tipo** | **Valor** |
| - | - | - |
| `customer_id` | Parámetro | `customer_identifier` |
| `attendee.email` | LLM Prompt | *«Extrae la dirección de correo electrónico del cliente de la conversación.»* |
| `recipients` | LLM Prompt | *«Extrae todas las direcciones de correo electrónico que menciona quien llama.»* |
**Solicitud de activación**:
```
{
"call_number": "++44123123123",
"voice_agent_id": "6819f0e147851f618cd6aed6",
"call_properties": {
"system_prompt": {
"variables": {
"customer_identifier": "abc123",
}
}
}
}
```
**Esta solicitud generará el siguiente cuerpo:**
```json theme={"system"}
{
"customer_id": "abc123",
"attendee": {
"email": "john@acme.com"
},
"recipients": ["a@b.com", "c@d.com"]
}
```
***
Asignar Herramientas a los VoiceAgents
Las Herramientas permiten que los VoiceAgents realicen acciones específicas durante una llamada, como activar flujos de trabajo externos, enviar datos a otros sistemas o finalizar la llamada. Un mismo VoiceAgent puede usar varias Herramientas, y una misma Herramienta puede usarse en varios VoiceAgents.
Las Herramientas se activan como **acciones dentro de un Escenario de VoiceAgent**. Esto significa que el VoiceAgent usará una Herramienta solo cuando ocurra durante la llamada la situación definida en el Escenario.
Para usar una herramienta dentro de un escenario:
1. Ve a la sección **Escenarios y Guardrails** de la configuración del VoiceAgent.
2. Crea un nuevo **Escenario** o edita uno existente.
3. Define la situación en la que debe usarse la Herramienta.
4. En el campo **Acción**, selecciona **Tool Call**.
5. En el menú desplegable **Herramientas**, elige la Herramienta que quieres que use el VoiceAgent.
6. Guarda la configuración.
Una vez configurado, el VoiceAgent usará automáticamente la Herramienta seleccionada cuando se cumplan las condiciones del escenario durante la llamada.
***
Consejos para usar las Herramientas de forma eficaz
* **Usa nombres de herramienta claros y descriptivos**\
Ponle a cada herramienta un nombre que refleje claramente lo que hace. Evita abreviaturas o códigos internos.
* Bien: `trigger_refund`, `get_order_status`, `book_appointment`
* No tan bien: `rfnd_tool_v1`, `statusQ`, `app_sched_new`
* **Escribe una descripción en lenguaje natural**\
En el campo Descripción de la herramienta, explica cuándo y por qué el VoiceAgent debe usar la herramienta. Para herramientas complejas, añade una breve descripción de cada argumento que el agente necesita recopilar.
***
*¿Necesitas ayuda o tienes alguna pregunta?* Ponte en contacto con nuestro [Portal de atención al cliente](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) — estamos aquí para ayudarte.
## Related topics
- [Herramientas de VoiceAgent: Cal.com](/es/articles/14073361-voiceagent-tools-cal-com.md)
- [VoiceAgents para llamadas entrantes](/es/articles/11399385-voiceagents-for-inbound-calls.md)
- [Activar una llamada de VoiceAgent desde Zapier](/es/articles/11831224-triggering-a-voiceagent-call-from-zapier.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.