先交代一下背景。我从去年年初开始搭一个面向垂直行业的 AI Agent 项目从需求梳理、架构选型到核心流程实现再到今年年初开始小范围放量陆陆续续在 Git 里留下了 1277 次提交。这个数字不是我刻意刷出来的而是几百个日夜的真实记录。前阵子做了一次阶段性复盘把提交记录按主题过了一遍有个结论让我自己都有点意外——这 1277 次提交里真正在跟模型能力较劲的其实很少大头全耗在了模型之外的地方上下文管理、工具调用、状态追踪、可观测性、测试回归。今天就把这段经历摊开聊聊希望能给准备从 0 到 1 搭 AI Agent 的朋友一些参考。1. 1277 次提交的真实构成模型只占了一小部分先上一组当时统计的提交分布数据。我按改动目的把提交分成了几类模型/提示词调整、工具函数开发、上下文与记忆逻辑、流程控制与状态机、日志与可观测性、测试用例、基础设施与部署。统计下来模型/提示词调整相关的提交大约占 22%工具函数开发占 18%上下文与记忆逻辑占 17%流程控制与状态机占 15%日志与可观测性占 12%测试用例占 10%剩下 6% 是部署、CI/CD、依赖升级这类基础设施改动。这个分布说明了一件事绝大多数时间都花在了让 Agent 稳定、可控、可维护上而不是花在选哪个模型、怎么写提示词上。模型更像是一个已经存在的能力基座真正决定项目成败的是基座之上那层工程骨架搭得够不够扎实。在项目的早期阶段我和大多数人一样把注意力都放在了模型选型和提示词打磨上。当时 DeepSeek、GPT 系列、开源权重模型来回切换逐个用实际任务评估效果甚至还做了简单的打分对比。但等 Agent 真正开始处理连续多步任务时我很快就意识到模型能力的天花板远远没有触到反倒是那些围绕模型搭建的工程环节一个接一个地成了瓶颈。模型偶尔输出差一点换个更好的模型或微调一下提示词就能解决但上下文越用越乱、工具调用链路的错误无法追踪这类问题不是换个模型就能翻篇的。另一个有意思的数据是提交时间分布。项目早期的提交非常密集上午和下午的改动主题经常完全不一样上午还在写工具调用逻辑下午就在处理上下文窗口溢出的问题这种频繁的切换本身就说明问题——AI Agent 开发里各种看似不相干的坑会同时冒出来你永远不知道下一个卡住你的是哪个环节。2. 上下文管理才是头号翻车点失忆与中毒的双重困境我在这个项目里最深刻的教训就是AI Agent 的上下文管理远比选模型要难得多。甚至可以说Agent 与普通 LLM 应用的本质区别就藏在上下文里。2.1 从对话上下文到任务上下文的思维转变如果你只是做一个单轮问答机器人上下文管理非常简单把用户问题塞进 prompt模型回答完就结束了。但 Agent 不是这样它要在一个会话里连续决策和执行可能要调用五个、八个甚至更多的工具每一步的输入输出都会累积到上下文里。这个过程中会出现两个极端情况。一是信息过载上下文被中间结果塞满真正重要的指令被淹没模型的注意力被大量噪音分散。二就是信息丢失对话太长之后早期的重要约束像不要调用更新类接口或用户偏好简洁回答会被后续内容挤出去Agent 在后续步骤中做出了违背初始约束的行为。当时项目里有个很典型的翻车场景。一个用户让 Agent 帮忙查询并整理某类商品的库存信息Agent 先查询了商品列表然后又逐个查询了每个商品的库存详情导致上下文里堆积了大量中间表格数据。接着用户补充了一句把库存低于 50 的商品找出来。Agent 却开始在之前那堆中间数据里找甚至做出了错误的汇总。问题根源不是模型不够聪明而是上下文里数据太多太久指令和数据的边界变得模糊。2.2 我的上下文管理方案分层记忆机制为了解决这个困境我设计了一套分层记忆机制这个架构后来也是我提交次数最频繁的区域。核心思路是区分短期工作记忆、长期事实记忆和任务指令记忆三层。短期工作记忆存放当前任务进行中的中间结果。我限制这一层的 token 数上限一旦超过阈值就把相对不重要的中间结果压缩成一句话摘要比如把一段详细的工具返回结果压缩成调用了 get_inventory API返回了 62 个商品的库存数据关键异常项3 个商品库存为 0。压缩后原始数据移到外部存储需要时再按需查询。长期事实记忆存放用户偏好、历史事实这类跨会话的信息。这一层我用的是向量库加实体存储的组合方案按任务需要动态拉取。比如用户多次强调回复用表格形式这类偏好会被写入长期记忆在每次任务开始前自动注入指令区。任务指令记忆则专门保存当前任务的初始要求和约束。系统会在每一轮 Agent 执行前把任务指令记忆重新注入 prompt 的靠前位置确保它不会被中间结果挤掉。这样做之后Agent 跑偏的概率明显下降。这里有一个很关键的操作细节不要在每一轮对话里都把所有记忆灌进去而是要给记忆分配合适的位置。我把任务指令放在 prompt 开头用户本次输入放在中间偏前的位置长期事实记忆放在用户输入之后工具返回结果放在最后。这样排布的原因很简单模型通常对开头和结尾的内容记忆更深刻中间区域相对容易忽略。把重要的指令放在注意力最强的区域能显著降低失忆的概率。2.3 上下文管理里最容易被忽略的 token 成本还有一个和成本相关的点值得单独说上下文膨胀会直接拉高 API 费用。我算过一笔账一个中等复杂度的任务如果不对上下文做任何压缩三轮工具调用下来输入 token 可能从几千膨胀到三万以上。而采用压缩策略之后同样任务输入 token 能压到一万以内。日请求量大的时候这个差异直接体现在账单上。所以上下文管理不是事后的优化而是架构设计阶段就要考虑的核心模块。你在最开始写 Agent 的时候脑子里就要有一张上下文流动的图景知道自己每一轮会往里面放什么、什么时候清理什么。3. 工具调用链路看起来能通跑起来全是雷模型选型的纠结其实很快就结束了真正折磨人的是工具调用。我刚做 Agent 的时候天真地以为 function calling 很成熟只要把函数定义传给模型模型就会规规矩矩地调用。实际上工具调用链路里埋着好几个让人崩溃的雷。3.1 参数幻觉模型会一本正经地编造参数最让我头疼的问题就是参数幻觉。模型会生成一个格式正确的函数调用但参数值却来自它自己的脑补而不是来自真实的用户输入或上下文。举个例子我们的 Agent 有一个查天气的工具参数是城市名。用户在会话里说帮我看看北京和上海的天气。模型正常应该生成两次调用传北京、上海两个城市名。但实际运行中模型有时会突然传一个它自己编出来的城市名比如北京市朝阳区或者更离谱把用户前几轮提过但已经作废的地点又翻出来当成当前参数。这类问题极难发现因为从代码逻辑上看函数调用成功了数据也返回了只是返回的内容不对。排查起来需要回看整个上下文才能判断这个参数到底是用户真实意图还是模型脑补的。3.2 函数定义越写越长调用结果却不稳定另一个问题是函数定义的描述文本。为了帮助模型更准确地识别参数我把每个函数的描述越写越长字段说明也越来越详细。结果发现函数定义的长度和解析准确率不是正相关有时候定义太长反而干扰模型的判断它在一个小字段上纠结反而忽略了更核心的参数。后来我把函数定义做了精简只保留最重要的参数描述和严格的枚举值约束复杂的业务规则挪到函数内部做校验而不是全靠模型理解。这个调整之后参数错误率反而下降了。总结下来一个规律函数定义要给出严格边界而不是求全求细模型不是在考场里做阅读理解的。3.3 工具返回值的爆炸性增长工具调用的返回值也是个大坑。有些接口一次能返回几百条数据把这些数据全部塞进上下文token 立刻飙升而且这些原始数据占用了注意力干扰了后续决策。我采用的方案是对工具返回值做了一层规约处理每个工具返回的数据都要经过一个轻量级摘要器只保留结构化的统计信息和关键异常项。比如库存查询接口我让摘要器输出共查到 62 个商品库存其中低于安全库存的 3 个商品编号 10231、20334、40921最低库存 12 件。原始数据不进入上下文而是短暂落在一个临时存储里如果 Agent 后续需要某条具体记录再按需取用。3.4 重试机制要考虑到状态变化工具调用的重试也是门学问不是简单地在失败后重新执行一遍就行。很多接口不是幂等的重试可能导致重复下单、重复发送通知这类副作用。我的做法是把工具按幂等性分成两类幂等工具可以安全重试非幂等工具出错后必须进入人工确认流程由用户在界面上确认是否重试。这个分类在代码层面做了硬性约束防止模型在错误恢复时做出危险决策。这一块的教训让我真正体会到AI Agent 的工程难点不在让模型输出东西而在如何让模型输出的东西处于一个可控、可校验、可恢复的流程里。工具的入口和出口都需要校验层入口校验参数合法性出口校验返回值是否在预期范围内。4. 流程控制与状态机不把 Agent 放进轨道里它就会飞出天际刚开始做 Agent 的时候我倾向于让模型自由发挥以为这样最智能。实际跑起来之后自由发挥带来了大量难以预料的执行路径有的路径走到一半就卡死有的路径反复调用同一个工具甚至出现循环。4.1 自由决策的代价记忆深刻的一个事故是这样的Agent 被要求更新一批数据第一步执行成功后模型在第二步决策时选择了重新调用第一步的工具因为上一步的返回结果显示数据还有更新空间但实际上数据已经达成目标状态这个不必要的调用把状态弄脏了。后来排查发现问题不在于模型笨而在于 Agent 没有一种机制来感知当前处于哪一步、这个步骤是否已经完成。自由决策在高层次其实是模型的优势但在每个步骤内部如果完全没有约束那就是在裸奔。我逐渐意识到Agent 需要一个执行框架我给这个框架起名叫轨道约束——给 Agent 一条明确的行动轨道轨道内允许有选择空间但轨道的边界必须强制守住。4.2 状态机的引入后来我引入了状态机作为流程控制的核心。一个任务被拆分成若干个阶段比如意图识别、信息收集、方案确认、执行、结果校验。每个阶段之间通过明确的状态转换条件连接。拿信息收集阶段举例如果 Agent 需要查询多个数据源状态机规定这一阶段只允许调用查询类工具不允许任何写操作或更新类操作直到状态转换到方案确认阶段。这种拆分让每个阶段的行为边界清晰模型在边界内做决策出错概率大幅下降。4.3 中断恢复Agent 里的断电重启状态机还解决了一个隐蔽的问题中断恢复。Agent 执行过程中随时可能遇到 API 超时、进程崩溃、网络波动如果任务没有状态持久化重启之后整个 Agent 就从零开始。而在状态机里每一步执行完成都会把状态写入持久化存储。进程重启后Agent 可以恢复到中断点而不是重头再来。这里不得不提到一个常见误解Agent 不是无限自动运行的黑盒它应该是一个可以被随时暂停、检查、恢复的流程系统。状态机给的就是这个可控性。4.4 流程引擎选型与现实取舍做状态机的时候我纠结过是直接用现成的流程编排框架还是自己写一个轻量的状态管理模块。最后选了自研轻量方案原因有两个一是现成框架通常太重为了支持各种复杂编排引入大量概念学习成本和维护成本都不低二是 Agent 的状态流转有自己的特点不是简单的一条 DAG它有时候需要根据模型决策动态跳转兼顾确定性和灵活性的需求市面上的通用框架并不完全契合。我的实现其实很简单一个状态上下文对象包含当前状态、执行历史、关键数据快照一个状态转换表明确定义每个状态下允许的动作和下一个状态一组状态守卫函数在执行动作前校验前置条件。这一套在自己的项目里跑得很稳也让我对 Agent 的流程控制有了更细颗粒度的掌控力。5. 可观测性AI Agent 调试为什么这么难以及我的解法AI Agent 的调试是我职业生涯里遇到的最难问题之一。常规软件的 bug 可以靠堆栈、断点、日志定位Agent 的 bug 往往没有堆栈没有断点只有一段看起来完全合理但结果不对的中间过程。5.1 黑盒困境你看到的只是模型想了什么当 Agent 执行出错时你问的第一句话永远是它为什么会这么做。但模型不是一个清晰的决策过程它给不出完整的决策链路。没有中间步骤的记录你就像在黑夜里摸黑找东西完全没有方向感。这个痛点让我在项目进入联调阶段后几乎把一半的精力投在了可观测性建设上。我的目标是让每一次 Agent 决策过程变得可回放、可审查而不是只留下最终输出。5.2 我的可观测体系决策轨迹与状态快照我在系统每一层都埋了详细的 trace 数据。具体来说包含这么几类第一类是决策轨迹。模型的每次 prompt 输入、模型输出、每个工具调用的参数和返回值都会以结构化的形式记录下来。尤其在 prompt 输入方面我会记录完整的 prompt 快照包含当前上下文里有哪些记忆、哪些历史数据。这些快照就是回放现场的最关键素材。第二类是状态快照。在状态机每一步执行前后记录完整的 Agent 状态当前处于哪个阶段、上下文 token 用量、已完成的操作列表、待处理的候选动作。状态快照用来回答一个问题Agent 在做出某个决策时它的世界模型是什么第三类是运行指标。包括每次模型调用的延迟、token 消耗、工具调用的成功率、重试次数。这类指标一般不会定位到具体 bug但能帮你发现趋势性问题比如某个工具调用失败率异常升高或者上下文压缩后 token 明显减少但任务成功率反而下降了。5.3 一个真实排查过程上下文压缩导致的信息丢失我讲一个用这套可观测体系定位问题的案例。项目跑了一段时间后有用户反馈 Agent 有时候会忘记用户是 VIP 客户这个重要身份导致回复的语气和建议内容都偏离预期。光靠猜很难定位而且很多环节都可能出错。我打开一条完整的决策轨迹在关键的那次调用里翻看 prompt 快照发现上下文压缩模块在某一轮发生了误判把一条格式为VIP 身份标记的长期事实记忆当成临时中间数据给压缩了。压缩摘要里没有完整保留 VIP 身份信息Agent 后续决策时就丢失了这个关键约束。问题根因不在模型而在压缩策略里没有区分记忆类型优先级设置不严谨。修复方案是在压缩模块里加入记忆类型保留规则重要记忆不仅不压缩还要在任务执行期间固定在 prompt 的指令区域。那次定位过程用到的全部素材几乎都来自提前埋好的 trace 数据没有 trace 的话这个问题我可能几天都查不出来。5.4 给新项目的一个建议日志从第一天就要埋好我踩过的坑是前期觉得日志埋点浪费时间等出问题才临时补结果发现很多关键节点已经无法追溯。如果让我重新做从第一天起就会为 Agent 单独建立一套日志体系和普通业务日志分开存。格式尽量统一方便做离线分析方便直接灌进一些数据分析工具里做聚合统计。可观测性这个东西本身就是 Agent 项目的地基工程。模型能力再强可控性为零也是白搭。每一步都留痕才是 Agent 项目能持续迭代的前提。6. 测试与回归Agent 系统里的反直觉工程测试在 Agent 项目里遇到的反直觉程度远超我最初的想象。传统软件测试的根基是确定性你输入什么就必然输出什么但模型输出天生有随机性同样的输入可能得到不同的结果这种情况下测试理念必须做调整。6.1 为什么传统断言式测试在 Agent 项目里行不通我刚开始给 Agent 写测试时用的是传统思路给定一个测试场景执行 Agent 流程断言最终输出包含某个关键词。结果发现测试非常不稳定有时通过有时失败而且失败原因跟需求功能未必相关可能只是模型换了个更委婉的说法。后来我意识到对 Agent 系统的测试重心应该放在行为约束验证上而不是结果对错验证。我们要验证的是Agent 有没有启用正确的工具、有没有跨过不该跨的边界、有没有在关键节点做出明显不合理的选择而不是验证它说的某句话是否精确匹配。6.2 Mock LLM把不确定性从测试里请出去面对模型输出不确定性的一个有效武器是 mock LLM。在测试环境里我不调用真实模型而是用一套 mock 回应机制来模拟模型的决策输出。mock 数据是根据测试场景预先设计好的比如在测试查库存并生成报告这个场景时mock 模型会返回预设的调用参数确保 Agent 流程稳定走过每一步。这样做的最大价值是让测试回归变得稳定。CI 里跑一条 Agent 跑链路二十四小时之后跑同样的测试结果是一致的。这种确定性对排查问题太重要了你能保证是代码改动导致的失败而不是模型情绪化的输出导致的。6.3 除了 mock需要一套概率性测试做兜底Mock LLM 补上了确定性的需求但如果你完全依赖 mock就会忽略真实模型的概率性行为问题。所以在 mock 测试之外我还设计了一套概率性测试在测试环境接真实模型跑一些典型的高频场景用多个指标评估结果比如工具调用正确率、任务完成率、越界行为次数等。这类测试不需要每次结果都一样但指标需要落在可接受的波动范围内。这套双轨测试体系确定性测试负责守护基本功能概率性测试负责洞察真实表现两者组合下来回归测试的效能明显提升。提测阶段的内心安全感也回来了不少。6.4 快照测试在 Agent 回归里的妙用还有一个我后来加上的测试方案快照测试。当 Agent 产出一类固定格式的结果比如某个特定任务的报告模板我会把输出结果做快照存储。后续每次修改系统自动对比新快照和基准快照的差异再人工审核差异是否符合预期。这个方法在调整提示词或模型版本时特别好用能一眼看到改动对输出风格和内容产生了哪些影响。调整提示词最怕的事情就是东边修好西边坏快照测试能在一定程度上防止这种问题。每次改动后跑一遍快照对比哪些模块受影响一目了然由不得你觉得心里没底。6.5 测试数据也是一等公民最后补一个容易被忽略的点Agent 测试数据的管理难度远比常规软件测试数据要高。因为 Agent 的测试离不开多轮会话记录这些记录要覆盖各种分支情况而且要定时更新避免测试数据与实际使用场景脱节。我建了一个测试场景库专门存放各种用户会话样本、期望路径和边界条件按模块分类维护跟代码一起走版本管理。这样新功能开发时能顺手补一条场景用例进去时间一长整个场景库的价值会越来越大几乎成了项目的半份需求文档。7. 1277 次提交沉淀下来的几点工程建议写完踩坑记录再回到 Git 这个视角聊聊代码层面的工程习惯。AI Agent 项目的代码变动特点和普通业务项目有显著差异某些做法对普通项目只是锦上添花在 Agent 项目里就成了刚需。首要建议是拆小提交。Agent 项目的尝试性质非常浓一个改动往往不是一步就能完成的常常是一个思路试了不行立刻回退。提交颗粒度小每次提交承载一个明确的改动主题这样回滚和定位都方便。比如一次提交只改工具描述的措辞另一次提交只重构上下文压缩策略而不是把十处改动揉成一大坨提交。事后翻 Git 历史的时候逻辑非常清晰哪些尝试有效哪些无效一目了然。然后是分支策略。我从项目中期开始改成特性分支加主干合并的模式每个功能模块或实验性改动都开独立分支验证稳定后再合回主干。这么做还有一个额外的好处每条分支的提交历史就是一次实验记录模型的 prompt 调整过程、上下文策略的演化轨迹全都在分支历史里保存着。这比任何设计文档都真实。还要特别说的是 commit message 的规范。不是格式的规范而是内容的规范一定要写明这次改动背后的原因。项目里我要求每次提交都交代清楚为什么。普通项目里fix bug这类 message 也就忍了但 Agent 项目里的bug往往不是直截了当的它背后是某个上下文策略失效、某个工具调用链路的边界问题不写明原因过两周回看历史压根不知道当初为什么要做这个改动。另外Agent 相关的配置和数据也要做版本管理。我指的是 prompt 模板、函数定义结构化描述、上下文压缩规则、测试场景库这些内容它们其实都是项目的核心资产理应进 Git。把这些配置和数据纳入版本控制之后每次改动都可追溯出问题时能快速对比变更差异。最后关于团队协作也补一句Agent 项目里代码审查的重点应该放在钩子逻辑部分也就是那些决定 Agent 行为边界的代码而不是放在模型调用的细节里。模型参数调得再花哨如果流控逻辑有漏洞上线照样出事故。 Review 重点看状态机的转换条件、工具调用的校验层、上下文压缩的策略这些地方才是事故高发区。1277 次提交记录下来的其实不止是代码的演化更是我从一个模型中心论思维方式慢慢变成一个工程控制论思维方式的过程。如果你也正准备做一个 AI Agent 项目我的核心建议是把模型当成已经稳定的基础设施把剩下的全部精力投到上下文、工具、流程、可观测性、测试这五个工程模块上。模型天天在进步但围绕模型构建的工程控制力才是每个 Agent 项目真正的护城河。