Saltar al contenido principal

​
¿Qué son las Integraciones HTTP?

Las integraciones HTTP te permiten conectar tus agentes con cualquier API REST que uses o controles. Es la forma más flexible de integrar sistemas externos, desde CRMs hasta plataformas de pagos, bases de datos o servicios internos. A diferencia de las integraciones MCP que sincronizan herramientas automáticamente, con HTTP tú defines manualmente cada herramienta: qué endpoint llamar, qué parámetros enviar y cómo autenticarse.

​
Crear una Integración HTTP

1

Accede a Integraciones

Desde el dashboard, ve a la sección Integraciones y haz clic en Nueva Integración.Selecciona el tipo HTTP.
2

Configura la Conexión

Define los detalles básicos de tu integración:Nombre: Identifica tu integración (ej. “Zendesk”, “Apidetuempresa” )URL Base: El dominio y ruta base de la API (ej. https://api.tuempresa.com/v1)Descripción: (Opcional) Explica para qué sirve esta integración Credenciales: Dependiendo del servidor, puede requerir:
  • Bearer Token
  • Headers personalizados
  • Sin autenticación
3

Guarda la Integración

Una vez confirmada la conexión, guarda la integración.Ahora puedes crear herramientas que usen esta integración.

​
Crear Herramientas

Una vez creada la integración, necesitas definir las herramientas (acciones específicas) que tus agentes pueden usar.
1

Accede a la Integración

En la lista de integraciones, selecciona la que acabas de crear.Haz clic en Nueva Herramienta.
2

Define la Herramienta

Configura los detalles de la acción:Nombre: Identificador único en formato snake_case (ej. buscar_cliente, crear_ticket)Descripción: Explica cuándo el agente debe usar esta herramienta. Sé específico.
Buena descripción: “Usa esta herramienta cuando el usuario proporcione su número de pedido y quiera saber el estado de su envío”Mala descripción: “Consulta pedidos”
Método HTTP: GET, POST, PUT, PATCH, DELETEEndpoint: Ruta relativa a la URL base (ej. /customers, /tickets/create)Headers Personalizados: (Opcional) Añade headers específicos para esta herramienta, si es necesario.
3

Define Parámetros

Especifica qué información necesita la herramienta. Los parámetros son opcionales (dependerá de la API) y podemos encontrar dos tipos:Parametros de la query: Se envían en la URL (ej. ?status=open&limit=5)Parametros del body: Se envían en el cuerpo de la solicitud (JSON)Para cada parámetro define los siguientes campos:
  • Nombre: Identificador único (ej. customer_id, status). Debe ser el nombre del valor que espera la API.
  • Descripción: Qué información representa y cómo obtenerla
  • Tipo de Dato: string, number, boolean, array, object
  • Obligatorio: Si es requerido o no
  • Modo de obtención: Cómo el agente consigue este valor:
    • Prompt: El agente pregunta al usuario o lo infiere del contexto
    • Valor fijo: Un valor constante que defines al crear la herramienta
La descripción del parámetro es clave para que el agente entienda qué valor debe proporcionar. Sé claro y específico.

​
Ejemplo Completo: Integración con un CRM

Vamos a crear una integración con un CRM ficticio para buscar clientes.

​
1. Crear la Integración

Pantalla de creación de integración HTTP mostrando campos de nombre, URL base y credenciales

​
2. Crear Herramienta: Buscar Cliente

  • Configuración basica:
Pantalla de creación de herramienta HTTP mostrando campos de nombre, descripción, método y endpoint
  • Endpoint y método:
Configuración del endpoint y método HTTP para la herramienta de buscar cliente
  • Parámetros:
Configuración del body JSON para la herramienta de buscar cliente con parámetro customer_id

​
3. Ejemplo de Uso en Llamada

Usuario: Mi email es juan@ejemplo.com, ¿qué pedidos tengo?

Agente: [Llama a buscar_cliente con email="juan@ejemplo.com"]

API responde:
{
  "customers": [{
    "id": "cust_123",
    "name": "Juan Pérez",
    "email": "juan@ejemplo.com",
    "phone": "+34612345678"
  }]
}

Agente: Hola Juan, veo que tienes una cuenta con nosotros.
        Déjame consultar tus pedidos...

​
Mejores Prácticas

Nombres de herramientas:
  • Usa verbos que describan la acción: buscar_, crear_, actualizar_, eliminar_
  • Formato snake_case: consultar_inventario, no consultarInventario
  • Sé específico: crear_ticket_soporte, no solo crear
Nombres de parámetros:
  • Consistentes con la API: usa los mismos nombres que la documentación
  • Descriptivos: customer_id mejor que id
Las descripciones ayudan al agente a decidir cuándo usar cada herramienta.Buenas descripciones incluyen:
  • Cuándo usar la herramienta (trigger)
  • Qué información necesita del usuario
  • Qué hace exactamente
Ejemplo:
✅ BIEN:
"Usa esta herramienta cuando el usuario mencione su número de
pedido y quiera conocer el estado de su envío. Requiere el
número de pedido completo (ej. ORD-12345)."

❌ MAL:
"Consulta pedidos"
Define qué debe hacer el agente si la herramienta falla:En el prompt del agente, añade instrucciones como:
## Manejo de Errores de Herramientas

Si una herramienta falla:
1. No repitas el error técnico al usuario
2. Explica el problema en lenguaje simple
3. Ofrece una alternativa

Ejemplo:
"Lo siento, no puedo acceder a esa información en este momento.
¿Puedo ayudarte con algo más o prefieres que te transfiera
con un agente humano?"
  • Rota credenciales regularmente: Actualiza API keys cada 3-6 meses
  • Usa credenciales de solo lectura cuando sea posible
  • Separa entornos: Diferentes credenciales para staging y producción
  • Nunca expongas credenciales en prompts, logs o respuestas del agente
Las llamadas lentas pausan la conversación.Reduce latencia:
  • Usa endpoints optimizados (solo pide los datos necesarios)
  • Limita el tamaño de respuestas (usa parámetros como limit, fields)
  • Considera cachear datos que no cambian frecuentemente
  • Monitorea tiempos de respuesta (objetivo: < 2 segundos)
Ejemplo:
✅ BIEN: GET /customers/123?fields=name,email,phone
❌ MAL: GET /customers/123 (devuelve 50 campos innecesarios)

​
Solución de Problemas

Causa: Credenciales incorrectas o expiradas.Solución:
  • Verifica que el tipo de autenticación sea correcto
  • Confirma que la API key o token esté activa
  • Revisa si el token tiene los permisos necesarios
  • Para Bearer tokens, verifica que no haya expirado
Causa: El endpoint no existe.Solución:
  • Verifica la URL base (debe terminar en la versión de la API, ej. /v1)
  • Confirma que el endpoint esté correctamente escrito
  • Revisa la documentación para cambios en la API
Causa: Parámetros faltantes o con formato incorrecto.Solución:
  • Verifica que los parámetros requeridos estén configurados
  • Confirma que los tipos de datos sean correctos (string, number, etc.)
  • Revisa que los parámetros estén en la ubicación correcta (path, query, body)
Causa: Límite de rate limit excedido.Solución:
  • Verifica los límites de la API en su documentación
  • Reduce la frecuencia de llamadas
  • Considera upgradar tu plan con el proveedor de la API
  • Implementa caché para datos que no cambian frecuentemente
Causa: El agente no sabe cuándo usar la herramienta.Solución:
  • Mejora la descripción de la herramienta (sé más específico)
  • En agentes de Prompt Único: añade instrucciones explícitas sobre cuándo usar la herramienta
  • En Caminos Conversacionales: asegúrate de que el nodo correcto esté configurado para usar la herramienta
Causa: Parámetros mal configurados o descripción ambigua.Solución:
  • Revisa que los parámetros tengan descripciones claras
  • Asegúrate de que los tipos de datos sean correctos
  • Mejora las instrucciones en el prompt del agente
  • Usa confirmación de usuario para herramientas críticas

​
Siguientes Pasos

https://mintcdn.com/diga/5WJ7DCPPeyMq2XKq/icons/file-attachment-02.svg?fit=max&auto=format&n=5WJ7DCPPeyMq2XKq&q=85&s=d54516959b34e8bac951d8b0014f75d4

Asignar a Agentes

Aprende a asignar esta integración a tus agentes y filtrar herramientas.
https://mintcdn.com/diga/xKWg5W37UL9-MZ81/icons/mcp-server.svg?fit=max&auto=format&n=xKWg5W37UL9-MZ81&q=85&s=4355c1a44d52543b9407dc083c15f0f7

Integraciones MCP

Descubre cómo sincronizar herramientas automáticamente con MCP.