这一节建议你先把接口角色分清楚,再去读下面的 Flask 代码。配合这张图去看,会非常省脑子。
![图片[1]-小节四:实现 POST /api/v1/runs 与 GET /api/v1/runs/{run_id}-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1615.png)
这张图表达得很清楚: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,否则原失败的时间、错误和证据都会被覆盖。
















请登录后查看评论内容