案例分析二：Data Analysis Agent 被另一个后端服务调用，为什么 run_id 从第一版接口就值得保留？

这一节里 run_id 看起来只是多返回了一个字段，但它背后其实对应的是一个非常重要的分离：会话连续性和单次执行生命周期，不应该混为一谈。先配合下面这张图理解一下，会更顺。

如图能一眼看出来：Session 关注的是“谁在聊”“上下文是否连续”，而 Run 关注的是“这次执行有没有开始、现在是什么状态、能不能查询、能不能取消”。也正因为这样，哪怕第一版接口还没有完整的 RunManager，先把 run_id 预留出来也是很值的。因为一旦后面接入异步执行、状态轮询、长任务追踪，你会发现这个字段几乎立刻就派上用场。

场景背景

另一个内部服务调用：

POST /api/v1/chat

任务，“分析昨天收入下降原因。”

这次 Agent 运行 25 秒。

中间查询多个指标。

最终返回：

{
  "answer": "...",
  "run_id": "run_72d1c8",
  "status": "completed"
}

第二天有人反馈，“昨天 15:20 那次分析结果不对。”

如果没有 run_id，只能从：

时间
用户
问题文本

猜是哪一次。

有 run_id 就可以：

run_72d1c8

直接关联：

Trace
Tool Calls
Token Usage
Error
Latency

即使现在还没有 RunManager，也值得先返回

因为 API 一旦被外部调用，后面再新增必填标识可能影响客户端。

所以第一版就返回：

run_id

是很合理的前置设计。

下一节会继续做什么？

这一节的 run_id 只是：

唯一字符串

下一节会让它真正拥有：

status
start_time
end_time
steps
error

也就是完整 Run 生命周期。

常见误区

误解： 第一个 Agent API 只要能返回模型文本就够了，run_id 和 status 都可以以后再说。
正解： 如果这个接口只是一次性 Demo，当然可以只返回 answer；但一旦准备作为 Backend Service，run_id 很快会用于日志、Trace、错误排查和状态查询，status 也会扩展成 running、failed、waiting_approval 等。第一版就保留这两个字段，可以让协议更稳定。

误解： POST /api/v1/chat 里面直接 new 一个 Provider、Registry 和 AgentEngine 最简单，也没什么问题。
正解： 每次请求都重新初始化核心组件，会产生重复加载、状态难共享和资源浪费。更合理的是在应用启动时初始化 Engine 和 Service，请求进来只调用已有实例。后续 SessionManager、连接池、Tool Registry 也更容易统一管理。

误解： API 参数校验可以交给 Agent，让模型自己判断 message 是否为空。
正解： message 是否缺失属于确定性程序校验，不应该消耗模型能力。HTTP 层应该直接返回 400。可确定的事情应该由程序处理，不确定的语义问题才交给 Agent，这和整门课程“确定性逻辑放在 Harness”是一致的。

误解： 捕获 Exception 后把完整 traceback 返回给客户端最方便调试。
正解： traceback 应该写入服务端日志或 Trace，而对外返回稳定错误结构。直接暴露内部路径、依赖版本和堆栈会泄露实现细节，也使客户端依赖不稳定字符串。生产系统应区分内部诊断信息与外部 API Error。

误解： Flask Route 里调用 agent.run() 就已经完成服务化，所以不需要 AgentService。
正解： 很小的 Demo 可以直接调用，但随着 Session、Run、持久化、权限进入，Route 会越来越重。AgentService 提供稳定的业务协调边界，让 HTTP 层与 Runtime 层分开。课程现在提前加入，是为了后面不用大规模重构。

误解： 只要 curl 能访问，说明这个 API 已经适合生产。
正解： 这一节只完成第一条 Backend Service 链路。生产还需要正式 Run 生命周期、Streaming、SQLite 持久化、并发、鉴权、超时、日志、安全和 WSGI 部署等。能被 HTTP 调用是服务化的起点，不是终点。

误解： request.get_json(silent=True) or {} 已经覆盖所有非法输入。
正解： 这种写法会把语法错误、null 和缺失 Body 都压成空字典，还可能让 JSON 数组在后续 .get() 时触发 500。先判断结果是否为 dict，再逐字段校验类型，错误才能稳定区分。也不要用 str(...) 把数字 message 悄悄转成合法输入。

误解： 测试 API 必须先启动服务器，再通过真实端口访问。
正解： curl 适合验证完整网络链路，但参数校验、错误码和 Service 调用更适合用 Flask Test Client 自动测试。通过 create_chat_app(engine=...) 注入假的 Engine，可以稳定覆盖成功、失败和异常路径，不依赖模型、端口或外部网络。

误解： 返回统一的外部错误后，内部异常可以不记录。
正解： 对外不泄露 traceback 与对内保留诊断证据是两件事。服务端应记录完整异常和 request_id，客户端只收到稳定 code、message 与 request_id。否则接口虽然“安全地失败”，维护者却无法定位是哪一步出了问题。