Conecta un agente de IA gestionado a tu aplicación
Usa una clave REST limitada a un agente desde un servidor de confianza para llamar al mismo agente IMFA publicado que gestiona conocimiento, comportamiento, modelos, herramientas, sesiones y canales. Envía mensajes, continúa conversaciones API, consulta el historial y recupera leads sin reconstruir el ciclo de vida del agente.
¿Qué es una API de agente con IA?
Una API de agente con IA permite que una aplicación de confianza se comunique con un agente que ya tiene instrucciones, conocimiento, modelo, herramientas y comportamiento conversacional. La API REST de IMFA permite listar el agente disponible, enviar mensajes, continuar una sesión API, leer mensajes persistidos y recuperar leads.
Es una interfaz para un agente gestionado, no un endpoint directo de modelo. Configuras y publicas el agente en IMFA y tu servidor lo llama con una clave limitada a ese agente. El mismo RAG y comportamiento aprobado puede servir a tu app, web, WhatsApp, Telegram, Discord y voz elegible.
Un contrato de producción para integraciones de servidor
La API ofrece una superficie REST limitada y documentada alrededor del agente publicado, mientras IMFA gestiona conocimiento, comportamiento, modelos, sesiones, créditos y protecciones.
Autenticación limitada al agente
Genera manualmente una clave REST en la vista API del agente o en la pantalla de claves. Envía Authorization: Bearer YOUR_API_KEY. La clave se muestra una vez, se guarda solo como hash y es diferente del token MCP de la cuenta.
Solicitudes de chat idempotentes
POST /v1/agents/{slug}/chat exige un Idempotency-Key de 8 a 128 caracteres permitidos. Usa una clave nueva para cada turno distinto y reutilízala solo al reintentar exactamente la misma solicitud.
Contexto API reutilizable
Omite sessionId para iniciar una conversación API, guarda el valor devuelto con la respuesta y reutilízalo después. Los ID de sesiones web, builder y canales visibles en el historial son de solo lectura.
Sesiones, mensajes y leads
Lista sesiones persistidas, lee los mensajes de una sesión y recupera leads. Las rutas GET paginadas devuelven 20 elementos por defecto y aceptan un límite entre 1 y 100 más un cursor opcional.
Límites y estados explícitos
El chat requiere message, usa sus primeros 4.000 caracteres, admite un sessionId de hasta 128 caracteres y limita el cuerpo a 64.000 bytes. Los estados distinguen validación, clave, créditos, disponibilidad, pausa, tamaño, tasa y servidor.
El mismo sistema de agente gestionado
Las respuestas usan instrucciones, modelo, conocimiento RAG, habilidades, herramientas y protecciones del agente publicado. Las solicitudes consumen créditos del propietario y una respuesta correcta puede incluir usage.credits.
Cómo llamar a un agente IMFA desde tu servidor
Publica primero el agente, protege su credencial en una variable de servidor y diseña los reintentos para conservar idempotencia y continuidad.
-
Crea y publica el agente gestionado
Define instrucciones, RAG, modelo, habilidades, herramientas y protecciones en IMFA. Prueba preguntas realistas y publica de forma explícita antes de usar el endpoint REST.
-
Genera y protege la clave limitada
Abre la vista API o https://www.imfa.app/app/api-keys, genera la clave manualmente y guárdala en una variable de servidor como IMFA_API_KEY. Nunca la pongas en el navegador, una app móvil, un repositorio público, logs o mensajes.
-
Envía una solicitud idempotente
Llama fetch('https://site.imfa.app/v1/agents/{slug}/chat') con POST, Authorization: Bearer más la clave del servidor, Content-Type: application/json, un Idempotency-Key único y JSON con message y sessionId opcional. Guarda reply, sessionId y usage.credits.
API de IMFA frente a una API de modelo o desarrollo propio
La elección depende de la capa que tu equipo quiera controlar. IMFA expone un agente de atención ya gestionado, mientras una API de modelo ofrece primitivas de generación.
Una API de modelo ofrece control máximo
Elige un proveedor directo si quieres gestionar prompts, ingestión y búsqueda RAG, sesiones, políticas de herramientas, autenticación, límites, canales, observabilidad, facturación, despliegue, seguridad y mantenimiento.
Los agentes de código crean software
Codex y Claude Code pueden crear aplicaciones e integraciones. También pueden gestionar IMFA mediante MCP, mientras el servidor de producción usa una clave REST distinta y limitada al agente.
IMFA gestiona el ciclo del agente
Elige IMFA cuando tu aplicación deba llamar a un agente cuyo conocimiento, reglas, canales, sesiones, leads, modelos, protecciones, publicación y uso se gestionan desde una interfaz.
Cinco endpoints REST para un agente publicado
La URL base es https://site.imfa.app/v1. Cada solicitud necesita la clave Bearer limitada al agente y el chat debe proceder de infraestructura de servidor de confianza.
Listar el agente disponible
GET /v1/agents devuelve el agente disponible para la clave y permite confirmar el destino publicado.
Chatear con el agente
POST /v1/agents/{slug}/chat envía un mensaje y devuelve reply, un sessionId reutilizable, usage.credits y el estado de replay cuando corresponda.
Leer conversaciones
GET /v1/agents/{slug}/sessions lista conversaciones y GET /v1/agents/{slug}/sessions/{sessionId}/messages lee los mensajes de una sesión.
Recuperar leads
GET /v1/agents/{slug}/leads devuelve los leads capturados con el mismo contrato de paginación mediante cursor.
Preguntas frecuentes sobre la API de agente con IA
Respuestas exactas sobre autenticación, uso servidor, idempotencia, sesiones, RAG, créditos y límites de tasa.
¿Puedo llamar a la API directamente desde el navegador?
No. La clave consume créditos del propietario y debe permanecer en un servidor de confianza. La API no está pensada para el navegador ni ofrece CORS público amplio. El navegador debe llamar a tu propio endpoint de servidor protegido.
¿Cómo autentico una solicitud a la API de IMFA?
Genera manualmente una clave REST limitada al agente en su vista API o en la pantalla de claves y envía Authorization: Bearer YOUR_API_KEY desde el servidor. El token MCP es una credencial distinta y no sustituye la clave REST.
¿Cómo continúo la misma conversación API?
Omite sessionId en la primera solicitud, guarda el valor devuelto y añádelo al siguiente cuerpo. Solo un ID devuelto por el chat API continúa ese contexto; las sesiones web y de canales son de solo lectura.
¿Por qué es obligatorio Idempotency-Key?
Permite repetir exactamente una solicitud sin convertir un reintento de red en un nuevo turno. Usa una clave nueva de 8 a 128 caracteres para cada mensaje distinto y reutilízala solo para esa misma solicitud.
¿La API usa mi RAG y mis herramientas?
Sí. Llama al agente publicado con sus instrucciones, modelo, conocimiento RAG, habilidades, herramientas y protecciones. El resultado depende de la configuración publicada, los créditos y los límites actuales del servicio.
¿Qué ocurre con límites de tasa o créditos agotados?
La API puede devolver 402 si no quedan créditos o 429 al limitar la tasa. Para 429 espera el tiempo Retry-After. Gestiona todos los estados y recuerda que un fallo interno de generación aún puede devolver sessionId.