小节二：实现第一个完整 Flask Agent API——真正跑通 POST /api/v1/chat

这一节可以理解成：我们开始把原来只能在本地 agent.run() 跑起来的能力，往“别人也能稳定调用”的方向推进。下面这张图把这条演进路径拆成了 7 步，看起来会特别顺。

图里最值得记住的一点是：服务化不是推倒重写，而是一层层长出来。先跑通本地能力，再把输入输出抽清楚，再往外包一层 Engine、Service 和 Route，最后补上错误处理、日志、鉴权、Session / Run。这样做既保住了你前面已经写好的核心能力，也让后面继续扩展时不至于返工。

现在开始写代码。

这一版我们先实现：

Flask
AgentService
AgentEngine
Run ID
Error Response

完整代码如下。

安装 Flask

python3 -m pip install "Flask>=3.0,<3.2"

启动服务

假设代码保存为：

app.py

运行：

python3 app.py

终端会看到开发服务器启动。

curl 调用

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

响应类似：

{
  "answer": "已完成项目检查。当前任务是：检查这个 Python 项目",
  "run_id": "run_8d1272ad0d42",
  "status": "completed"
}

课程项目中的可运行版本

上面的单文件版适合第一次看清调用链。课程项目把同样逻辑放进应用工厂：

from agent_harness.service.chat_api import (
    create_chat_app,
)


app = create_chat_app()

create_chat_app(engine=...) 允许测试时注入一个假的 Engine，不必真的调用模型。完整实现还会严格区分非法 JSON 和字段错误，限制消息长度，为每次请求生成 request_id，并把内部异常写入服务端日志。

在项目根目录运行：

python3 \
  projects/06_flask_run_api/minimal_chat_api.py

默认监听 http://127.0.0.1:5001。如果端口冲突，可以追加 --port 5007。这里继续只监听本机；要让局域网或公网访问，还需要部署和安全配置，不要为了让手机暂时连上就直接把教学服务器暴露出去。

到这里，发生了什么本质变化？

以前：

agent.run(...)

只能被 Python 代码调用。

现在：

curl
浏览器
前端
App
其他服务

只要能访问 HTTP，就可以使用 Agent。

这就是，Backend Service。