Ir al contenido principal
Agentes

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

  • 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.

  • Tipos: string, number, integer y boolean en la vista Formulario. En la vista JSON también puedes usar object, array y 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 como string, la llamada se rechaza y la herramienta no se ejecuta.

  • 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.

  • 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

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.

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.

  • 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.

  • 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.

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.