小节四:实现 POST /api/v1/runs 与 GET /api/v1/runs/{run_id}

这一节建议你先把接口角色分清楚,再去读下面的 Flask 代码。配合这张图去看,会非常省脑子。

图片[1]-小节四:实现 POST /api/v1/runs 与 GET /api/v1/runs/{run_id}-大赛人网

这张图表达得很清楚:POST /api/v1/runs 负责“创建一个 Run”,所以它更像起点;而 GET /api/v1/runs/{run_id} 负责“查询这个 Run 现在执行到哪里了”,所以它更像状态观察窗口。也正因为两者职责不同,POST 返回 201 是合理的,而后面轮询状态、读取 steps / error / answer 的动作,就应该交给 GET 去承担。

现在正式做 API。

本章不急着异步。

POST /runs 可以:

创建 Run
马上同步执行
最后返回 Run 状态

虽然调用仍然同步,但 API 模型已经独立。

下一步要改异步时,结构无需推翻。

POST 请求

POST /api/v1/runs

请求:

{
  "session_id": "sess_demo",
  "message": "检查这个 Python 项目"
}

为什么现在要 session_id?

因为我们本章已经正式建立,Run 必须属于某个 Session。

GET 请求

GET /api/v1/runs/{run_id}

返回:

{
  "run_id": "run_xxx",
  "session_id": "sess_demo",
  "status": "completed",
  "start_time": "...",
  "end_time": "...",
  "steps": [
    ...
  ],
  "error": null
}

完整 Flask 示例

下面代码完整可运行。

创建 Run

curl -X POST \
  http://127.0.0.1:5000/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":"sess_demo",
    "message":"检查这个 Python 项目"
  }'

会返回:

{
  "run_id": "run_xxx",
  "session_id": "sess_demo",
  "status": "completed",
  "start_time": "...",
  "end_time": "...",
  "steps": [
    {
      "step": 1,
      "kind": "reason",
      "detail": "理解任务:检查这个 Python 项目"
    },
    {
      "step": 2,
      "kind": "tool",
      "detail": "模拟检查 Python 项目"
    }
  ],
  "error": null,
  "answer": "项目检查完成:检查这个 Python 项目"
}

查询 Run

curl \
  http://127.0.0.1:5000/api/v1/runs/run_xxx

这时真正形成:

创建任务
 ↓
得到 run_id
 ↓
后续按 run_id 查询

为什么 POST 返回 201?

因为,创建了一个新的 Run 资源。

这是比统一返回 200 更清晰的 REST 语义。

更完整的响应还可以带:

Location: /api/v1/runs/run_xxx

状态码要和执行方式一起看:同步接口创建并完成一个 Run,可以返回 201 和完整资源;异步接口只接收任务、尚未完成时通常返回 202。若 Agent 执行失败但失败 Run 已经成功落库,资源仍然存在,客户端应读取 Body 中的 status=failed;如果连 Run 都没创建成功,才是创建接口本身的 4xx/5xx。关键不是背一个数字,而是让合同没有歧义。

上面的单文件示例还有两个明确限制。第一,Run 只在进程字典里,服务重启后 GET 会变成 404;第二,GET 没有鉴权,只适合本机单用户实验。共享部署前必须把 Run 放进持久化存储,并按当前身份校验 Session / Run 归属。下一节先做 Streaming,第 22 节再正式接 SQLite。

为了让代码集中在一处,这个组合示例直接修改了 Run 字段。真正项目不要照着这一点扩张:Service 应调用前面统一的 start_run()、complete_run() 和 fail_run(),避免 HTTP 入口与后台 Worker 各写出一套不同的转换规则。

创建接口还要承接上一节的幂等约定。客户端超时后带同一个 Idempotency Key 重试,应拿到原 run_id,而不是再创建一个 Run;如果用户明确要重跑,则创建新 Run,并用 retry_of 或 parent_run_id 指向原任务。重试不是把 failed 原地改回 running,否则原失败的时间、错误和证据都会被覆盖。

© 版权声明
THE END
喜欢就支持一下吧
点赞11 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容