Tu primera integración con AGOS

AGOS expone una API REST para integrar agentes, conocimiento y conversaciones en un ERP, un portal o una aplicación. Esta documentación usa el contrato OpenAPI de AGOS 1.7.4. Comprueba siempre la versión de tu instalación antes de integrar.

Elegir el tipo de integración

Necesidad	Interfaz	Autenticación
Tu backend consulta el chat o administra recursos	/api/chat y /api/admin/*	JWT Bearer de un usuario dedicado
Incorporas un asistente en una web	/widget/{publicationId}	Licencia de uso por usuario final
Construyes una experiencia de chat propia	/api/public/widgets/{publicationId}/*	licenseId en las operaciones de usuario

No confundas la licencia de uso del widget con la licencia que habilita toda la instalación.

Requisitos

1. Una instalación de AGOS accesible por HTTPS y su URL base, por ejemplo https://agos.example.com.
2. Un usuario de integración creado por el administrador. No uses su cuenta personal de administrador.
3. Una licencia de instalación vigente y cuota suficiente para el usuario.
4. Un agente activo con conocimiento preparado. Para los ejemplos, configura AGOS_AGENT_KEY con su clave real.

Los dominios, identificadores y mensajes de esta guía son ejemplos. No contienen accesos operativos.

Preparar el entorno

Configura estas variables mediante tu entorno de ejecución o un almacén de secretos. No las incluyas en el repositorio ni en el JavaScript que recibe el navegador.

Variable	Contenido
AGOS_BASE_URL	Origen HTTPS de AGOS, sin /api al final
AGOS_EMAIL	Correo del usuario de integración
AGOS_PASSWORD	Contraseña de ese usuario
AGOS_AGENT_KEY	Clave de un agente activo, por ejemplo soporte-app

Realizar la primera llamada

1. Envía POST /api/auth/login con email, password y useCookie: false.
2. Conserva el token devuelto en el backend.
3. Envía POST /api/chat con Authorization: Bearer <token> y el mensaje.
4. Comprueba el código HTTP antes de leer la respuesta.

{
  "message": "¿Cómo registro una devolución?",
  "agentKey": "soporte-app",
  "history": []
}

Una respuesta satisfactoria incluye text, personality, tokensUsed, elapsedMs, messageId y sources. El texto viene en Markdown: usa un renderizador con sanitización si lo muestras como HTML.

Ejecutar un ejemplo completo

Abre Ejemplos por lenguaje para realizar el mismo flujo en cURL, JavaScript, Python o C#. Los ejemplos se ejecutan en tu equipo o backend; este sitio de documentación no solicita credenciales ni envía peticiones a AGOS.

Comprobar el resultado

Un 200 confirma la respuesta del chat. Comprueba que personality sea el agente esperado y revisa sus fuentes. Si no puedes autenticarte, continúa con Autenticación y permisos. Para otros estados, consulta Errores y límites.