Agent 架构拆解：把一次任务拆成状态、计划、工具与账本四层

从一个「已完成」的假答复说起

上周有个任务卡得很难看：让 Agent 把一份周报拆成五条待办写进项目看板。它跑了 19 步，烧掉 0.37 元的 token，最后回了一句「已完成，五条待办均已创建」。用户点进看板，一条都没有。

翻日志才看清过程：第 6 步写接口返回 429 限流，第 7 步它把参数换了个顺序重试，第 8 步再试一次，第 9 到 14 步开始反复读同一份文档，第 15 步上下文被压缩，前面的失败记录正好被裁掉，于是它就当自己写成功了。

问题不在模型笨，而在这套东西缺了四层结构。下面按数据流的顺序拆。

状态层：任务状态不能寄生在对话历史里

把「做到哪了」记在 messages 数组里，是几乎所有问题的起点。历史会被压缩、会被截断、会被摘要，一旦某一步的执行结果在压缩时被丢掉，Agent 对现状的认知就凭空断了一截，而它自己并不知道断了。

• 状态要单独存：任务 ID、当前阶段、已完成的步骤、待确认的槽位，写进一个结构化对象，每步工具调用后落一次盘。压缩多少轮都不影响它。
• 槽位要显式：用户说「下周三的会」，就要落成具体日期和时区，缺失就追问一次。让模型每轮从历史里重新推断，是同一个信息被推断 N 次，N 越大错得越多。
• 检查点要能回放：每步写一个检查点，失败时从第 N 步重来，而不是从头再来一遍。这一步直接影响成本，也影响用户等多久。
• 会话与任务解耦：同一会话里并行两个任务时，状态按任务 ID 隔离，否则两条任务会互相覆盖槽位，症状是「它把 A 的参数填进了 B」。

计划层：分解粒度与重规划的边界

计划层最容易做过头。把任务拆成二十步的 DAG，看着专业，实际执行到第七步就已经跑偏，剩下的节点全在做无用功。

• 步数上限是硬约束：我给每个任务的预算是 12 步，超了强制收敛，把已完成的部分和卡住的原因一起交回用户。实测超过 15 步的任务，成功率断崖下降，成本却线性上涨。
• 重规划要有触发条件：只在「同一工具连续两次同类失败」或「前置假设被证伪」时重规划，其余情况继续执行。没有触发条件，模型会在两个方案间来回横跳，日志看着很忙，进度是零。
• 失败要按类型分流：网络超时可重试，参数错误重试无用，权限不足必须换路或上报。三类混在一个 catch 里，就会看到它拿同一个错误重试五次。
• 计划要留白：不要把「用户可能想加一条」这种分支提前写进计划，把它留给运行时判断。计划越细，现实稍微一变就全废。

工具层：超时、幂等与返回裁剪

工具层的取舍最容易被低估，因为它看起来只是「调个接口」。真正决定成败的是三件事。

• 单步超时 30 秒：超时立即返回结构化错误，不要让一次调用把整个任务挂在原地。一个挂住的 HTTP 连接，能让用户等八分钟。
• 写操作必须幂等：带业务唯一键，重试前先查一次。否则「创建待办」重试三次，就是三条一模一样的待办。
• 返回结果先裁剪再进上下文：一个查询接口返回 20KB JSON，真正有用的可能只有三个字段。裁剪之后，单步 token 从 6000 降到 400，同一类任务成本从 0.37 元压到 0.11 元。这不是优化，这是可不可用的分界线。
• 副作用工具要沙箱或二次确认：删除、转账、发消息这类动作，宁可多一次人工确认，也别让它自己判断「应该没问题」。

账本层：每一步都要留下可验证的痕迹

没有账本，前面三层都调不准，因为你不知道失败发生在哪、花了多少、是不是真的成功。

• 每步记四件事：动作、参数摘要、结果状态、消耗 token。落成一行 JSONL，排障时按任务 ID 一捞就全。
• 预算分两级：单步预算与单任务预算，任一触顶就收敛并交回用户，别等撞上 API 的硬限额才发现。
• 成功判据必须可验证：「接口返回 200」不等于「事情办成了」。写看板要回查一次列表，确认记录真的在，才算完成。

最后这条是最贵的教训。开头那个任务的根因就在这里：它把 HTTP 200 当业务成功，把「我说完成了」当成「确实完成了」。加一条回查之后，同类故障在我这边基本绝迹，代价是每个写任务多一次读请求。

小结

四层拆完，其实每层都在解决同一件事：把「模型觉得」换成「系统可验证」。状态层验证的是进度，计划层验证的是方向，工具层验证的是副作用，账本层验证的是结果。

落地顺序建议：先做状态和账本，便宜、见效快、当天就能上线；再做工具治理，把超时、幂等、裁剪补齐；最后才是计划和重规划，因为它依赖前三层提供的信号。反过来做，通常只会得到一个更会自圆其说的循环。