Blog
实践15 分钟阅读

我为什么推倒重写了自己的 AI Agent?

一次重写,让我重新理解状态、上下文和系统边界。

开发者将复杂的水母形 Agent 拆开,重新组织记忆、消息与工作流模块。
重写的起点,是重新理解每个模块应该承担什么。

第一次把 Agent 的主链路跑通时,我以为最难的部分已经结束了。

模型能调用,数据能落库,向量能召回,工作流也能顺利走到最后。对于一个第一次用 LangGraph 做完整项目的人来说,这已经足够让我兴奋一阵子。

但真正开始连续使用,问题才一个个冒出来:明明配置了 checkpoint,下一轮模型却不知道上一轮发生了什么;工作流拆得很细,状态里却塞满了没必要保存的中间产物;数据库里存了不少信息,模型拿到的上下文却未必有用。

更难受的是,每当产品需求发生变化,我总要先解释一遍,为什么现有架构不太支持这个需求,再想办法把它硬塞进去。

后来,我决定重写。

为了方便讨论,下面隐去项目的具体业务,把它看作一个需要持续积累上下文、支持多轮交互的对话 Agent。这篇也不打算罗列一遍技术栈,我更想聊聊那些真正让我卡住的地方,以及这些问题怎样改变了我对 Agent 开发的理解。

一、我把工作流状态,当成了模型的记忆

最早的架构是一条比较长的 Pipeline:加载业务对象、整理基础资料、构建检索 query、召回信息、组织上下文,最后调用模型。

为了方便节点之间传递数据,我把途中产生的东西几乎全部放进了 Graph State。查询结果、检索 query、组织到一半的上下文,甚至 SQLAlchemy 的 ORM 实例,都往里面塞。

当时的理解很简单:State 不就是跨节点共享的数据吗?放进去,下个节点直接拿,多方便。

直到接入 checkpoint,问题来了。

首先是序列化。ORM 实例不能像普通字典一样直接交给当时的 checkpoint 序列化链路。其次是持久化范围:很多只在本次执行中有用的临时数据,也跟着状态一起被存了下来。

我最初的修法是在最后一个节点里把中间字段清空。后来才意识到,checkpoint 在执行过程中就会记录状态,最后清空一次,并不能消除前面已经写下的快照。

但这还不是最大的坑。

为了支持连续追问,我希望第二轮直接复用第一轮保存的上下文,省掉一次耗时的构建过程。配置相同的 thread_id,接着调用 Graph,结果模型仍然像没见过上一轮一样。

仔细看链路,原因其实很直白:状态恢复了,但我在调用模型时,只构造了一条新的 HumanMessage。历史信息躺在 State 里,没有被组织进本次请求,模型自然看不到。

更离谱的是,第二轮输入里,我还给上下文字段传了一个空字符串。本来想表达“这轮不重新计算”,实际效果却是用空值覆盖了已有状态……

这次之后,我才真正把几件事分开:

数据在系统里的职责
节点内部的临时变量完成当前步骤,用完即可丢弃
Graph State在节点间传递、按需要恢复的执行状态
消息历史多轮交互中需要保留的对话内容
本次模型输入当前任务真正需要消费的信息

checkpoint 能帮助恢复执行状态,但哪些内容进入模型输入,仍然需要我自己设计。反过来,State 很大,也不意味着每次请求一定会消耗很多 token;只有把这些内容发送给模型,它们才会成为输入成本。

这个区别看起来很基础,但我确实是栽过一次才懂的。

我也重新考虑了节点的划分。之前几乎是一个函数拆一个 node,后来又一度走到另一个极端,把整条链路塞回一个 node。继续做下去才发现,节点边界应该跟着执行需求走:需要独立观察、分支路由或者并行调度的步骤,拆出来有价值;只在局部使用的转换逻辑,普通函数就够了。

存储柜里的信息经过选择后,才被送入右侧模型。
存下来的状态,只有被组织进本次请求,才会成为模型能使用的上下文。

二、模型处理得慢,有时是我给它出的题太难

早期有一条输入链路,需要从截图中恢复结构化记录。

我要求模型识别每条消息的说话人、内容、时间,再整理成严格的 JSON。为了提高准确性,还给用户加了不少限制:截图按顺序上传、包含时间、控制张数等等。

结果并不理想。一次尝试中,两张截图处理了大约两分钟,仍然存在时间混乱、说话人错位和无效内容。

第一反应当然是继续调 prompt。但再看一遍最终用途,我突然发现,自己并不需要把原始记录一条不漏地恢复出来。

下游真正需要的是:这段材料围绕什么主题,包含哪些值得保留的信息,以及它们发生在什么语境下。

于是我把数据粒度从“逐条原始记录”调整为“围绕一个主题组织的信息”。模型不再承担完整复原记录的任务,后续检索也不用先从大量零散消息里重新拼出语义。

当然,这个方案当时也有代价:我要求用户单次提交的材料尽量属于同一主题,相当于把一部分分段工作交还给了用户。它减轻了处理负担,但还不能算完全解决了输入体验。

这件事让我开始习惯在优化模型之前,先问两个问题:最终功能究竟需要什么信息?现在要求模型输出的粒度,是不是超过了实际用途?

数据库能装下原始记录,不代表模型必须逐条重建它;模型能输出一套复杂结构,也不代表产品需要用户等它把这套结构填完。

三、上下文的难点,从“存下来”转向“这轮怎么用”

最初做记忆,我的注意力主要在写入端:资料怎么抽取、数据怎么建模、文本怎么向量化。

后来接触一些以 Markdown 组织上下文的方案,我发现它们在信息分类和表达上有很多值得借鉴的地方。但我试用的方案中,一些文件要求每轮必读,其他文件则按需全量加载。

资料少的时候,这样很直接。资料逐渐变多之后,我开始担心,每次只需要一小部分信息,却要先加载整份文件。

于是重构时,我保留了基础资料,把更细的信息拆成独立条目,支持后续按问题检索。这里,数据库负责管理条目的归属、分类和时间,文本内容负责表达模型需要理解的语义。

但有了向量检索,问题也没有自动消失。

早期召回主要依赖语义距离。后来我逐渐加入业务范围过滤、重要性权重,以及对部分信息的时间衰减。因为“与问题很相似”和“适合用于当前回答”,并不是一回事。

尤其是时间。

我曾经只在系统提示词里放一个“当前时间”,后来才意识到,它无法说明历史消息分别发生在什么时候。再往上游看,即使数据库有创建时间,如果抽取后的文本丢掉了原始材料中的年份、时期或阶段,模型仍然容易把不同时间发生的相似事情混在一起。

后来的调整分成两部分:对话消息显式带时间戳;抽取信息时,把材料中可确认的时间锚点保留到正文里,无法确定的时间则不补写。

这比单纯调整排序公式更靠前。时间信息在抽取时丢了,检索阶段很难凭空找回来。

另外,我也尝试过把知识召回封装成 Tool,让模型判断何时需要补充资料,避免每轮机械地跑完整套检索。

但 Tool Call 又暴露出另一个边界:模型不能稳定生成当前业务对象的 ID。这个 ID 明明已经在系统运行上下文里,我却还要求模型再猜一次。

最后,我在执行工具前注入当前上下文中已确定的参数。模型可以决定是否需要检索、检索什么;至于当前用户是谁、正在操作哪个对象,以及是否有权访问,应该由程序确定和校验。

这些问题做下来,我对上下文的理解才从“收集得尽可能多”,逐渐转向:为当前任务保留必要信息,并让它以合适的形式进入模型。

至于每项改动究竟提高了多少效果,我没有足够系统的评测数据,不想在这里编一个百分比。能确认的是,我开始知道应该沿着哪条链路排查,而不再只盯着最终回答调提示词。

四、拆了目录,不代表真的解耦了

过去做 Web 项目,我很习惯先写后端,再包装 HTTP 接口,最后给前端调用。这个 Agent 最初也沿用了类似结构,业务能力和 Web 服务放得很近。

后来产品主要通过 IM 交互,我又加入 CLI,用来执行配置、管理和诊断操作。到这时,业务层继续依赖 Web 框架就显得很别扭。

于是我把 Service 拆出来,让它承载业务与数据访问能力,再由不同入口调用。

听起来已经解耦了,对吧?现实又给了我一拳。

一次运行 CLI 的帮助命令,输出的竟然是 Web 框架的帮助。

原因是命令模块导入 Service,Service 又在顶层导入了 Web 框架的 Request 类型。它原本只是一个类型注解,却在运行时把整个框架带进来,并影响了命令行参数解析。

修法并不复杂:纯类型依赖移到 TYPE_CHECKING 下,命令注册阶段尽量保持轻量,真正执行时再加载必要模块。

但这件小事让我意识到,架构图上的依赖箭头,最终要落实到模块导入和初始化行为上。一个看起来很干净的 Service,如果导入它就会带起框架、读取参数或启动外部连接,换个入口调用时,问题照样会冒出来。

后来我又为了简化用户配置,把一部分数据能力尝试放到远端。原先拿 ORM 对象的地方,要改为消费明确的返回结构;入口和 Graph 中散落的数据库操作,也得继续往 Service 收。

我加了一层统一分发:本地模式调用 Service,远程模式调用对应 HTTP API。序列化也在这个边界处理,避免枚举、时间对象和可选参数的转换散落在各处。

比如一个缺省的查询参数,在 Python 函数里传 None 很自然,到了 HTTP query 编码却可能直接报错。修复应当收在请求边界,同时保留 0、False 这些有实际意义的值;也不能顺手把 JSON 请求体里的显式 null 一起删掉。

这些都不是什么复杂算法,却决定了“本地能调用的函数”能不能成为一个可靠的远程接口。

五、用户少配一个数据库,系统就多了一组责任

做 CLI 和 IM 入口,最初是为了减少独立前端的开发量,也让用户在熟悉的地方交互。

但把安装流程串起来,我发现自己只是省掉了前端,用户仍然要准备数据库、模型配置和机器人配置。代码能跑通,距离用户愿意用,中间还有很长一段路。

因此我尝试让服务端承接数据库访问,减少用户自行建库的负担。

第一个约束很明确:不能为了方便,就把共享数据库的连接凭据发到客户端。普通数据操作可以通过鉴权 API 承接,但工作流的 checkpoint 依赖数据库连接,它不会因为我加了 HTTP 路由,就自动获得远程存储能力。

当时的处理是保留两种行为:本地模式继续用 PostgreSQL 持久化 checkpoint;实验性的共享模式改用进程内存。

代价也很明确:进程重启后,共享模式下的这部分短期记忆会丢失。

我没有把这个问题彻底解决,只是接受了一个降级,换取不向客户端暴露数据库连接的运行方式。它也不意味着 checkpoint 永远不能远程化,只是当时那套分发层覆盖不了它,继续抽象的成本已经超出了那一轮的目标。

更麻烦的问题还在后面。

某些看起来是“数据同步”的 Service,内部其实会调用模型。把它移到服务端,究竟应该使用谁的模型配置?用户的配置怎么传?调用成本由谁承担?

原先在单机里,数据库、模型配置和执行环境都在同一个地方,这些问题很容易被忽略。跨过网络之后,每一项都得重新回答。

登录态也一样。为减少后台任务被 token 过期打断,我一度采用了不设置过期时间的方式。但它留下的轮换、撤销和失效治理问题仍然存在,不能因为主链路继续运行,就说鉴权已经设计完整。

最终,共享模式的部分链路虽然已经打通,我还是隐藏了公开配置入口。模型配置归属和服务端代执行的边界没有处理干净,就不应该让用户把它当成一个已经准备好的选项。

这也是我在产品层面的一次转变:降低使用成本,意味着有人要承担原先交给用户的复杂度。数据库不用用户配了,服务端就要接住相应的权限、配置和运行责任。一个 “Easy Mode”,远不止是少展示几个输入框。

用户桌面上的配置变简单,背后的服务端承接权限、存储、配置和运行责任。
用户少配一项,系统就要接住相应的责任。

六、一次提示词服务故障,让我重新看待运行依赖

还有一次教训,跟模型能力几乎没有关系。

为了方便调优,我把提示词放在外部平台,运行时实时拉取。修改提示词不必重新发布,开发体验确实很好。

然后平台服务出故障了。

我既没有保留本地备份,也没有设计读取失败的兜底,涉及提示词的链路一下子全部挂掉。外部服务大约两天后恢复,但这两天足够让我意识到:我把一个开发便利工具,放成了运行时的硬依赖。

这件事给我的教训很具体。提示词虽然是一段文本,在系统里却承担着实际执行逻辑;它的版本、备份和可用性,都需要认真对待。把它放到远端管理,并不会让这些责任消失。

后来的开发过程中,我也开始把反复出现的协作要求沉淀成 Skill:改动后做质检、记录变更、同步 Graph 文档,以及把纠偏写回规则。

这些规程不能替代测试,也不能保证 Agent 每次都执行正确。但至少,同一种遗漏再次出现时,我有机会修改持续被消费的规则,而不只是再提醒一次。

写到最后

回头看,这次重写并不是在某一天想通全部问题,然后画一张新架构图,一次性完成。

我先误解 checkpoint,再重新设计状态;先追求细粒度输入,再回到下游实际需要的语义;先拆业务层、删掉不必要的入口,后来为了新的部署方式又补回 HTTP 服务。新的问题不断出现,前面做过的选择也会被重新审视。

我不再特别纠结“当初是不是选错了框架”。真正让我绕远路的,是没有弄清楚一些更基础的边界:什么需要持久化,什么需要进入模型,哪些参数由程序决定,以及一项能力换了运行位置之后,会把哪些责任一起带过去。

现在开始写一个新功能,我会比以前多花一点时间追问这些问题。它们不一定能让我第一次就做对,但能让我少写一些看起来已经完成、换个场景却又要推倒的代码。

至于这次重写,我最愿意留下的成果,大概就是这些后来会继续影响我怎么写代码的问题。