交互式文档
每个 Agent-Lab 应用都会自动提供 OpenAPI 3 文档——参考实现位于 http://localhost:18000/docs（或者你自己的应用运行所在的地址）。下面的目录记录了框架内置的路由；你的 extra_routers 也会出现在同一个 schema 中。
认证
当 auth.enabled 为 true 时（参见配置参考），各路由都需要 Keycloak bearer 令牌。/auth 路由仅在启用认证时才会挂载：
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| 方法 | 端点 | 说明 |
|---|---|---|
| POST | /auth/login |
创建新的 bearer 令牌 |
| POST | /auth/renew |
续期现有的 bearer 令牌 |
| POST | /auth/exchange |
用 Microsoft Entra ID 授权码（PKCE）换取应用令牌 |
| GET | /auth/profile |
获取已认证用户的资料 |
| PUT | /auth/profile |
更新已认证用户的资料 |
realm/客户端的设置请参阅使用 Keycloak 进行认证。
无需认证的路径：/status/*、/docs、/openapi.json、/mcp、/static、OAuth well-known 端点以及 SPA 挂载路径——其他所有路径都需要有效的令牌。
端点
智能体
可以创建任何已注册智能体类型的实例；agent_type 会依据注册表进行动态校验。
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | /agents/list |
列出所有智能体实例 |
| GET | /agents/types |
列出已注册的智能体类型（即注册表） |
| GET | /agents/{agent_id} |
按 ID 获取智能体实例 |
| POST | /agents/create |
创建新的智能体实例 |
| POST | /agents/update |
更新智能体的基本信息 |
| POST | /agents/update_setting |
更新单个智能体设置 |
| POST | /agents/{agent_id}/reset_settings |
将智能体的设置重置为默认值 |
| DELETE | /agents/delete/{agent_id} |
删除智能体实例 |
| WS | /agents/ws/task_updates/{agent_id} |
长时间操作的任务进度更新 WebSocket 流 |
消息
| 方法 | 端点 | 说明 |
|---|---|---|
| POST | /messages/post |
向智能体发送消息并获取回复 |
| POST | /messages/list |
列出某个智能体的消息 |
| GET | /messages/{message_id} |
获取展开后的消息详情（回复、附件） |
| DELETE | /messages/delete/{message_id} |
删除消息 |
语言模型
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | /llms/list |
列出已配置的语言模型 |
| GET | /llms/{language_model_id} |
获取语言模型及其设置 |
| POST | /llms/create |
创建新的语言模型 |
| POST | /llms/update |
更新语言模型的配置 |
| POST | /llms/update_setting |
更新单个语言模型设置 |
| DELETE | /llms/delete/{language_model_id} |
删除语言模型 |
集成
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | /integrations/list |
列出外部集成（AI 供应商） |
| GET | /integrations/{integration_id} |
获取集成详情 |
| POST | /integrations/create |
创建集成（凭据存储在 Vault 中） |
| DELETE | /integrations/delete/{integration_id} |
删除集成 |
附件
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | /attachments/list |
列出附件 |
| GET | /attachments/download/{attachment_id} |
下载附件 |
| POST | /attachments/upload |
上传文件附件 |
| POST | /attachments/embeddings |
为附件生成嵌入 |
状态与 MCP
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | /status/liveness |
存活探针 |
| GET | /status/readiness |
就绪探针 |
| GET | /status/metrics |
Prometheus 指标 |
| * | /mcp |
MCP 服务器（Streamable HTTP） |
| GET | /.well-known/oauth-protected-resource/mcp |
面向 MCP 客户端的 OAuth 元数据 |
请求示例
创建智能体实例——agent_name 接受 [a-zA-Z0-9_-]；agent_type 必须是已注册的类型；language_model_id 为可选项：
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发送消息——message_role 取值为 human、assistant、tool 之一；attachment_id 为可选项：
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更新智能体设置——setting_key 接受 [a-zA-Z_-]；setting_value 最多可容纳 16,000 个字符（提示词模板和 JSON 载荷都存放在这里——参见实体领域模型）：
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约定
- ID 均为 UUID；所有列表端点都接受 JSON 请求体，而不是查询字符串。
- 设置是与智能体或模型一同持久化的键值对——同一个实现正是借此运行多个配置各异的实例。
- 注册表是有效
agent_type值的唯一可信来源——运行GET /agents/types即可查看正在运行的应用发现了哪些类型（包括通过scan_packages引入的你自己的包）。