Agente de voz IA

Creación de herramientas personalizadas

Aprende a crear una herramienta personalizada en E-Smart360 para conectar tu agente de voz con APIs externas.

Información básica

Name — Etiqueta que se muestra en la interfaz de E-Smart360 y se referencia en los flujos. Elige un nombre descriptivo y único (p. ej., CheckAvailability en lugar de Get).
Description — Explicación concisa del propósito de la herramienta. Es crítica porque el LLM usa la descripción para decidir cuándo activar la herramienta.
Pre-call (Speech) Message (opcional) — Mensaje que dirá tu agente mientras la herramienta se ejecuta. Por ejemplo: «Un momento mientras compruebo eso.» Así la conversación se siente natural, incluso mientras espera la respuesta de la API.

Nombre, descripción y mensaje previo a la llamada

Configuración de la API

Configura cómo tu herramienta se comunica con servicios externos:

API URL — Endpoint al que se llama (p. ej., https://api.example.com/check).
HTTP Method — Tipo de solicitud (GET, POST, PUT, DELETE).
API Token / Headers (opcional) — Detalles de autenticación, como bearer tokens o cabeceras personalizadas.

Esta configuración garantiza que la herramienta sepa exactamente dónde enviar los datos y cómo solicitarlos de forma segura.

Configuración de parámetros

Los parámetros permiten que tu herramienta capture y use información dinámica obtenida del usuario durante la conversación.

En lugar de valores fijos, los parámetros hacen que las llamadas a la API sean flexibles, reutilizables y personalizadas.

Qué son: Piensa en los parámetros como campos de entrada que el LLM rellenará con valores proporcionados por el usuario (como startTime o endTime).

Por qué importan: Sin parámetros, cada llamada a la API devolvería resultados estáticos. Con parámetros, la herramienta puede adaptarse a las necesidades de cada usuario.

Cómo configurar parámetros:

Asigna un Name — p. ej., startTime.
Elige un Data Type — p. ej., string, number o boolean.
Añade una Description — Explica qué representa el parámetro para que el LLM sepa cómo y cuándo recopilarlo.
Marca Required u Optional — Indica parámetros obligatorios (p. ej., fecha de reserva) frente a opcionales (p. ej., una nota).

Ejemplo:

startTime (String, Required) → "Hora de inicio de la reserva."

endTime (String, Required) → "Hora de fin de la reserva."

Durante una llamada, el agente pedirá estos valores si aún no se han proporcionado y los insertará dinámicamente en la solicitud a la API.

Configuración de parámetros startTime y endTime

Después, pulsa el botón Create Tool para guardar la herramienta en el agente.

Definir una herramienta personalizada con JSON

También puedes configurar la herramienta directamente mediante JSON.

Así podría verse una definición de herramienta en JSON, reflejando la interfaz de E-Smart360:

{
  "key": "custom_task",
  "name": "Test Task",
  "description": "Ejecuta una llamada de prueba a la API durante la conversación.",
  "pre_call_message": "Dame un momento, enseguida vuelvo.",
  "parameters": {
    "type": "object",
    "required": [],
    "properties": {
      "startTime": {
        "type": "string",
        "description": "Hora de inicio de la tarea"
      },
      "endTime": {
        "type": "string",
        "description": "Hora de fin de la tarea"
      }
    }
  },
  "value": {
    "method": "GET",
    "param": {
      "startTime": "%(startTime)s",
      "endTime": "%(endTime)s"
    },
    "url": "https://api.example.com/test",
    "api_token": "Bearer YOUR_API_TOKEN"
  }
}

A continuación, más ejemplos.

JSON para función de reserva de citas

{
  "key": "custom_task",
  "name": "Book Appointment",
  "description": "Programa una nueva cita para el usuario con los datos proporcionados.",
  "pre_call_message": "Déjame programar esa cita para ti...",
  "parameters": {
    "type": "object",
    "required": [
      "customerName",
      "appointmentDate",
      "startTime",
      "endTime",
      "serviceType"
    ],
    "properties": {
      "customerName": {
        "type": "string",
        "description": "Nombre completo del cliente que reserva la cita."
      },
      "appointmentDate": {
        "type": "string",
        "description": "Fecha de la cita en formato YYYY-MM-DD."
      },
      "startTime": {
        "type": "string",
        "description": "Hora de inicio de la cita en formato HH:MM (24 horas)."
      },
      "endTime": {
        "type": "string",
        "description": "Hora de fin de la cita en formato HH:MM (24 horas)."
      },
      "serviceType": {
        "type": "string",
        "description": "Tipo de servicio de la cita (p. ej., consulta, fotografía, peluquería)."
      },
      "notes": {
        "type": "string",
        "description": "Notas adicionales o solicitudes especiales opcionales para la cita."
      }
    }
  },
  "value": {
    "method": "POST",
    "url": "https://api.example.com/appointments",
    "api_token": "Bearer YOUR_API_TOKEN",
    "param": {
      "customerName": "%(customerName)s",
      "appointmentDate": "%(appointmentDate)s",
      "startTime": "%(startTime)s",
      "endTime": "%(endTime)s",
      "serviceType": "%(serviceType)s",
      "notes": "%(notes)s"
    }
  }
}

JSON para función de búsqueda de vuelos

{
  "key": "search_flights",
  "name": "Search Flights",
  "description": "Obtiene vuelos disponibles según el origen, destino, fecha de viaje y número de pasajeros indicados por el usuario.",
  "pre_call_message": "Déjame buscar vuelos disponibles para ti...",
  "parameters": {
    "type": "object",
    "required": ["origin", "destination", "departureDate", "passengers"],
    "properties": {
      "origin": {
        "type": "string",
        "description": "Código del aeropuerto de salida (p. ej., JFK, LAX)."
      },
      "destination": {
        "type": "string",
        "description": "Código del aeropuerto de llegada (p. ej., LHR, DXB)."
      },
      "departureDate": {
        "type": "string",
        "description": "Fecha de salida del vuelo en formato YYYY-MM-DD."
      },
      "returnDate": {
        "type": "string",
        "description": "Fecha de regreso opcional para vuelos de ida y vuelta en formato YYYY-MM-DD."
      },
      "passengers": {
        "type": "integer",
        "description": "Número de pasajeros."
      },
      "classType": {
        "type": "string",
        "description": "Clase de viaje (p. ej., Economy, Business, First)."
      }
    }
  },
  "value": {
    "method": "GET",
    "url": "https://api.example.com/flights/search",
    "api_token": "Bearer YOUR_API_TOKEN",
    "param": {
      "origin": "%(origin)s",
      "destination": "%(destination)s",
      "departureDate": "%(departureDate)s",
      "returnDate": "%(returnDate)s",
      "passengers": "%(passengers)s",
      "classType": "%(classType)s"
    }
  }
}

Explicación detallada de cada sección

1. name

Etiqueta legible para humanos.
Ejemplo: «Book Appointment» aparecerá en tu interfaz o en los registros.

2. description

Explica qué hace la herramienta.
Ejemplo: «Programa una nueva cita para el usuario con los datos proporcionados.»

3. pre_call_message

Mensaje que el agente dice antes de realizar la llamada a la API.
Ejemplo: «Déjame programar esa cita para ti...»

4. parameters

Define qué entradas se requieren de la conversación.
type: "object" significa que las entradas se pasan como JSON estructurado.
required: lista de campos que deben estar presentes.
properties: definición detallada de cada entrada:
- customerName: persona que reserva.
- appointmentDate: fecha (formato estricto YYYY-MM-DD).
- startTime, endTime: franjas horarias.
- serviceType: tipo de servicio solicitado.
- notes: texto libre opcional.

5. value

Define cómo se realiza la llamada a la API:
- method: "POST" porque la reserva modifica datos en el servidor.
- url: el endpoint (sustituye por tu backend real).
- api_token: autenticación estándar de la API.
- param: payload enviado a la API. Cada campo usa el placeholder %(fieldName)s → se sustituye dinámicamente con la entrada del usuario.

Referencia de campos:

key: identificador único para referencia interna.
name: se muestra en el constructor de flujos.
description: describe la intención de la herramienta.
pre_call_message: mensaje de voz durante la ejecución.
parameters: define variables de entrada mediante JSON schema.
value: detalles de ejecución HTTP de la llamada a la API.

Consejos y consideraciones

Los nombres importan: evita verbos demasiado genéricos como «call» o «get» que puedan entrar en conflicto con acciones integradas. Elige nombres claros y descriptivos que representen de forma única el propósito de la herramienta.
Descripción de la herramienta: es uno de los aspectos más importantes para su activación. El LLM solo invocará una herramienta cuando los escenarios descritos en su descripción coincidan durante la conversación. Redacta la descripción con cuidado para capturar los casos de uso previstos.
Uso de parámetros: define claramente cuáles son obligatorios y cuáles opcionales. Si los referencias después en manejadores de respuesta o plantillas de mensajes, asegúrate de mapearlos correctamente para que la herramienta funcione de forma fiable.
Seguridad: almacena siempre los tokens de API de forma segura. Evita incrustar credenciales sensibles en documentación, capturas de pantalla o interfaces públicas. Usa variables de entorno o prácticas seguras de gestión de configuración.