Cómo crear habilidades personalizadas para el agente de IA

Las habilidades HTTP permiten que el agente haga llamadas a APIs externas durante una conversación. Por ejemplo: consultar el stock, verificar el estado de un pedido o registrar datos en un sistema interno.

Disponible en: todos los planes.
Quién puede hacerlo: administradores.

---

Qué son las habilidades

Son acciones que configuras para que el agente las ejecute cuando necesita información externa. Cuando identifica la necesidad, el agente dispara la llamada HTTP configurada y usa los datos devueltos para responder al lead.

Crear una habilidad

1. Ve a Configuración > Base de conocimiento > Habilidades

2. Haz clic en + Crear habilidad

3. Completa el Título de la habilidad (nombre descriptivo que se mostrará)

4. Selecciona HTTP en el campo Tipo

5. Configura las pestañas de abajo

Pestaña Configuración HTTP

Método HTTP: selecciona el método de la solicitud (GET, POST, PUT, PATCH, DELETE)

URL de la API: ingresa la URL completa del endpoint. Usa :variavel para path params dinámicos (ej.: https://api.exemplo.com/v1/users/:userId/orders)

Timeout (ms): tiempo máximo de espera de la respuesta de la API (entre 1.000 y 120.000 ms). El valor predeterminado es 30.000 ms

Headers HTTP: agrega los headers necesarios haciendo clic en + Agregar Header (ej.: Authorization, Content-Type)

Query Parameters: agrega parámetros de URL haciendo clic en + Agregar Parámetro. Para cada parámetro, define el Nombre y la Fuente del valor:

• Valor fijo — texto literal, igual en todas las llamadas (ej.: v2 en api_version)

• Campo inteligente — el valor viene de un campo del contexto de la conversación (contacto, empresa, conversación), elegido en el selector de campos

• Generado por la IA — la IA extrae el valor de la conversación en tiempo real a partir de un prompt que tú escribes (ej.: “Extrae el número de identificación fiscal que informó el lead”); hay un switch para marcar el campo como obligatorio

Pestaña Auth & Retry

Autenticación: configura cómo se autenticará la habilidad en la API. Los tipos disponibles son:

• Bearer Token: ingresa el token de autenticación

• API key: ingresa la clave de API

• HMAC (firma): Nuvia firma cada solicitud con un secreto compartido (ver abajo)

Autenticación HMAC (firma por solicitud)

Algunas APIs no aceptan un token fijo: exigen que cada solicitud esté firmada con un secreto, para demostrar que la llamada es legítima y no fue reutilizada. Es el estándar que usan las pasarelas de pago, los bancos y varias APIs brasileñas hechas en Laravel.

Elige HMAC (firma) en el tipo de autenticación y completa los campos según la documentación de la API que vas a llamar.

Cómo armar la plantilla de la cadena firmada. Usa los marcadores de abajo, separando las líneas con \n:

{method} · {path} · {path_with_query} · {path_relative} · {query} · {url} · {host} · {body} · {body_sha256_hex} · {timestamp} · {api_key}

El botón Usar formato común completa la plantilla con {method}\n{path_with_query}\n{timestamp}\n{body} y ajusta el formato del timestamp a ISO 8601 microsegundos — la combinación más frecuente. Si la API que usas pide otro orden, edítala a mano.

Dónde se envía la firma. Por defecto, Nuvia envía tres headers separados, cuyos nombres puedes cambiar:

Header único (opcional). Algunas APIs piden todo empaquetado en un solo header. Completa Nombre del header único (ej.: X-Auth) y Plantilla del valor del header (ej.: hmac {api_key}:{timestamp}:{signature}), usando los marcadores {api_key}, {timestamp} y {signature}.

Cuando completas la plantilla del header único, los campos de nombre del header de API key y de firma desaparecen de la pantalla, porque dejan de usarse. El header de timestamp se sigue enviando por separado.

Retry (Reintentos): define el comportamiento en caso de falla en la llamada:

• Máx. intentos: número máximo de intentos (1 a 10)

• Delay (ms): intervalo inicial entre intentos

• Multiplicador: factor de backoff exponencial entre intentos

Pestaña Parámetros

Define los parámetros que el agente extrae de la conversación para usarlos en la llamada. Configúralos con el Parameters Schema (JSON Schema):

• Nombre del campo: identificador del parámetro

• Tipo: tipo de dato (Texto, Número, etc.)

• Descripción: instrucción para el agente sobre cómo extraer ese valor de la conversación

Haz clic en + Agregar propiedad para incluir nuevos parámetros. Para configuraciones avanzadas, cambia a la pestaña Avanzado y edita el JSON Schema directamente.

Cuando el valor esté vacío

Para cada parámetro defines qué envía Nuvia al webhook cuando el agente no logra completar ese campo en la conversación:

• No enviar el campo (predeterminado) — la clave se omite del cuerpo de la solicitud (mismo comportamiento que antes)

• Enviar vacío (“”) — envía el campo con texto vacío

• Enviar null — envía el campo con el valor null

Esta opción está disponible para campos de primer nivel. Úsala cuando la API del otro lado espera recibir la clave siempre presente (aunque sin valor) en lugar de simplemente ausente.

Pestaña Respuesta

Configura cómo el agente interpretará la respuesta de la API mediante el Response Mapping (opcional). Cuando está habilitado, permite mapear campos específicos de la respuesta de la API para usarlos en la conversación.

Pestaña Probar Solicitud

Usa la pestaña Probar Solicitud para disparar la llamada HTTP de forma aislada y ver la respuesta sin tener que ejecutar una conversación completa con el agente. Sirve para validar el endpoint, la autenticación y el payload antes de poner la habilidad en producción. La pestaña aparece tanto en la creación como en la edición de habilidades HTTP.

Cómo probar:

1. Abre la pestaña Probar Solicitud

2. En el campo Parámetros (JSON), ajusta los valores de prueba. El campo ya viene completado con los parámetros declarados en la pestaña Parámetros — el valor de cada uno muestra la descripción del parámetro como ejemplo, para que la reemplaces por un valor real

3. Haz clic en Probar Solicitud

Qué muestra el resultado:

• Estado de la respuesta (verde para éxito, rojo para error) y Tiempo de respuesta en milisegundos

• URL llamada, Headers enviados y Body enviado — exactamente lo que se disparó. Por seguridad, el token de autenticación se oculta en la respuesta

• Response Body (crudo): lo que devolvió la API

• Response Body (mapeado): el resultado después del Response Mapping configurado en la pestaña Respuesta

• Historial de las últimas pruebas: guarda las últimas ejecuciones (hasta 10) para que compares resultados; haz clic en cualquiera para revisarla

Avisos que ayudan a configurar:

• Si escribes un campo que no está declarado en la pestaña Parámetros, Nuvia avisa que se ignorará en la prueba — el mismo filtro que aplica el agente real (solo envía lo que está en el schema)

• Si no hay ningún parámetro declarado en la pestaña Parámetros, la prueba envía el body vacío y muestra un aviso pidiéndote que declares los parámetros allí

Casos de uso

• Consultar el stock de un producto

• Verificar el estado de un pedido

• Agendar una visita técnica

• Calcular el envío

• Registrar un lead en un CRM externo

Preguntas frecuentes