1. [Ayuda](https://nuvia.ai/es/docs) 2. [Pipeline y Embudos Inteligentes (Agentes de IA)](https://nuvia.ai/es/docs/colecoes/19377999-pipeline-y-embudos-inteligentes-agentes-de-ia) 3. [Embudos Inteligentes](https://nuvia.ai/es/docs/colecoes/19431085-embudos-inteligentes) # Cómo crear habilidades personalizadas para el agente de IA Cómo crear y configurar herramientas HTTP (Custom HTTP) que permiten al agente de IA llamar APIs externas durante las conversaciones. Disponible en todos los planes Quién puede hacerlo administradores Actualizado el 9 de septiembre de 2026 [Embudos Inteligentes](https://nuvia.ai/es/docs/colecoes/19431085-embudos-inteligentes) 1. [Cómo crear habilidades personalizadas para el agente de IA](https://nuvia.ai/es/docs/artigos/14590394-como-crear-habilidades-personalizadas-para-agente-de-ia) 2. [Cómo escribir el objetivo, el conocimiento y los pilares de comunicación del agente](https://nuvia.ai/es/docs/artigos/16515436-escribir-objetivo-conocimiento-pilares-comunicacion-agente) 3. [Cómo escribir las instrucciones de una etapa](https://nuvia.ai/es/docs/artigos/16515466-como-escribir-instrucciones-de-una-etapa) 4. [Etapas estándar de un embudo de ventas: cómo diseñar el flujo del agente](https://nuvia.ai/es/docs/artigos/16515486-etapas-estandar-embudo-de-ventas-flujo-del-agente) 5. [Cómo archivar un Embudo Inteligente transfiriendo las conversaciones](https://nuvia.ai/es/docs/artigos/16624949-como-archivar-embudo-inteligente-transfiriendo-conversaciones) 6. [Cómo funciona la reapertura de conversación reciente en el Embudo Inteligente](https://nuvia.ai/es/docs/artigos/16644378-como-funciona-reapertura-conversacion-reciente-embudo-inteligente) 7. [Cómo alimentar el Centro de Conocimiento](https://nuvia.ai/es/docs/artigos/14579639-como-alimentar-el-centro-de-conocimiento) 8. [Cómo configurar y usar los Seguimientos Inteligentes en Nuvia](https://nuvia.ai/es/docs/artigos/14580483-como-configurar-usar-seguimientos-inteligentes-nuvia) En esta página 1. Qué son las habilidades 2. Crear una habilidad 3. Pestaña Configuración HTTP 4. Pestaña Auth & Retry 5. Pestaña Parámetros 6. Pestaña Respuesta 7. Pestaña Probar Solicitud 8. Casos de uso 9. Preguntas frecuentes **En esta página9 secciones** 1. Qué son las habilidades 2. Crear una habilidad 3. Pestaña Configuración HTTP 4. Pestaña Auth & Retry 5. Pestaña Parámetros 6. Pestaña Respuesta 7. Pestaña Probar Solicitud 8. Casos de uso 9. Preguntas frecuentes 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. Campo Para qué sirve **API key** Identificador público, enviado junto con la firma. Obligatorio **Secret** El secreto que se usa para firmar. Obligatorio. El campo aparece enmascarado en pantalla, como un campo de contraseña **Plantilla de la cadena firmada** Define exactamente qué texto se firma. Obligatorio — cada API la arma a su manera **Prefijo eliminado del path firmado** Opcional. Lo usa {path_relative}. La barra final decide si queda una barra: /api/ genera customers, /api genera /customers. En blanco = path completo **Formato del timestamp** ISO 8601 microsegundos (Laravel/Carbon) · ISO 8601 milisegundos · Unix (segundos) · Unix (milisegundos). Predeterminado: ISO 8601 microsegundos **Algoritmo** HMAC-SHA256 (predeterminado) o HMAC-SHA512 **Codificación de la firma** Hexadecimal (predeterminado) o Base64 **Prefijo de la firma** Opcional. Texto que se coloca antes de la firma, ej.: sha256= **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. ⚠️ Un marcador mal escrito no pasa. Si escribes algo como {pathwithquery}, Nuvia rechaza el guardado y te dice qué marcador es inválido, junto con la lista de los aceptados. Esto es a propósito: un marcador incorrecto que pasara se convertiría en un error 401 sin explicación en medio de una conversación real. Dónde se envía la firma. Por defecto, Nuvia envía tres headers separados, cuyos nombres puedes cambiar: Header Nombre predeterminado API key X-API-Key Timestamp X-Timestamp Firma X-Signature **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. 💡 ¿Te da 401 aunque todo parece correcto? El sospechoso número uno es el formato del timestamp; tiene que coincidir exactamente con lo que espera la API del otro lado. Revisa también que el Prefijo eliminado del path firmado corresponda a lo que describe la documentación de la API. Usa la pestaña Probar Solicitud para validar antes de poner la habilidad en producción. **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** 💡 Bueno saber: al probar, los cambios de la habilidad se guardan automáticamente (creándola o actualizándola) y la solicitud se ejecuta en el backend, simulando el escenario real. No necesitas guardar manualmente antes. **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 ## Preguntas frecuentes **¿Necesito ejecutar una conversación para probar la habilidad?** No. La pestaña **Probar Solicitud** dispara la llamada de forma aislada y muestra la respuesta al instante, sin iniciar una conversación con el agente. **¿La prueba usa la versión que está en pantalla o la guardada?** Al hacer clic en probar, Nuvia guarda la habilidad automáticamente (creándola o actualizándola) y ejecuta la solicitud contra esa versión guardada, así que la prueba siempre refleja lo que acabas de configurar. **¿El token de autenticación aparece en el resultado de la prueba?** No. Los headers de autenticación se ocultan en la respuesta de la prueba. **¿Puedo ver el Secret del HMAC después de guardar?** El campo aparece enmascarado en pantalla, como un campo de contraseña. El ocultamiento en el resultado de **Probar Solicitud** se aplica a los headers de autenticación de esa prueba; no impide que alguien con acceso a la pantalla de habilidades recupere el secreto configurado. Trata el Secret como una credencial de la empresa y limita quién tiene acceso al área de Habilidades. **¿La prueba repite la llamada en caso de falla, como el Retry?** No. La prueba ejecuta una sola llamada (sin retry), para que veas exactamente qué pasa en un intento. El Retry sigue aplicándose en la ejecución real del agente. **¿El agente decide solo cuándo usar la habilidad?** Sí, según la descripción y el contexto de la conversación. **¿Qué pasa si el agente no completa un parámetro?** Depende de la opción **Cuando el valor esté vacío** de ese parámetro: por defecto Nuvia **omite** la clave; puedes elegir enviar vacío (“”) o **null**, según lo que espere la API externa. La configuración se aplica a los campos de primer nivel. **¿Qué pasa si la API devuelve un error?** El agente adapta la respuesta e informa al contacto. En la prueba, el error aparece con el estado y el mensaje devueltos por la API (o “Error de red” cuando la llamada ni siquiera llega a completarse). [SiguienteCómo escribir el objetivo, el conocimiento y los pilares de comunicación del agente](https://nuvia.ai/es/docs/artigos/16515436-escribir-objetivo-conocimiento-pilares-comunicacion-agente) ¿Te ayudó este artículo? ## Artículos relacionados - [Cómo gestionar API keys en Nuvia](https://nuvia.ai/es/docs/artigos/15230128-como-gestionar-api-keys-en-nuvia) - [Cómo crear y editar Embudos Inteligentes por el MCP (Agent Builder)](https://nuvia.ai/es/docs/artigos/16074655-crear-editar-embudos-inteligentes-mcp-agent-builder) [Embudos Inteligentes](https://nuvia.ai/es/docs/colecoes/19431085-embudos-inteligentes) 1. [Cómo crear habilidades personalizadas para el agente de IA](https://nuvia.ai/es/docs/artigos/14590394-como-crear-habilidades-personalizadas-para-agente-de-ia) 2. [Cómo escribir el objetivo, el conocimiento y los pilares de comunicación del agente](https://nuvia.ai/es/docs/artigos/16515436-escribir-objetivo-conocimiento-pilares-comunicacion-agente) 3. [Cómo escribir las instrucciones de una etapa](https://nuvia.ai/es/docs/artigos/16515466-como-escribir-instrucciones-de-una-etapa) 4. [Etapas estándar de un embudo de ventas: cómo diseñar el flujo del agente](https://nuvia.ai/es/docs/artigos/16515486-etapas-estandar-embudo-de-ventas-flujo-del-agente) 5. [Cómo archivar un Embudo Inteligente transfiriendo las conversaciones](https://nuvia.ai/es/docs/artigos/16624949-como-archivar-embudo-inteligente-transfiriendo-conversaciones) 6. [Cómo funciona la reapertura de conversación reciente en el Embudo Inteligente](https://nuvia.ai/es/docs/artigos/16644378-como-funciona-reapertura-conversacion-reciente-embudo-inteligente) 7. [Cómo alimentar el Centro de Conocimiento](https://nuvia.ai/es/docs/artigos/14579639-como-alimentar-el-centro-de-conocimiento) 8. [Cómo configurar y usar los Seguimientos Inteligentes en Nuvia](https://nuvia.ai/es/docs/artigos/14580483-como-configurar-usar-seguimientos-inteligentes-nuvia) ## ¿Todavía necesitas ayuda? Los clientes hablan con soporte por el chat dentro de la plataforma. ¿Aún no eres cliente? Habla con nuestro equipo. [Hablar con soporte en la plataforma](https://app.nuvia.ai) [Aún no soy cliente](https://nuvia.ai/es/contact) --- Source: https://nuvia.ai/es/docs/artigos/14590394-como-crear-habilidades-personalizadas-para-agente-de-ia