Agent Gateway API
由
scripts/generate-api-docs.ts自动生成 —— 请勿手改 共 17 个端点
GET /gateway/agents/status
查询 Agent 在线状态——支持 ?agentId=xxx 查单个
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agentId | query | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 200 |
GET /gateway/dialogue/assistant
取平台助手会话（没有就建）——直聊的默认落点，也是主动播报的落点
响应
| 状态码 | 说明 |
|---|---|
| 200 |
GET /gateway/dialogue/history
对话层指标采样历史（默认最近 60 分钟）
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
minutes | query | number | — | 回溯分钟数，默认 60 |
limit | query | number | — | 最大采样条数，默认 500 |
响应
| 状态码 | 说明 |
|---|---|
| 200 |
GET /gateway/dialogue/metrics
对话层实时指标（会话 / 轮次 / tokens per session / 429 / TTL 回收 / 延迟）
响应
| 状态码 | 说明 |
|---|---|
| 200 |
GET /gateway/dialogue/sessions
获取用户的所有活跃对话 Session
响应
| 状态码 | 说明 |
|---|---|
| 200 |
POST /gateway/dialogue/sessions
创建新的对话 Session——指定 agentId 直接对话，或按 skillId 自动匹配
响应
| 状态码 | 说明 |
|---|---|
| 201 |
DELETE /gateway/dialogue/sessions/{sessionId}
删除对话 Session——软删除，列表接口不再返回（与 end 区分）
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
sessionId | path | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 200 |
GET /gateway/dialogue/sessions/{sessionId}
获取对话历史
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
sessionId | path | string | ✅ | |
taskId | query | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 200 |
POST /gateway/dialogue/sessions/{sessionId}/end
结束对话 Session
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
sessionId | path | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 201 |
POST /gateway/dialogue/sessions/{sessionId}/message
在对话 Session 中发送消息——消息会转发到绑定的 Agent
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
sessionId | path | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 201 |
POST /gateway/dialogue/sessions/{sessionId}/message/stream
发送对话消息（SSE：start → delta* → done → [result] / error）
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
sessionId | path | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 201 |
GET /gateway/dialogue/sessions/{sessionId}/result
读取本次对话提交到状态层后的结果（pending / ready / none）
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
sessionId | path | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 200 |
GET /gateway/tasks
Agent 拉取待处理任务（X-Api-Key 认证，只能拉取本 Agent 的任务）
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agentId | query | string | ✅ | |
status | query | string | ✅ | |
userId | query | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 200 |
POST /gateway/tasks/{taskId}/claim
认领任务——原子抢占（pending/delivered → claimed），防止供应商多实例重复执行
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
taskId | path | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 201 |
POST /gateway/tasks/{taskId}/result
Agent 回传任务结果（X-Api-Key 认证；完成回传需通过 skill output_schema 校验）
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
taskId | path | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 201 |
POST /gateway/tasks/{taskId}/review
人工审核草稿结果（X-Api-Key 认证，只能审核本 Agent 的任务）
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
taskId | path | string | ✅ |
响应
| 状态码 | 说明 |
|---|---|
| 201 |
POST /gateway/test-push
推送任务到 DB——Agent 轮询拉取，不等待 Socket.IO 响应
响应
| 状态码 | 说明 |
|---|---|
| 201 |