Referencia de la API REST

Documentación interactiva

Toda aplicación Agent-Lab sirve OpenAPI 3 automáticamente: la implementación de referencia en http://localhost:18000/docs (o tu propia aplicación, dondequiera que se ejecute). El catálogo siguiente documenta los routers integrados del framework; tus extra_routers aparecen en el mismo esquema.

Autenticación

Cuando auth.enabled vale true (consulta la Referencia de configuración), las rutas requieren un token bearer de Keycloak. El router /auth solo se monta cuando la autenticación está habilitada:

TOKEN=$(curl -s -X POST https://<host>/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "…", "password": "…"}' | jq -r '.access_token')

curl -s https://<host>/agents/list -H "Authorization: Bearer $TOKEN" | jq

La configuración del realm y del cliente se explica en Autenticación con Keycloak.

Rutas sin autenticación: /status/*, /docs, /openapi.json, /mcp, /static, los endpoints well-known de OAuth y el montaje de la SPA; todo lo demás requiere un token válido.

Endpoints

Agentes

Crea instancias de cualquier tipo de agente registrado; agent_type se valida dinámicamente contra el registro.

Mensajes

Modelos de lenguaje

Integraciones

Adjuntos

Estado y MCP

Ejemplos de peticiones

Crear una instancia de agente: agent_name admite [a-zA-Z0-9_-]; agent_type debe ser un tipo registrado; language_model_id es opcional:

curl -s -X POST http://localhost:18000/agents/create \
  -H "Content-Type: application/json" \
  -d '{
        "agent_name": "support-agent-1",
        "agent_type": "coordinator_planner_supervisor",
        "language_model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }' | jq

Enviar un mensaje: message_role es uno de human, assistant, tool; attachment_id es opcional:

curl -s -X POST http://localhost:18000/messages/post \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "message_role": "human",
        "message_content": "Summarize the attached report.",
        "attachment_id": null
      }' | jq

Actualizar un ajuste de agente: setting_key admite [a-zA-Z_-]; setting_value admite hasta 16.000 caracteres (aquí residen las plantillas de prompts y las cargas JSON; consulta el Modelo de dominio de entidades):

curl -s -X POST http://localhost:18000/agents/update_setting \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "setting_key": "system_prompt",
        "setting_value": "You are a concise research assistant…"
      }' | jq

Convenciones

• Los ID son UUID; todos los endpoints de listado aceptan cuerpos JSON, no query strings.
• Los ajustes son pares clave-valor que se persisten con el agente o el modelo: así es como la misma implementación ejecuta muchas instancias configuradas de forma distinta.
• El registro es la fuente de verdad de los valores válidos de agent_type: ejecuta GET /agents/types para ver qué ha descubierto la aplicación en ejecución (incluidos tus propios paquetes mediante scan_packages).