Por qué conectar tu agente de IA a tu app con una API

Qué es una API de agentes de IA

Una API de agentes de IA permite que tu propio software envíe un mensaje a un agente que ya creaste y reciba su respuesta. El agente conserva sus instrucciones, su conocimiento, su modelo, sus herramientas y sus reglas de seguridad. Tu app solo envía la pregunta.

Esa es la diferencia con la API de un modelo sin más. Una API de modelo te da generación de texto y te deja todo lo demás: prompts, búsqueda en documentos, memoria, límites de uso, facturación. La API REST de IMFA te da un agente gestionado que ya tiene todo eso, detrás de una clave limitada a ese agente.

Creas el agente con el creador de chatbots con IA. La API es un lugar más donde puede responder, junto a tu web, WhatsApp, Instagram, Facebook, Telegram, Discord y la línea de voz.

Cuándo conviene conectar tu agente mediante una API

Recurre a la API cuando la conversación ocurre dentro de algo que es tuyo:

• Tu app o tu portal de clientes necesita un asistente de ayuda que conozca tus políticas, sin un segundo chatbot que mantener.
• Tu backend debe responder preguntas desde otro sistema, como páginas de pedidos, una herramienta de reservas o un panel interno.
• Quieres tus leads en tu CRM. La API devuelve los leads que el agente captó en todos los canales, así puedes sincronizarlos de forma programada.
• Necesitas el historial de conversaciones para informes o revisiones de calidad.

Si solo necesitas una burbuja de chat en una web, la inserción de una línea es más sencilla. La API es para cuando la interfaz es tu producto, no el widget.

Cómo funciona la API de agentes de IMFA

La URL base es https://site.imfa.app/v1. Cada llamada necesita la clave del agente y debe salir de código de servidor de confianza, nunca de un navegador ni de una app móvil.

1. Publica el agente. Define sus instrucciones, su conocimiento, su modelo y sus herramientas en IMFA, prueba preguntas reales y publica. La API sirve la versión publicada.
2. Genera la clave. Abre la vista API del agente o la pantalla de claves de API y genera una clave. Se muestra una sola vez y solo se guarda como hash. Guárdala en una variable de entorno del servidor, como IMFA_API_KEY.
3. Envía una petición de chat. POST /v1/agents/{slug}/chat con Authorization: Bearer <key>, una Idempotency-Key única (de 8 a 128 caracteres) y un cuerpo JSON con message y un sessionId opcional. La respuesta llega con un sessionId y usage.credits.
4. Continúa la conversación. Omite sessionId en el primer turno y después envía el que recibiste. El agente recuerda el contexto.
5. Consulta lo que ha pasado. GET /v1/agents/{slug}/sessions lista las conversaciones, GET /v1/agents/{slug}/sessions/{sessionId}/messages lee una y GET /v1/agents/{slug}/leads devuelve los leads captados. Las listas devuelven 20 elementos por defecto, hasta 100, con un cursor. GET /v1/agents confirma a qué agente sirve la clave.

Los límites son explícitos: se usan los primeros 4.000 caracteres de un mensaje, los cuerpos tienen un máximo de 64.000 bytes y los errores tienen tipo (validación, autenticación, créditos, límite de uso, servidor). Un 429 llega con Retry-After; un 402 significa que el propietario se ha quedado sin créditos.

Por qué usar la API de agentes en lugar de construir la tuya

Te ahorras meses de infraestructura. La búsqueda en documentos, las sesiones, los límites de uso, los reintentos, la contabilidad de créditos y las reglas contra la inyección de prompts ya están funcionando. Tu equipo escribe una llamada HTTP.

Un agente, un comportamiento. La respuesta que muestra tu app es la misma que dan tu web y WhatsApp, porque es el mismo agente. Actualízalo una vez en IMFA y todo lo demás le sigue.

Los reintentos son seguros. Con la clave de idempotencia, un reintento de red devuelve la respuesta original en lugar de cobrar un segundo turno.

Los leads dejan de vivir aislados. Recupera todos los leads captados desde un solo endpoint, vengan del canal que vengan.

Puedes seguir yendo a lo totalmente personalizado. Si necesitas controlar cada capa, la API de un modelo te da ese control, a cambio de construirlo y mantenerlo tú. Los agentes de programación como Codex y Claude Code también pueden gestionar agentes de IMFA mediante MCP, mientras tu servidor usa la clave REST para atender a tus clientes.

Preguntas frecuentes sobre la API de agentes de IA

¿Puedo llamar a la API de agentes de IA directamente desde un navegador?

No. La clave gasta los créditos del propietario y debe quedarse en un servidor de confianza. La API no abre acceso general desde navegadores. Haz que tu navegador llame a tu propio endpoint protegido y que este llame a IMFA.

¿Cómo autentico una petición a la API de agentes de IMFA?

Genera una clave limitada al agente en su vista API o en la pantalla de claves de API y envía Authorization: Bearer YOUR_API_KEY desde código de servidor. Un token de MCP es una credencial distinta y no sirve aquí.

¿Cómo continúo la misma conversación de la API?

Omite sessionId en la primera petición de chat, guarda el sessionId que devuelve la API y envíalo con el siguiente mensaje. Los identificadores de sesión de conversaciones de la web o de los canales son de solo lectura y no pueden continuar una conversación de la API.

¿Por qué el chat exige una Idempotency-Key?

Hace que los reintentos sean seguros. Un reintento exacto con la misma clave devuelve el mismo resultado en lugar de crear un turno nuevo. Usa una clave nueva para cada mensaje nuevo.

¿Qué pasa cuando la API llega al límite de uso o se queda sin créditos?

Recibes un 429 con la cabecera Retry-After cuando se alcanza el límite de uso, y un 402 cuando el propietario se queda sin créditos. Gestiona en tu integración todos los códigos de estado documentados.