Cómo conectar tu agente a otros sistemas con una herramienta HTTP
Crea, prueba y soluciona problemas de una herramienta HTTP para que tu agente de IA consulte o envíe datos a tus sistemas durante una conversación, vía API. Incluye la referencia técnica y respuestas a problemas comunes.
Última actualización Hace alrededor de 1 mes
Una herramienta HTTP permite que tu agente se comunique con otros sistemas (propios o externos) durante una conversación: revisar la disponibilidad en tu agenda, buscar un cliente en tu CRM o enviar un pedido a un webhook de n8n, Make, Zapier o GoHighLevel. Configuras el endpoint una vez y el agente decide cuándo llamarlo y qué datos enviar.
Esta guía tiene tres partes: cómo crear la herramienta, una referencia técnica y respuestas a los problemas más comunes.
Antes de empezar: Ten a mano la URL del endpoint y, si lo pide, su token o API key. Estas herramientas solo pueden ser creadas o editadas por usuarios con rol Owner o Admin en agencias o subcuentas; usuarios con rol User solo pueden verlas.
Paso 1: Abre las herramientas personalizadas de tu agente
En el menú izquierdo, abre Agentes y selecciona tu agente. Abre Integraciones, luego Herramientas personalizadas y Herramientas HTTP. Haz clic en Crear y asignar herramienta HTTP: la herramienta se crea y queda asignada a este agente.

Paso 2: Describe la herramienta
En Nueva herramienta HTTP, completa:
Nombre de la herramienta: un nombre corto en snake_case, por ejemplo
check_availability. Debe ser único, no puede repetir el nombre de otra herramienta que use el agente.Descripción: qué hace la herramienta.
URL del endpoint y el método: GET, POST, PUT, PATCH o DELETE. Si una parte de la URL es dinámica, escríbela entre llaves, por ejemplo
/clients/{id}.Instrucciones del prompt: cuándo y cómo el agente debe llamar a la herramienta, y qué datos debe capturar antes.

Importante: El agente lee las Instrucciones del prompt para decidir cuándo llamar a la herramienta. Sé específico sobre las circunstancias donde lo amerita y los datos que debe pedir, o la herramienta puede ejecutarse en el momento equivocado o no ejecutarse.
Paso 3: Declara los parámetros
En Parámetros, declara cada dato que envía el agente. Usa Parámetros del body para los datos que van en el cuerpo de la petición (POST, PUT, PATCH) y Parámetros de consulta para los que se agregan a la URL.
Añade parámetros haciendo clic en Agregar y completa el nombre, el tipo, si es Obligatorio y una descripción.

Para pegar un schema completo, cambia de Formulario a JSON, y agrégalo en el bloque habilitado. Por ejemplo:
{
"type": "object",
"required": ["pago"],
"properties": {
"pago": {
"type": "object",
"description": "Datos del comprobante de pago",
"required": ["monto", "fecha"],
"properties": {
"monto": { "type": "number", "description": "Monto pagado" },
"fecha": { "type": "string", "description": "Fecha del pago (AAAA-MM-DD)" },
"referencia": { "type": "string", "description": "Número de referencia" }
}
}
}
}Importante: La herramienta solo envía los campos que declaras. Si el agente conoce un dato pero no está declarado aquí, nunca llega a tu sistema.
Si el sistema pide autenticación, abre Opciones avanzadas y elige el tipo de Autenticación: Bearer Token, Autenticación básica o API Key. Agrega los headers extra en Headers personalizados.
Paso 4: Prueba el endpoint
Abre Probar endpoint, completa los valores de ejemplo y haz clic en Ejecutar prueba. Esto envía una petición real con el contenido del formulario, igual que la armaría el agente, y muestra el estado, el tiempo y la respuesta.

Importante: La prueba es una petición real. Si la herramienta crea o cambia algo, como una reserva o un pedido, la prueba también lo hace. Usa datos de prueba distinguibles.
Paso 5: Crea la herramienta y pruébala
Haz clic en Crear herramienta. La herramienta aparece en la lista como Activa. Luego abre Probar agente y pregunta algo que deba activarla: el chat muestra cada llamada y su resultado, en verde si funcionó y en rojo si falló.
Qué herramientas usa cada agente
Un agente usa las herramientas HTTP creadas y asignadas en él con Crear y asignar herramienta HTTP, más las herramientas de los toolkits que tiene asignados. Revisa Cómo agrupar herramientas en un toolkit.
El interruptor de cada herramienta la activa o desactiva para todos los agentes que la usan.
Encuentras todas tus Herramientas HTTP en el panel de navegación izquierdo, sub menú de Agentes, en Herramientas personalizadas. Desde ahí puedes agregar una con Agregar herramienta HTTP, editarla, activarla o desactivarla, o eliminarla con el ícono de papelera.
Referencia técnica
Cómo se arma la petición
Cómo se arma la petición
Parámetros de ruta: cada
{nombre}de la URL se reemplaza por el valor que envía el agente, codificado para URL.Parámetros de consulta: se agregan a la URL como
?key=value.Parámetros del body: se envían como JSON, solo con los campos declarados.
Headers: tus headers personalizados más la autenticación que elegiste.
Cómo declarar los parámetros
Cómo declarar los parámetros
Tipos:
string,number,integerybooleanen la vista Formulario. En la vista JSON también puedes usarobject,arrayy una lista de valores permitidos (enum).Descripción: todos los campos la necesitan, también los que están dentro de otros objetos. Es lo que lee el agente para saber qué valor poner, así que escríbela como una instrucción: "Fecha de la cita en formato AAAA-MM-DD".
Obligatorio: los campos obligatorios siempre se envían. El agente puede omitir los demás si no tiene el dato.
Usa el tipo correcto: si un campo es un número, decláralo como
number. Si el agente envía un número a un campo declarado comostring, la llamada se rechaza y la herramienta no se ejecuta.
Límites
Límites
Tiempo de respuesta: el agente espera hasta 30 segundos. Si tu sistema no responde a tiempo, el agente recibe el aviso de que el servicio no respondió y sigue la conversación.
Tamaño de la respuesta: el agente lee hasta 50 KB de la respuesta. Devuelve solo los datos que necesita.
Errores: si tu sistema responde con un error (4xx o 5xx), el agente recibe el código y una fracción del mensaje de error, y sigue la conversación.
Probar endpoint: muestra hasta 10 KB de la respuesta.
Seguridad
Seguridad
La URL debe ser accesible desde internet. Las direcciones privadas o internas (localhost, 127.x, 10.x, 172.16–31.x, 192.168.x, 169.254.x) están bloqueadas, también cuando una URL pública redirige a ellas.
Los tokens, contraseñas y API keys se guardan encriptados y no se vuelven a mostrar después de guardar. Al editar una herramienta, esos campos se ven vacíos: déjalos vacíos para conservar el valor guardado o escribe uno nuevo para reemplazarlo.
Problemas comunes
A mi sistema solo llega una parte de los datos
A mi sistema solo llega una parte de los datos
La herramienta solo envía los campos declarados en sus parámetros. Agrega los campos que faltan, con su tipo y descripción, en Parámetros del body o Parámetros de consulta. Para datos anidados, usa la vista JSON.
No puedo guardar la herramienta
No puedo guardar la herramienta
Revisa que todos los campos, también los que están dentro de otros objetos, tengan nombre, tipo y descripción, y que el JSON sea válido. Un JSON mal formado no se puede guardar.
El agente no llama a la herramienta
El agente no llama a la herramienta
Revisa que la herramienta esté Activa y asignada al agente, directamente o por un toolkit.
Haz más específicas las Instrucciones del prompt: cuándo llamarla y qué datos necesita antes.
Revisa los tipos: si un valor no coincide con su tipo declarado, la llamada se rechaza. Mira la llamada en Probar agente para ver el error.
La prueba falla o la URL está bloqueada
La prueba falla o la URL está bloqueada
Revisa que la URL no tenga errores ni espacios de más, sobre todo al inicio.
Usa una URL pública. Las direcciones locales o internas están bloqueadas.
Revisa el tipo de autenticación y las credenciales.
Si se agota el tiempo, revisa que tu sistema responda en menos de 30 segundos.
La herramienta se ejecuta, pero el agente responde mal
La herramienta se ejecuta, pero el agente responde mal
Ejecuta la prueba y lee la respuesta. Si es muy larga o trae datos que el agente no necesita, devuelve una respuesta más corta desde tu sistema y dile al agente en las Instrucciones del prompt qué campos usar.
Listo
Tu agente ya puede usar la herramienta en sus conversaciones. Vuelve a probarla después de cada cambio en la herramienta o en el prompt.
¿Necesitas ayuda? Contacta a soporte desde la vista de inicio de tu plataforma. Incluye el nombre de la herramienta y lo que ves en Probar endpoint o en Probar agente.
¿Fue útil esto?
¿Aún necesitas ayuda? Pregunta al equipo