AI Agent工程实战：从七要素到七个决策点的系统设计指南

AI Agent 这个词在过去一年里被反复提及但真正动手搭过一套能跑起来的 Agent 系统的人都知道从知道它是什么到让它稳定干活之间隔着一整套工程决策。我前后参与过几个 Agent 项目的落地从最初用现成框架拼装到后来自己拆解每一层的职责边界踩过的坑基本都集中在几个固定的地方循环怎么设计、工具怎么调、状态怎么管、失败怎么兜。这篇内容不打算讲概念科普而是把 Agent 从七要素到七个决策点这条链路完整拆开讲清楚每个环节在工程上到底要做什么选择、为什么这么选、选错了会怎样。适合已经了解 LLM 基础、准备或正在搭建 Agent 系统的开发者也适合想搞清楚 Agent 内部到底怎么运转的技术负责人。1. 七要素拆解Agent 系统的最小完整单元很多人一上来就问用哪个框架但框架只是外壳真正决定系统能不能跑通的是七个核心要素是否都到位。这七个要素不是并列关系而是有依赖顺序的缺一个都会导致系统在某个环节卡死。1.1 模型层不只是选一个 LLM 那么简单模型层是 Agent 的大脑但工程上要决策的远不止用哪个模型。你需要考虑的是主推理模型和辅助模型怎么分工。实际项目中我通常会把模型分成三类角色来用。第一类是主推理模型负责理解用户意图、规划任务步骤、决定下一步调用什么工具。这类模型需要较强的指令遵循能力和推理能力通常选参数量较大、经过指令微调的版本。第二类是工具调用模型专门负责把自然语言意图转成结构化的工具调用参数。有些场景下主推理模型可以直接兼任但如果工具参数格式复杂单独用一个更擅长结构化输出的模型会更稳。第三类是结果总结模型把工具返回的原始数据转成用户能读懂的回复这类任务对推理能力要求不高可以用更轻量的模型来降低成本。为什么要做这个分工因为一个模型很难在所有维度上都最优。主推理需要深度思考工具调用需要格式精确结果总结需要语言流畅这三个目标在训练时是有张力的。分开之后每个环节都可以独立调优和替换不会因为换一个模型就把整个系统搞崩。还有一个容易被忽略的点上下文窗口的实际可用量。标称 128K 的模型实际能稳定利用的可能只有一半左右因为中间部分的信息容易被遗忘。所以在设计时不要把关键信息塞在超长上下文的中间位置要么放在开头要么放在结尾要么通过外部存储来管理。1.2 记忆层短期、长期、工作记忆的三层结构记忆层是 Agent 区别于单次 LLM 调用的核心。没有记忆每次对话都是重新开始Agent 就无法完成多步骤任务。工程上我习惯把记忆分成三层。短期记忆就是当前对话的上下文通常用消息列表来维护直接塞进模型的上下文窗口。工作记忆是当前任务执行过程中的中间状态比如已经完成了哪些步骤、当前卡在哪一步、已经收集到哪些信息。这部分不一定全部塞进上下文而是用一个结构化的状态对象来管理需要的时候再取出来。长期记忆是跨会话的知识比如用户的偏好、历史任务的结论、领域知识库通常存在外部存储里通过检索来调用。这三层的管理策略完全不同。短期记忆的关键是截断和压缩——对话太长时要决定丢弃哪些、总结哪些。工作记忆的关键是结构化——不能是一堆散乱的文本而要有明确的字段和状态机。长期记忆的关键是检索质量——存进去容易取出来准才是难点。我踩过的一个坑是早期把所有东西都往短期记忆里塞结果上下文迅速膨胀模型开始忽略中间的信息任务执行到一半就忘了之前做过什么。后来改成工作记忆用独立的状态对象管理只在每一步需要的时候把相关部分注入上下文稳定性提升非常明显。1.3 工具层Agent 与外部世界交互的唯一通道工具层决定了 Agent 能做什么。没有工具Agent 只能说不能做。工具的设计质量直接决定了 Agent 的能力上限。工具层要解决三个问题工具怎么定义、工具怎么选择、工具怎么执行。定义方面每个工具需要清晰的名称、描述、参数 schema 和返回值格式。描述要写得让模型能准确判断什么时候该用这个工具而不是靠猜。参数 schema 要严格该必填的必填该枚举的枚举减少模型自由发挥的空间。工具选择是 Agent 循环中的核心决策点。当工具数量超过十个之后模型选错的概率会明显上升。常见的做法是分组——把工具按领域分成几组先让模型选组再在组内选具体工具。另一种做法是预过滤——根据当前任务状态先用规则或轻量模型筛掉明显不相关的工具只把候选工具给主模型选。工具执行方面最关键的是超时和重试策略。外部工具调用可能失败、可能超时、可能返回格式不对的数据。每个工具都要有独立的超时设置和重试逻辑不能用一个全局配置糊弄过去。我一般会给每个工具配三个参数超时时间、最大重试次数、失败后的降级行为。1.4 规划层从想到哪做到哪到有章法地推进规划层是很多 Agent 项目最容易做薄的地方。没有规划Agent 就是走一步看一步遇到复杂任务就容易迷失。规划层的核心是任务分解和执行顺序编排。任务分解是把用户的模糊需求拆成可执行的步骤执行顺序编排是决定这些步骤是串行、并行还是有条件分支。工程上有两种主流做法。一种是显式规划——先让模型生成一个完整的步骤列表然后按列表逐步执行。这种做法的好处是全局可见、容易调试坏处是如果第一步就理解错了后面全错。另一种是隐式规划——不生成完整计划而是在每一步根据当前状态决定下一步做什么。这种更灵活但容易陷入局部最优做着做着偏离了原始目标。我实际项目中用的是混合模式先做一次粗粒度的显式规划把任务分成几个大阶段每个阶段内部用隐式规划逐步推进。这样既有全局方向又有局部灵活性。粗粒度规划不需要太细三到五个阶段就够了太细反而容易因为实际情况变化而频繁调整。1.5 执行层循环机制的设计与边界控制执行层就是 Agent 的主循环是整个系统运转的引擎。循环机制设计得好不好直接决定了 Agent 是智能还是智障。一个基本的 Agent 循环是这样的接收输入 → 模型推理 → 决定动作 → 执行动作 → 观察结果 → 判断是否完成 → 未完成则回到推理。看起来简单但每个环节都有工程决策。循环终止条件是最关键的。不能只靠模型说我完成了来判断因为模型可能会误判。我通常设三重保险模型显式声明完成、达到最大循环次数、连续 N 次没有产生有效动作。三个条件满足任意一个就终止避免死循环烧钱。循环中的状态传递也很重要。每一轮循环要把哪些信息传给下一轮全部传会导致上下文膨胀传太少会导致信息丢失。我的做法是维护一个结构化的执行状态每轮只把当前步骤相关的上下文 全局状态摘要注入模型而不是把完整历史都塞进去。1.6 反馈层让 Agent 知道自己做得对不对反馈层是 Agent 自我修正的基础。没有反馈Agent 就无法判断自己的输出质量也无法在出错时调整策略。反馈分两种内部反馈和外部反馈。内部反馈来自 Agent 自身的判断比如模型对自己输出的置信度、格式校验的结果、逻辑一致性检查。外部反馈来自工具返回值、用户输入、环境变化。工程上最实用的是结构化校验。每次工具调用返回后不要直接把原始结果丢给模型而是先做一轮格式和内容的校验把校验结果作为反馈的一部分。比如调用搜索工具返回了空结果不要只说搜索完成而要明确告诉模型搜索返回了 0 条结果可能需要换关键词或换数据源。1.7 安全层不是可选项是必选项安全层在原型阶段经常被忽略但一旦上线就是致命的。Agent 的安全问题比普通 LLM 应用更复杂因为它能执行动作。安全层要覆盖几个方面输入过滤——防止恶意指令注入工具权限控制——不是所有工具在任何场景下都能调用输出审查——防止 Agent 生成或执行有害内容操作审计——记录每一步动作便于追溯。我特别想强调的是工具权限的最小化原则。每个工具只给完成当前任务所需的最小权限不要图省事给一个大权限工具。比如文件操作读和写要分开写操作要限定目录范围。这些在原型阶段可能觉得麻烦但上线后能避免很多灾难性问题。2. 七个决策点工程实现中的关键分叉路口七要素讲的是系统由什么组成七个决策点讲的是每个环节你要做什么选择。这些决策点没有标准答案但有明显的优劣之分选错了会在后期付出很大代价。2.1 决策点一单 Agent 还是多 Agent这是架构层面的第一个分叉。单 Agent 是一个模型驱动所有工具和流程多 Agent 是多个专职 Agent 协作完成一个任务。单 Agent 的优势是简单、调试方便、状态管理集中。劣势是当任务复杂度上升时一个模型的上下文和注意力会成为瓶颈。多 Agent 的优势是每个 Agent 可以专注自己的领域用不同的模型和工具集整体能力上限更高。劣势是通信成本高、状态同步复杂、调试困难。我的判断标准是如果任务可以清晰地分成几个独立子领域且子领域之间的交互不频繁就用多 Agent否则先用单 Agent遇到瓶颈再拆。很多项目一上来就搞多 Agent结果大部分时间花在调试 Agent 之间的通信上核心业务逻辑反而没做好。如果决定用多 Agent还要决定协作模式。常见的有主管模式一个协调 Agent 分配任务给执行 Agent、流水线模式Agent 按顺序处理、辩论模式多个 Agent 对同一问题给出方案再择优。主管模式最常用也最容易控制。2.2 决策点二ReAct 还是 Plan-and-Execute这是循环机制的核心选择。ReAct 是推理-行动交替进行每一步都根据当前观察决定下一步。Plan-and-Execute 是先制定完整计划再执行。ReAct 的优点是灵活、适应性强适合环境不确定、需要频繁调整的场景。缺点是容易短视可能做出局部最优但全局次优的决策。Plan-and-Execute 的优点是全局视野好、执行效率高适合流程相对固定的场景。缺点是计划一旦制定就缺乏灵活性遇到意外情况需要重新规划。实际项目中我更多用的是混合方案外层用 Plan-and-Execute 做阶段划分内层用 ReAct 处理每个阶段内的具体步骤。这样既有全局方向又有局部灵活。纯 ReAct 适合探索性任务纯 Plan-and-Execute 适合流程化任务混合方案适合大多数实际业务场景。还有一个细节计划的可修改性。即使是 Plan-and-Execute也要允许在执行过程中修改计划。我通常会在每个阶段结束后加一个计划复审步骤让模型判断是否需要调整后续计划。2.3 决策点三工具调用的粒度怎么定工具粒度是很容易被低估的决策点。粒度太粗一个工具做太多事模型难以精确控制粒度太细工具数量爆炸模型选择困难。我的经验法则是一个工具只做一件事但这件事要有完整的业务语义。比如发送邮件是一个合适的粒度连接 SMTP 服务器和构造邮件内容和发送分成三个工具就太细了处理所有客户沟通又太粗。另一个考虑是参数复杂度。如果一个工具需要超过 5-6 个参数通常说明它承担了太多职责应该拆分。反过来如果一个工具没有任何参数可能它太简单了可以直接内置到流程里而不必做成工具。工具命名也很关键。名称要能自解释让模型一看就知道什么时候用。我习惯用动词名词的格式比如search_documents、create_task、send_notification避免用do_stuff这种模糊命名。2.4 决策点四状态存在哪里、怎么存状态管理是 Agent 工程中最容易出问题的环节。状态存哪里、怎么序列化、怎么恢复这些决策直接影响系统的可靠性和可调试性。状态存储有三个层次的选择。内存状态最快但易失适合单次会话内的临时状态。外部存储持久但慢适合跨会话的长期状态。混合方案是热状态在内存、冷状态定期持久化兼顾速度和可靠性。我实际项目中用的是混合方案当前执行状态放在内存对象里每完成一个步骤就序列化一份快照到外部存储。这样即使进程崩溃也能从最近的快照恢复不会丢失全部进度。状态的序列化格式也有讲究。JSON 最通用但体积大MessagePack 或 Protobuf 更紧凑但可读性差。如果状态需要人工排查JSON 的便利性通常值得那点体积代价。如果状态量很大且不需要人工看可以用更紧凑的格式。还有一个关键决策状态是集中管理还是分散管理。集中管理是一个全局状态对象所有组件读写同一份状态。分散管理是每个组件维护自己的状态通过消息传递同步。集中管理简单但容易成为瓶颈分散管理灵活但一致性难保证。我倾向于集中管理因为 Agent 系统的状态一致性比性能更重要。2.5 决策点五失败重试的策略怎么设计Agent 系统一定会遇到失败工具超时、模型输出格式错误、外部服务不可用。失败重试策略设计得好不好决定了系统是偶尔出错但能自愈还是一错就崩。重试策略要分错误类型来设计。瞬时错误网络抖动、临时限流适合立即重试通常重试 2-3 次就能成功。逻辑错误参数不对、格式不符不适合盲目重试应该先修正再重试。永久错误权限不足、资源不存在重试多少次都没用应该直接降级或上报。重试的退避策略也很重要。固定间隔重试在对方服务过载时会加剧问题指数退避每次重试间隔翻倍更合理。我通常用指数退避 随机抖动避免多个请求同时重试造成惊群。还有一个容易被忽略的点重试的上限和降级路径。重试不能无限进行要有明确的上限。达到上限后要有降级方案比如返回缓存结果、返回部分结果、或者明确告知用户当前无法完成。没有降级路径的重试就是在烧钱。2.6 决策点六上下文怎么组装和压缩上下文组装是每轮循环都要做的事但很多项目在这上面做得很粗糙导致模型表现不稳定。上下文组装的核心原则是把最相关的信息放在最显眼的位置。模型对开头和结尾的信息注意力最高中间部分容易被忽略。所以关键指令放开头当前任务状态放结尾参考信息放中间。上下文压缩是长对话场景的必备能力。压缩策略有几种滑动窗口是只保留最近 N 轮对话简单但会丢失早期信息。摘要压缩是把早期对话总结成一段话保留关键信息但会损失细节。检索压缩是把历史对话存起来需要时检索相关片段注入灵活但依赖检索质量。我实际用的是摘要 检索的混合方案近期对话保留原文中期对话做摘要远期对话存起来按需检索。这样在大多数场景下都能平衡信息完整性和上下文长度。2.7 决策点七怎么评估 Agent 的表现没有评估就没有优化。Agent 的评估比普通 LLM 应用更复杂因为它涉及多步骤、多工具、多轮交互。评估要分过程指标和结果指标。过程指标看每一步的质量工具选择准确率、参数正确率、循环效率完成任务的步数、失败恢复率。结果指标看最终产出任务完成率、用户满意度、端到端延迟、成本。我习惯建一个回归测试集把典型任务和边界情况都收录进去每次改动后跑一遍看指标有没有退化。这个测试集不需要很大几十个精心设计的用例就能覆盖大部分问题。关键是持续维护每次发现新的失败案例就加进去。评估的自动化程度也很重要。完全人工评估成本太高完全自动评估又可能不准。我的做法是用规则做初筛格式对不对、有没有明显错误用 LLM 做质量评分相关性、完整性、逻辑性人工只复核有争议的案例。3. 循环机制Agent 的心脏怎么跳循环机制是 Agent 工程中最核心也最容易出问题的部分。这一章把循环的设计、实现和调优讲透。3.1 一个最小可用的 Agent 循环长什么样先看一个最简化的循环结构用伪代码表示def agent_loop(user_input, max_iterations10): state init_state(user_input) for i in range(max_iterations): context build_context(state) response llm.invoke(context) action parse_action(response) if action.type finish: return action.content if action.type tool_call: result execute_tool(action.tool_name, action.params) state.add_observation(result) if no_progress(state, window3): return fallback_response(state) return max_iterations_response(state)这个循环包含了几个关键设计最大迭代次数限制、完成判断、工具执行、无进展检测。看起来简单但每个环节都有细节要处理。build_context决定了模型看到什么这是影响表现最大的环节。parse_action决定了模型输出怎么转成可执行动作格式解析的鲁棒性直接影响系统稳定性。no_progress检测防止死循环判断逻辑需要根据具体场景调整。3.2 循环终止怎么判断真的完成了循环终止判断是 Agent 循环中最微妙的环节。判断太早任务没完成就退出判断太晚浪费资源还可能出错。我用的终止条件组合是这样的终止条件触发逻辑适用场景模型显式完成模型输出 finish 动作正常完成最大迭代次数达到预设上限防止无限循环无进展检测连续 N 轮无有效动作防止原地打转错误累积连续 N 次工具调用失败防止无效重试超时总执行时间超限防止长时间占用模型显式完成是最理想的终止方式但不能完全信任。我遇到过模型在任务只完成一半时就输出完成的情况所以通常还会加一个完成度校验让模型在声明完成时同时输出一个完成度自评低于阈值时触发一次你确定完成了吗的确认。无进展检测的进展定义很关键。不能只看有没有工具调用而要看状态有没有实质变化。比如连续三轮都在搜索同样的关键词即使每轮都有工具调用也是无进展。我的做法是给状态加一个哈希每轮比较哈希是否变化连续多轮不变就判定无进展。3.3 循环中的错误恢复从失败中继续而不是重来Agent 执行过程中出错是常态关键是怎么从错误中恢复而不是整个重来。错误恢复的核心是状态快照 局部回滚。每完成一个成功的步骤就存一个快照出错时回滚到最近的成功快照然后尝试替代路径。这样不需要从头开始节省时间和成本。替代路径的生成有两种方式。一种是预定义备选每个工具配一个或多个备选工具主工具失败时自动尝试备选。另一种是动态生成把错误信息反馈给模型让模型决定怎么调整。我通常两者结合有预定义备选时优先用备选没有时让模型动态决策。错误恢复还要考虑错误传播。一个步骤失败可能导致后续步骤都无法执行这时候要判断是局部失败还是全局失败。局部失败可以绕过继续全局失败需要重新规划。判断依据是当前步骤是否是后续步骤的前置依赖。3.4 循环效率优化怎么让 Agent 少走弯路Agent 循环的效率直接影响成本和用户体验。同样一个任务优化好的循环可能 5 步完成没优化的可能 15 步还在打转。效率优化的第一个抓手是减少无效工具调用。常见做法是在工具调用前加一层预判根据当前状态判断这个工具调用是否可能有效无效的直接跳过。比如已经知道某个数据源不可用就不要再去调那个数据源的工具。第二个抓手是并行化。如果多个工具调用之间没有依赖关系可以并行执行。比如同时搜索多个数据源、同时查询多个 API。并行化能显著缩短总执行时间但要注意并发控制和错误处理。第三个抓手是缓存。相同或相似的查询结果可以缓存避免重复调用。缓存的关键是键的设计——键太细命中率低键太粗可能返回错误结果。我通常用工具名 归一化后的参数作为缓存键。第四个抓手是提前终止。当已经收集到足够信息可以回答用户问题时不必执行完所有计划步骤。这需要模型有能力判断信息是否充分我通常会在每步后加一个轻量的充分性检查。4. 工具调用Agent 的手脚怎么用工具调用是 Agent 从思考到行动的桥梁。这一章把工具调用的工程细节讲清楚。4.1 工具描述怎么写才能让模型选对工具描述是模型选择工具的唯一依据写得好不好直接决定选择准确率。一个好的工具描述包含四个部分功能说明这个工具做什么、使用场景什么时候该用、参数说明每个参数的含义和格式、返回说明返回什么格式的数据。功能说明要具体不要用模糊词汇。比如处理文档就不如从 PDF 文件中提取文本内容清晰。使用场景要写清楚边界比如当需要从非结构化文档中获取信息时使用不适用于结构化数据库查询。参数说明要标注类型、是否必填、取值范围。对于枚举类型把所有可能值列出来。对于字符串类型说明格式要求比如日期用 YYYY-MM-DD 格式。返回说明经常被忽略但很重要。模型需要知道工具返回什么格式才能正确解析和使用。如果返回可能为空要明确说明空值的情况。我踩过的一个坑是工具描述写得太简略模型经常在不适用的场景调用它或者在适用场景忘了调用。后来把描述扩充到包含正例和反例选择准确率明显提升。4.2 工具参数校验在模型和工具之间加一道防线模型生成的工具参数不一定合法直接传给工具可能导致各种问题。在中间加一道校验层是必要的。校验分格式校验和语义校验。格式校验检查参数类型、必填项、取值范围是否符合 schema。语义校验检查参数在业务上是否合理比如日期不能是过去的时间、ID 必须存在。校验失败时的处理策略很重要。不能简单报错让模型重试因为模型可能反复生成同样的错误参数。我的做法是校验失败时把具体的错误原因和修正建议一起返回给模型引导它生成正确的参数。比如参数 date 格式错误应为 YYYY-MM-DD 格式你提供的是 2024/01/01。对于高频错误可以在校验层做自动修正。比如日期格式错误自动转换、字符串前后空格自动去除、枚举值大小写自动归一化。这样能减少一轮往返提升效率。4.3 工具执行的安全边界什么能做什么不能做工具执行的安全边界是 Agent 上线前的必答题。没有安全边界的 Agent 就是一个随时可能闯祸的不定时炸弹。安全边界的设计原则是最小权限 显式授权 操作审计。最小权限是每个工具只给完成功能所需的最小权限。显式授权是敏感操作需要额外确认。操作审计是记录每一步操作便于追溯。具体到实现我会给每个工具打上风险等级标签低风险只读查询、中风险写入但可撤销、高风险不可逆操作。低风险工具可以直接执行中风险工具需要记录详细日志高风险工具需要二次确认或人工审批。还有一个容易忽略的点是工具的组合风险。单个工具可能都是安全的但组合起来可能产生风险。比如读取文件和发送邮件单独都安全但组合起来可能泄露敏感信息。所以安全边界不仅要看单个工具还要看工具调用的序列模式。4.4 工具返回结果的处理从原始数据到模型可用的信息工具返回的原始数据通常不能直接给模型用需要经过处理。处理包括格式转换、信息提取、长度控制。格式转换是把工具返回的格式转成模型容易理解的格式比如把 JSON 转成自然语言描述。信息提取是从大量返回数据中提取关键信息避免无关信息干扰模型。长度控制是限制返回信息的长度超长时做截断或摘要。我通常会在工具和模型之间加一个结果处理器每个工具配一个处理器。处理器负责把原始返回转成模型友好的格式。这样模型看到的是经过整理的信息而不是一堆原始数据。结果处理还要考虑错误信息的处理。工具执行失败时返回的错误信息要清晰、可操作。不要返回Error 500这种模型看不懂的信息而要返回服务暂时不可用建议稍后重试或使用备选数据源这种模型能据此决策的信息。5. 状态管理与上下文工程状态和上下文是 Agent 系统的内存管理得好不好直接影响系统的稳定性和能力上限。5.1 状态对象的设计结构化比什么都重要状态对象的设计原则是结构化、可序列化、可版本化。结构化意味着状态有明确的字段和类型不是一堆散乱的键值对。可序列化意味着状态能存能取支持持久化和恢复。可版本化意味着状态结构变化时能兼容旧数据。一个典型的状态对象包含这些字段会话标识区分不同会话、任务描述当前要完成什么、执行历史已经做了哪些步骤、当前步骤正在做什么、中间结果收集到的数据、错误记录遇到的失败、元信息时间戳、版本号等。状态更新要遵循单一写入原则每个字段只有一个组件负责写入其他组件只读。这样避免多组件同时写导致的状态不一致。如果确实需要多组件写要用锁或事务来保证一致性。状态的生命周期管理也很重要。会话结束后状态怎么处理是保留一段时间还是立即清理保留的话保留多久这些要根据业务需求和数据敏感度来定。涉及敏感信息的状态要及时清理普通状态可以保留一段时间用于分析和调试。5.2 上下文窗口的分配策略上下文窗口是有限资源怎么分配直接决定模型能看到什么。我的分配策略是固定比例 动态调整。固定比例是给各类信息分配基础配额比如系统指令 10%、任务描述 15%、执行历史 30%、当前观察 25%、工具定义 20%。动态调整是根据实际情况在基础配额上浮动比如工具多的时候工具定义占比上升历史长的时候历史占比上升。分配的核心原则是优先级排序。最不能丢的是系统指令和当前任务其次是当前观察再次是执行历史最后是工具定义。当空间不够时按这个优先级从低到高裁剪。裁剪策略也有讲究。执行历史裁剪时优先保留最近的和最关键的比如出错的步骤中间的成功步骤可以压缩成摘要。工具定义裁剪时优先保留当前任务可能用到的工具不相关的可以暂时移除。5.3 长对话的压缩与检索长对话场景下上下文压缩是必须的。压缩的目标是在有限空间里保留最多有用信息。压缩策略我分三级。一级压缩是去除冗余比如重复的确认信息、格式化的空行、无关的客套话。二级压缩是摘要把多轮对话总结成一段话保留关键决策和结论。三级压缩是检索把历史对话存到外部需要时检索相关片段。检索的质量取决于索引的设计。我通常用混合索引关键词索引保证精确匹配向量索引保证语义匹配。检索时两路都查合并结果后按相关性排序。压缩的触发时机也很关键。不能等到上下文满了才压缩那样会导致突然的信息丢失。我通常在上下文使用率达到 70% 时开始预警达到 85% 时触发压缩。这样有缓冲空间不会因为压缩导致模型表现突然下降。5.4 状态恢复崩溃后怎么接着干状态恢复是生产环境 Agent 的必备能力。没有状态恢复一次崩溃就丢失全部进度。恢复的基础是定期快照。每完成一个关键步骤就存一份状态快照快照包含恢复所需的所有信息。快照的存储要可靠通常用外部数据库而不是本地文件。恢复的流程是检测到崩溃 → 加载最近的快照 → 校验快照完整性 → 从快照点继续执行。校验很重要因为快照可能损坏或不完整直接用可能导致更严重的问题。恢复还要考虑幂等性。从快照恢复后重新执行的步骤可能之前已经执行过了。如果步骤不幂等比如发送邮件重复执行会造成问题。所以要么保证步骤幂等要么在快照里记录已执行的步骤恢复时跳过。6. 从原型到生产上线前必须过的几道关原型能跑通不代表能上线。这一章讲从原型到生产要补的课。6.1 并发场景下的 Agent 行为单用户场景下跑得好好的 Agent到了并发场景可能完全不是那么回事。并发带来的第一个问题是资源竞争。多个 Agent 实例同时调用同一个工具或访问同一份状态可能产生冲突。解决方式是资源隔离或加锁。资源隔离是每个实例用独立的资源加锁是共享资源但串行访问。我倾向于资源隔离因为加锁会降低并发度。第二个问题是成本控制。并发上去后LLM 调用成本可能指数级增长。需要设置全局配额和单用户配额防止个别用户或异常情况导致成本失控。配额可以按调用次数、token 数或金额来设。第三个问题是公平性。高并发时某些请求可能被饿死。需要设计调度策略保证每个请求都有机会被处理。简单的做法是队列 轮询复杂的可以用优先级队列。6.2 可观测性怎么知道 Agent 在干什么Agent 系统比普通应用更难调试因为它的行为是模型驱动的不完全可预测。可观测性是调试和优化的基础。可观测性要覆盖三个层面指标Metrics、日志Logs、追踪Traces。指标是聚合数据比如任务完成率、平均步数、工具调用分布。日志是详细记录每一步的输入输出都要记。追踪是跨步骤的关联把一次任务的所有步骤串起来看。我特别想强调追踪的重要性。Agent 的一次任务可能涉及几十次 LLM 调用和工具调用没有追踪根本理不清。追踪要记录每一步的输入、输出、耗时、状态变化最好能可视化展示。日志的结构化也很重要。不要用纯文本日志要用结构化格式比如 JSON方便查询和分析。关键字段包括时间戳、会话 ID、步骤序号、动作类型、输入摘要、输出摘要、耗时、错误信息。6.3 成本控制Agent 烧钱的地方在哪里Agent 的成本比普通 LLM 应用高得多因为一次任务可能调用几十次模型。成本控制是上线前必须解决的问题。成本主要来自三块模型调用、工具调用、存储。模型调用通常是大头尤其是用大模型做主推理时。工具调用看具体工具有些外部 API 按次收费。存储主要是状态和日志的存储成本。模型调用的优化有几个方向。模型分级是简单任务用轻量模型复杂任务用大模型。缓存是相同或相似的请求复用结果。批处理是把多个小请求合并成一个大请求。提前终止是信息足够时不再继续调用。我实际项目中用得最多的是模型分级 缓存。模型分级能省 30-50% 的成本缓存能省 20-40%。两者结合整体成本能降到原来的三分之一左右。6.4 灰度发布与回滚Agent 系统的行为不完全可预测直接全量上线风险很大。灰度发布是降低风险的有效手段。灰度发布的策略是先小流量验证逐步扩大流量同时监控关键指标。指标正常就继续扩大指标异常就暂停或回滚。回滚能力是灰度发布的前提。回滚要快、要干净。快是指发现问题后能立即切回旧版本。干净是指回滚后不留下脏数据或中间状态。我通常用版本化部署 流量切换来实现快速回滚新旧版本同时运行通过流量比例控制。灰度期间要重点监控的指标包括任务完成率、平均步数、错误率、延迟、成本。任何一个指标明显退化都要警惕。7. 几个实际项目中的经验教训最后分享几个我在实际项目中踩过的坑和总结的经验这些是文档里不会写的。7.1 不要过早优化循环步数刚开始做 Agent 时我总想着怎么让循环步数最少。后来发现步数少不一定好。有些任务需要多步探索才能做对强行压缩步数会导致质量下降。正确的做法是先保证质量再优化效率。先让 Agent 能稳定完成任务哪怕步数多。然后再分析哪些步骤是冗余的有针对性地优化。优化的目标是消除无效步骤而不是减少所有步骤。7.2 工具不是越多越好工具数量增加会带来两个问题模型选择困难、维护成本上升。我见过一个项目有 50 多个工具模型选择准确率不到 60%。我的建议是工具数量控制在 15 个以内超过就考虑分组或合并。分组是把工具按领域分成几组模型先选组再选工具。合并是把功能相近的工具合并成一个通过参数区分具体行为。7.3 状态设计要留扩展余地状态对象一旦上线就很难改因为改了要兼容旧数据。所以设计时要留足扩展余地。我的做法是核心字段用强类型扩展字段用元数据字典。核心字段是必须的、稳定的元数据字典是灵活的、可扩展的。这样新增信息时可以放元数据字典不用改核心结构。7.4 评估要趁早做很多项目到快上线才想起来做评估这时候发现问题已经很难改了。评估应该从项目第一天就开始。早期评估不需要很复杂几个典型用例 人工检查就够了。随着项目推进逐步扩充用例、增加自动化检查。到上线时评估体系已经比较完善了。7.5 人工兜底不是失败有些团队觉得 Agent 需要人工兜底是能力不足的表现想尽办法追求全自动。我的看法是人工兜底是负责任的设计不是失败。Agent 再强也有边界遇到边界情况时人工介入是合理的。关键是设计好交接机制什么时候触发人工、交接时传递哪些信息、人工处理后怎么回到自动流程。这些设计好了人机协作的效率比纯自动或纯人工都高。我在实际项目中的体会是Agent 工程最难的不是某个技术点而是整体的系统设计和权衡。七要素和七个决策点提供了一个思考框架但具体怎么选还要结合业务场景、团队能力和资源约束。没有银弹只有适合当前情况的方案。