Herramientas para VoiceAgent

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`).
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": ["[email protected]", "[email protected]"]). 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 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 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:

{
  "customer_id": "abc123",
  "attendee": {
    "email": "[email protected]"
  },
  "recipients": ["[email protected]", "[email protected]"]
}

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:

Ve a la sección Escenarios y Guardrails de la configuración del VoiceAgent.
Crea un nuevo Escenario o edita uno existente.
Define la situación en la que debe usarse la Herramienta.
En el campo Acción, selecciona Tool Call.
En el menú desplegable Herramientas, elige la Herramienta que quieres que use el VoiceAgent.
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 — estamos aquí para ayudarte.

Primeros pasos

Números y portabilidad

IA

AI Sales Dialer

CloudTalk Phone y Go

Mensajería

Dashboard

Integraciones

Facturación y suscripción

Novedades y actualizaciones técnicas

Dashboard antiguo

¿Qué son las Herramientas?

Cómo crear una Herramienta

Referencia de los campos de la herramienta

Cómo funcionan los parámetros

Tipos de parámetros

Parámetros de ruta

Parámetros del cuerpo

Asignar Herramientas a los VoiceAgents

Consejos para usar las Herramientas de forma eficaz

​¿Qué son las Herramientas?

​Cómo crear una Herramienta

​Referencia de los campos de la herramienta

​Cómo funcionan los parámetros

​Tipos de parámetros

​Parámetros de ruta

​Parámetros del cuerpo

​Asignar Herramientas a los VoiceAgents

​Consejos para usar las Herramientas de forma eficaz

¿Qué son las Herramientas?

Cómo crear una Herramienta

Referencia de los campos de la herramienta

Cómo funcionan los parámetros

Tipos de parámetros

Parámetros de ruta

Parámetros del cuerpo

Asignar Herramientas a los VoiceAgents

Consejos para usar las Herramientas de forma eficaz