案例分析二：给飞书机器人接入 Agent，如何管理请求与任务生命周期

如果说前一个案例强调的是 Web 产品化，那这个案例更强调“企业协作入口 + 任务系统”。下面这张图从飞书用户发消息开始，一路串到 Bot 接收、API / Route、AgentService、AgentEngine，再到回调或轮询拿结果，最后回复飞书用户。

这样一看就会特别清楚：飞书机器人真正接入 Agent 之后，背后跑的并不是一个“收到消息就立刻返回”的小脚本，而是一整套带 Session、Run、异步执行、状态追踪和回调机制的任务链路。也正因为如此，它才不只是“接了个机器人”，而是在接一个可管理的任务系统。

场景背景

用户在飞书输入：

@Agent
帮我看昨天收入为什么下降

飞书平台会把事件发向一个网络地址：

Feishu
 ↓
Webhook
 ↓
Your Server

只有本地脚本时的问题

假设你只有：

python3 data_agent.py

飞书根本不知道：

脚本在哪
怎么启动
参数怎么传
session_id 怎么关联
结果怎么返回
失败怎么表示

它需要的是网络协议。

加入 Agent Server 后

可以有：

POST /feishu/events

Adapter 解析：

user
message
conversation

然后统一调用：

AgentService.execute(...)

最终再把结果回传飞书。

Webhook 平台通常要求服务端尽快确认收到事件。如果 Route 一直阻塞到 Agent 分析结束，平台可能因超时重复投递同一事件。更稳的流程是先验证和去重，再创建 Run 并快速应答，后台执行完成后通过平台消息接口回传结果。这正好再次说明：网络请求和 Agent Run 是两个生命周期。

为什么这不只是“做个机器人”

一旦 Agent Server 存在，同样能力还可以服务：

监控告警
内部数据平台
移动端
浏览器页面
自动化任务

所以真正可复用的资产不是某个机器人，而是，Agent Server。

常见误区

误解： 既然 Flask 可以调用模型，就把 Agent Main Loop、Tool 和 Memory 全部写进 Route 最简单。
正解： Demo 确实可以这么做，但 Route 很快会同时承担网络、会话、任务生命周期、模型、工具、错误和持久化责任。更稳的结构是 Flask Route 只处理 HTTP，AgentService 做业务协调，AgentEngine 保留 Main Loop 与 Harness。这样 CLI、Web、飞书才真正共享同一个 Agent。

误解： 服务化以后原来的 agent.run() 就没有用了。
正解： agent.run() 仍然可以作为 AgentEngine 的内部接口，CLI、测试甚至某些本地任务都可以继续调用。变化只是它不再是唯一外部入口。Web 和其他系统通过 AgentService/HTTP API 间接调用它，因此服务化是增加边界，而不是推翻原实现。

误解： HTTP API 只是为了给前端页面调用。
正解： 前端只是其中一个客户端。App、飞书、告警系统、自动化任务、Java/Go 服务都可以通过同一个 Agent API 使用能力。HTTP 的真正价值是跨语言、跨进程、跨部署环境复用 Agent，而不是单纯“做网页”。

误解： 本地 Flask app.run(debug=True) 跑起来，就等于 Agent 已经可以生产部署。
正解： Flask 开发服务器只适合本地调试。生产系统还需要 WSGI Server、并发、超时、鉴权、Session 持久化、Run 生命周期、Streaming、错误码、安全控制和监控。本节只是建立服务边界，后续章节才会逐步补齐真实服务能力。

误解： Session、Run、Streaming 都只是 Flask 的附加功能，和 Agent 本身关系不大。
正解： 这些需求真正来自 Agent 的运行特征：长执行、多步骤、多轮状态、工具调用和可恢复性。普通 CRUD 请求可能几十毫秒就结束，而 Agent 可能运行几十秒并不断产生进度。因此服务化只是把这些已有特性暴露出来，后端必须正式管理它们。

误解： 如果现在只有一个调用方，就完全没必要考虑服务层。
正解： 如果目标永远只是个人本地工具，CLI 完全可以长期保留；但一旦计划接 Web、远程设备、多用户、其他系统或统一权限，Service/API 边界就很有价值。是否服务化应该由产品目标决定，而不是为了技术复杂度本身。

误解： 客户端请求超时，说明 Agent 没有执行，可以放心重试。
正解： 超时只表示客户端没按时收到响应，请求可能已经创建 Run，甚至已经执行了 Tool。直接重试可能产生重复任务。创建类接口应支持幂等键，并允许客户端用原 run_id 查询状态；取消也要通过独立、可审计的状态转换完成。

误解： SessionManager 放在 Flask 全局变量里，所有请求自然就能共享。
正解： 这只在当前进程内成立。多 Worker、滚动发布或服务重启后，内存状态可能消失或分裂。需要可靠恢复的 Session、Run 和事件应进入共享持久化存储；本地内存适合教学和缓存，不适合作为生产环境唯一事实来源。

误解： Service 直接接收 Flask request，少传几个参数会更方便。
正解： 这样会让业务层依赖 Web 框架，CLI、测试、飞书 Adapter 都难以复用。Route 应先完成协议解析和身份验证，再构造普通业务命令交给 Service；AgentEngine 更不应该知道 Cookie、Header 或 Flask Request Context。