Referência da API REST

Documentação interativa

Toda aplicação Agent-Lab serve OpenAPI 3 automaticamente — a implementação de referência em http://localhost:18000/docs (ou a sua própria aplicação, onde quer que ela rode). O catálogo abaixo documenta os routers nativos do framework; seus extra_routers aparecem no mesmo schema.

Autenticação

Quando auth.enabled é true (consulte a Referência de configuração), as rotas exigem um bearer token do Keycloak. O router /auth só é montado quando a autenticação está ativada:

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

A configuração do realm/client é explicada em Autenticação com Keycloak.

Caminhos sem autenticação: /status/*, /docs, /openapi.json, /mcp, /static, os endpoints well-known do OAuth e o mount da SPA — todo o resto exige um token válido.

Endpoints

Agentes

Crie instâncias de qualquer tipo de agente registrado; agent_type é validado dinamicamente contra o registro.

Mensagens

Modelos de linguagem

Integrações

Anexos

Status e MCP

Exemplos de requisição

Criar uma instância de agente — agent_name aceita [a-zA-Z0-9_-]; agent_type deve ser um tipo registrado; language_model_id é 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 uma mensagem — message_role é um de human, assistant, tool; attachment_id é 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

Atualizar uma configuração do agente — setting_key aceita [a-zA-Z_-]; setting_value comporta até 16.000 caracteres (templates de prompt e payloads JSON ficam aqui — consulte o Modelo de domínio 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

Convenções

• IDs são UUIDs; todos os endpoints de listagem aceitam corpos JSON, e não query strings.
• Configurações são pares chave-valor persistidos com o agente ou o modelo — é assim que a mesma implementação executa muitas instâncias configuradas de formas diferentes.
• O registro é a fonte da verdade para os valores válidos de agent_type — execute GET /agents/types para ver o que a aplicação em execução descobriu (incluindo seus próprios pacotes via scan_packages).