Referência da API REST

Documentação interativa

Todas as aplicações Agent-Lab servem automaticamente OpenAPI 3 — a implementação de referência em http://localhost:18000/docs (ou a sua própria aplicação, onde quer que esteja em execução). O catálogo abaixo documenta os routers incluídos na framework; os seus extra_routers aparecem no mesmo esquema.

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/cliente é descrita em Autenticação com Keycloak.

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

Endpoints

Agentes

Criar instâncias de qualquer tipo de agente registado; agent_type é validado dinamicamente face ao registo.

Mensagens

Modelos de linguagem

Integrações

Anexos

Estado e MCP

Exemplos de pedidos

Criar uma instância de agente — agent_name aceita [a-zA-Z0-9_-]; agent_type tem de ser um tipo registado; 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 definição de agente — setting_key aceita [a-zA-Z_-]; setting_value comporta até 16 000 caracteres (é aqui que residem os templates de prompts e os payloads JSON — 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

• Os IDs são UUIDs; todos os endpoints de listagem aceitam corpos JSON, e não query strings.
• As definiçõ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 forma diferente.
• O registo é a fonte de 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 os seus próprios pacotes através de scan_packages).