ADK-gateway/gateway-task/references/api_reference.md

网关任务 API 参考

网关 Base URL：http://localhost:8000。

认证

# 本机开发环境：
# - 后端 D:\workspace\ADK-gateway .env 中 GATEWAY_AUTH=<实际值>
# - 若未配置，默认值为 dev-gateway-auth
AUTH="<GATEWAY_AUTH>"

认证传递方式：

• POST 写入型接口（提交任务、Agent 注册/心跳/结果/注销）：auth 在请求体 JSON 中。
• GET 查询、SSE 订阅、取消：auth 作为 query 参数 ?auth=<AUTH>。

任务接口

1. 提交任务（推荐：带 cli_session_id 以便 SSE 免轮询）

curl -X POST http://localhost:8000/api/cli/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "auth": "'"$AUTH"'",
    "task_type": "generate",
    "task_tags": ["dev"],
    "cli_session_id": "cli-123",
    "payload": {"prompt": "生成一个炫酷的时钟 HTML 文件"},
    "timeout": 300
  }'

关键：若要免轮询通过 SSE 拿结果，cli_session_id 必须传，且与订阅 GET /api/cli/events 时用的 session 完全一致。

中文编码（重要，Windows 下必读）

Windows PowerShell 下直接用 curl -d '{...中文...}' 或 Invoke-WebRequest 传中文，会把中文转成 ? 乱码。必须用 UTF-8 编码的 JSON 文件 + --data-binary @file：

1. 用 UTF-8（无 BOM）写入请求文件 request.json：

{
  "auth": "gw_xxx",
  "task_type": "generate",
  "task_tags": ["dev"],
  "cli_session_id": "cli-123",
  "timeout": 300,
  "payload": {"prompt": "请在您的工作目录下创建一个炫酷的时钟 HTML 文件"}
}

2. 提交：

curl -s -X POST "http://localhost:8000/api/cli/tasks?auth=<AUTH>" \
  -H "Content-Type: application/json" \
  --data-binary "@request.json"

注意 auth 放在 query 或 body 均可，但 body 内的 auth 也需保留。用 --data-binary @file 可避免 Shell 对引号/中文的再转义。

响应（TaskInfo）：

{
  "request_id": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
  "task_type": "generate",
  "task_tags": ["dev"],
  "payload": {"prompt": "生成一个炫酷的时钟 HTML 文件"},
  "status": "pending",
  "agent_id": null,
  "cli_session_id": "cli-123",
  "create_time": 1710000000.0,
  "timeout": 300,
  "progress": 0,
  "result": null,
  "error_info": null
}

2. 订阅任务完成事件（SSE，推荐，免轮询）

curl -N http://localhost:8000/api/cli/events?cli_session_id=cli-123\&auth="$AUTH"

• SSE 长连接（text/event-stream）。先订阅，再提交带相同 cli_session_id 的任务。
• 任务到达终态（success / failed，含取消/超时）时，网关推送：

data: {"event": "task_done", "request_id": "9f8e...", "status": "success", "result": {...}, "error_info": null}

• 支持回放：即使连接晚于任务完成，也会先收到历史完成事件，再收实时事件。
• 收到目标 request_id 的 task_done 即完成，无需轮询。

3. 查询任务状态（兜底）

curl "http://localhost:8000/api/cli/tasks/<request_id>?auth=$AUTH"

• 未找到返回 404。
• status 取值：pending（排队）、running（执行中）、success（成功）、failed（失败/取消/超时）。
• success 时 result 为结果字典；failed 时 error_info 说明原因（如 cancelled by user、timeout、无可用 Agent）。
• progress 为 0~100 的整数进度。

成功任务的 result 结构：

{
  "reply": "我先查看工作目录环境，然后创建烟花特效文件。",
  "output": "已生成文件：D:\\workspace\\firework.html（17236 字节）。实现：Canvas 粒子系统、火箭拖尾升空、爆炸粒子、点击放花与自动循环。"
}

• reply：Agent 接受任务后的首条完整回复（展示为"Agent 接受任务回复"）。
• output：Agent 执行完成后的最终总结（展示为"Agent 总结"）。
• 失败/取消/超时任务 result 为 null，此时以 error_info 为准。

4. 取消任务

curl -X POST "http://localhost:8000/api/cli/tasks/<request_id>/cancel?auth=$AUTH"

• 仅 pending / running 可取消；已终态返回 400。
• 成功：{"ok": true, "request_id": "<request_id>"}。

Agent 接口

所有 Agent 接口 auth 在请求体 JSON 中。

注册

curl -X POST http://localhost:8000/api/agent/register \
  -H "Content-Type: application/json" \
  -d '{
    "auth": "'"$AUTH"'",
    "agent_id": "agent-001",
    "endpoint": "http://agent-host:9000",
    "agent_tags": ["dev"],
    "max_concurrent": 2,
    "current_load": 0
  }'

心跳

curl -X POST http://localhost:8000/api/agent/heartbeat \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent-001"}'

未注册返回 404。

结果回传

curl -X POST http://localhost:8000/api/agent/result \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "<request_id>",
    "agent_id": "agent-001",
    "status": "success",
    "progress": 100,
    "result": {"output": "build ok"},
    "error_info": null
  }'

注销

curl -X POST http://localhost:8000/api/agent/unregister \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent-001"}'

典型对话引导（CLI 中提交任务）

当用户（CLI 中）请求提交任务时，按以下顺序执行：

1. 读取网关 .env 获取 GATEWAY_AUTH（默认 dev-gateway-auth）与 ADMIN_AUTH。
2. 与用户确认 task_type 与关键参数（task_tags、payload），不明确时做合理假设并说明。
3. 生成一个 cli_session_id（如 cli-<时间戳>）。
4. 先订阅 SSE：GET /api/cli/events?cli_session_id=<sid>&auth=<AUTH>（后台发起）。
5. 再提交任务：POST /api/cli/tasks，请求体带相同的 cli_session_id。若 payload 含中文，务必用 UTF-8 文件 + --data-binary @file（见上文"中文编码"）。
6. 从 SSE 事件流中等待该 request_id 的 task_done 事件，拿到 status / result / error_info；若 SSE 不可用则回退为 GET /api/cli/tasks/{request_id} 轮询。
7. 向用户汇报最终状态与 result（reply = Agent 接受任务回复、output = Agent 总结）；失败时汇报 error_info。

任务卡住时的排查步骤

若任务长时间 pending 或 failed：

1. 查 error_info 定位原因（无可用 Agent / timeout / cancelled by user / 具体异常）。
2. 无可用 Agent：调 GET /api/admin/agents（Header X-Admin-Auth: <ADMIN_AUTH>）核对 Agent 的标签交集、状态（须 ready/processing）、是否满载。
3. timeout/cancelled：多为 Agent 侧执行慢、被取消，或 Agent 进程异常；先确认 Agent 进程存活（访问其 endpoint 健康路径），必要时重启 Agent。
4. 展示时注意：PowerShell 会把嵌套 JSON 包装成 CLIXML，直接用 type file.json 看会误以为 result 是 {"type":"execute_command_result",...}。应改用 python -c "import json,sys; print(json.load(open(f))['result'])" 或 python -m json.tool 等干净解析，再判断 reply/output 是否真实存在。

错误码

HTTP	含义
400	请求不合法（如取消已结束任务、缺少 agent_id）
401	auth 与 GATEWAY_AUTH 不一致（POST 在 body、GET/取消/SSE 在 query）
404	任务/Agent 不存在
422	请求体字段缺失或类型错误