解构 AI Agent从七要素到七个决策点1. 先搞清楚我们到底在聊什么AI Agent 这个概念在过去两年里已经被聊得够多了但大多数文章要么停留在“Agent 是什么”的科普层面要么一头扎进某个框架的 API 文档里出不来。真正做工程的人需要的其实是中间那块——把 Agent 拆开看清楚每个零件是什么、为什么需要它、以及落地时每个决策点到底在权衡什么。我自己在多个 Agent 项目里踩过坑之后慢慢形成了一个习惯先不看代码先把整个系统用自己的话讲清楚。如果你没法用三句话讲清楚你的 Agent 在干什么、依赖什么、在什么条件下会失效那代码写得再漂亮上线也是迟早要出事的。这篇文章要做的就是把 AI Agent 的工程实现拆成两个层面来讲先是七要素解决“一个 Agent 系统里必须有什么”的问题再是七个决策点解决“每个要素落地时你该怎么选”的问题。七要素帮你看清结构七个决策点帮你在真实工程约束下做取舍。两者加在一起基本就是一个可落地的 Agent 系统的完整蓝图。适合谁看想从“调 API 写 demo”跨越到“做真正能用的 Agent 系统”的开发者以及需要在团队里设计 Agent 方案的架构师。我不讲花里胡哨的概念只讲工程上真正需要你拍板的事情。2. Agent 的七要素解剖一个最小可用系统2.1 为什么是“七要素”很多人喜欢把 Agent 描述得很玄什么“自主性”“智能体”“模拟人类”这些东西对写代码没有直接帮助。我从工程结构的角度把 Agent 拆成七个必须明确的要素任务、模型、上下文、工具、记忆、规划、行动。注意这七个不是框架里硬造出来的概念而是每一个 Agent 系统运行时必然涉及的部分。哪怕你只是写了一个while True循环调大模型你也在隐式处理这七个要素。只是处理得好不好、有没有显式设计的问题。我之前带过一个项目初期就是“一个大循环 一堆 if else”结果需求一变就崩。后来把所有逻辑按这七个要素重新整理了一遍代码量反而减少了因为每个部分的边界清楚了改起来不再互相牵连。2.2 七要素逐个拆解任务Task这是整个 Agent 存在的理由。任务定义包含两层一层是用户可见的目标描述另一层是系统内部的成功标准。很多人只定义了前者结果 Agent 干活干得很嗨但产出的东西根本不是用户要的。工程上任务要素要输出的是一份可校验的目标说明最好能拆成几个可自动验证的子目标。模型Model模型的选型直接影响 Agent 的天花板和地板。地板指的是稳定性天花板指的是能力上限。你要关注的不只是“哪个模型聪明”还有“哪个模型在你可以接受的成本下能稳定地遵循复杂指令”。后面决策点部分我会展开讲。上下文Context上下文是模型每次调用时看到的所有信息包括用户输入、历史对话、工具返回、系统提示词。上下文管理是所有 Agent 工程里最脏最累的活因为它直接和 token 成本挂钩又直接影响模型的理解质量。上下文不是越多越好——信息密度比信息总量更重要。工具Tools工具是 Agent 与外部世界交互的接口。没有工具的 Agent 只能“说”有了工具的 Agent 才能“做”。工具可以是 API 调用、代码执行器、数据库查询、文件读写甚至是另一个 Agent。工具定义的核心是接口契约也就是把工具的能力描述清楚让模型能自主决定何时调用哪个工具。记忆Memory记忆解决的是“跨轮次信息保持”的问题。短期记忆对应当前任务中的上下文窗口长期记忆则把重要信息持久化供后续任务使用。工程上最常犯的错误是把所有东西都塞进记忆结果重要的信息被淹没在不重要的噪声里。规划Planning规划是 Agent 把大目标拆成可执行步骤的能力。简单的 Agent 可以不显式规划靠模型一步到位复杂的任务必须拆解。规划有两种实现路线一种靠模型自身推理CoT、ReAct 这类另一种靠外部流程引擎工作流、状态机。路线选择本身就是一个重要决策。行动Action行动是规划的执行环节。它把“决定要做的事”变成“实际产生效果的操作”。行动不只有工具调用还包括向用户提问澄清、请求确认、报告中间状态——这些“软行动”往往比硬操作更能体现 Agent 的可用性。我在实际项目中最喜欢用一句话来检查这七个要素是否都到位从“用户给了一个任务”到“系统交付了一个结果”中间每一次状态变化能不能在这七个要素里找到对应位置能找到说明结构清晰找不到说明有隐藏逻辑在裸奔。2.3 要素之间的协作关系七个要素不是孤立的它们之间存在固定的数据流向任务定义决定了模型需要理解什么模型在上下文的辅助下进行规划规划产生行动序列行动调用工具获取外部反馈反馈写入记忆和上下文然后循环继续。我习惯把这个流程画成一个简单循环但真实系统的复杂点在于每一次循环都是动态的任务可能会细化上下文会更新记忆会写入新内容工具的返回结果会改变下一步计划。所以工程实现的重心不是让每个要素各自做到最优而是让它们之间的协作足够顺滑、足够可观测。这也是为什么我不推荐一上来就上重型框架的原因吧。框架往往把协作方式写死了你先用七要素想清楚自己的 Agent 需要什么样的协作模式再选框架才是正路。3. 核心决策点一与二模型选型和上下文管理3.1 模型选型不要只盯着排行榜模型选型是七个决策点里最容易做也最容易被反噬的一个。容易是因为看起来只需要对比几个榜单分数容易出问题是因为榜单分数和你的实际场景之间隔着巨大的鸿沟。我在项目里总结出一个四步选型法第一步定义你的任务类型和难度基准找 20 到 50 条真实样本第二步用这些样本在候选模型上跑一轮粗测对比指令遵循能力和格式稳定性第三步把模型接进一个带工具的测试环境跑端到端的任务链路这一步最关键因为模型在有多工具可选时的行为和单轮对话完完全全是两回事第四步算成本账包括 token 单价、延迟容忍度、并发量预估综合出一个性价比结论。这里有个很实在的经验复杂推理任务上头部模型的优势极其明显但大部分业务场景根本不涉及复杂推理。大部分 Agent 任务是把流程走对、把格式输出对、把工具调用参数填对这类任务上中等模型微调或调好提示词效果完全够用成本却能省下一大截。3.2 上下文管理token 预算的科学分配上下文管理直接决定了你的成本上限和模型的实际发挥。我见过太多 Agent 把上下文塞到接近窗口上限模型开始“胡言乱语”——不是模型变笨了是有效信息被稀释了。上下文管理的第一原则是分层。我把上下文分成三层核心层系统提示词和任务定义、工作层当前任务的输入和中间结果、参考层长期记忆和检索到的相关资料。每次调用前三层都要做一次裁剪和刷新。具体到 token 预算我推荐一个经验比例系统提示词控制在总预算的 5% 到 10%当前任务信息占 40% 到 60%检索参考信息占 20% 到 30%预留 10% 给模型的输出和工具返回。这个比例不是死的但可以作为起始配置。有一项基础工作必须做扎实——token 估算。模型不同tokenizer 不同同一个单词的 token 数可能差三倍。工程上建议直接用tiktoken这类工具库做精确估算各模型对应编码器不同比如cl100k_base对应一批旧模型o200k_base对应更新的模型系列而不是靠“大概多少字”来猜。粗算的话中文大约一个字对应 1.5 到 2 个 token英文大约一个词对应 1.2 到 1.5 个 token但这只能用于快速估算上线前建议用真实文本跑一轮精确计算。另外上下文管理绝不只是“截断”。真正有效的做法是“压缩 选择性保留”。压缩是指把工具返回的大段文本做成摘要选择性保留是指只保留和当前步骤直接相关的历史片段。这两件事做扎实了Agent 的稳定性会有肉眼可见的提升。4. 核心决策点三与四记忆机制和工具架构4.1 记忆机制短期记忆和长期记忆的工程分工记忆机制最容易踩的坑是把所有历史对话一股脑存下来然后每次请求全量塞进上下文。这样做短期看起来省事长期必然爆炸——token 成本暴涨响应变慢模型质量还会因为上下文过载而下降。我先说说短期记忆的工程实现。短期记忆本质上是上下文窗口中直接保留的信息工程实现的关键是“窗口管理”。做法是给每条消息打上类型标签和时间戳每次构造上下文时按策略筛选系统提示词永远在最近的 N 轮对话保留更早的对话按相关性召回而不是按时间顺序全留。这里 N 要实测我一般从 6 到 10 轮起步结合模型窗口大小和任务复杂度调整。长期记忆的工程实现则完全不同。它更像一个检索系统写入时要提取关键实体比如用户偏好、任务状态、重要结论存储时用向量库或者结构化数据库读取时靠检索而不是靠扫描。我的建议是不要一上来就上向量数据库很多场景用带标签的 JSON 文件或者 SQLite 就够用了等检索量真的上来了再迁移到专门的向量库。有一个容易被忽略的点记忆是要有写入策略的。不是每一轮的对话都值得写入长期记忆。我通常用一个简单的规则触发写入任务完成时、检测到明确偏好时、出现重复失败时、用户给出显式修正时。这样长期记忆里沉淀的都是真正有价值的信息而不是流水账。4.2 工具架构从“接口调用”到“能力编目”工具架构决定了 Agent 能做什么、能做多好。工具设计不是把 API 包装一下就完事核心工作是“能力描述”。模型是靠工具的描述来决定什么时候调用、怎么调用、传什么参数的描述写得含糊工具再强也用不上。我建议把每个工具的定义组织成一个五件套工具名称必须唯一且语义清晰、功能描述用一句话说明这个工具能做什么、适合什么场景写清楚边界条件、参数说明每个参数的名称、类型、必填与否、取值范围、含义解释、返回值说明返回结果的格式和语义、使用约束什么情况下不应该调用这个工具这个特别重要能避免很多误调用。参数设计上建议用 JSON Schema 来约束结构这样一方面模型生成的参数更容易规范化校验另一方面后续如果要让 Agent 之间互相调用工具接口契约也足够清晰。这里有个实践例子。社交平台自动发消息这个场景工具表面上就是一个“发送消息”的 API但真正做工程时你至少要拆出三个工具内容生成、合规检查、定时发送。内容生成负责按用户模板产出消息草稿合规检查负责在发出去之前拦下明显违规的内容比如涉敏词、营销话术定时发送负责真正把消息发出去并返回发送结果。三个工具各有独立的描述和参数Agent 就能在中间插入人工确认环节——这个环节能挡住一大半事故。工具设计的另一个关键点是“尽量原子化”。一个工具只做一件事参数越少越好。比如“获取用户信息”和“更新用户信息”一定要拆成两个工具不要做成“用户信息操作”然后靠参数区分模型很容易搞混。原子化的工具组合起来反而更灵活。4.3 工具调用的容错设计工具调用失败是 Agent 工程里最频繁的异常场景而且失败方式五花八门参数校验不过、API 超时、返回数据格式和描述不一致、权限不足、外部依赖挂了。工程上必须有配套的容错机制。我在项目里给每个工具调用配置了三条规则第一统一超时时间外部 API 调用我一般设 10 秒超过就报错不让 Agent 干等第二失败后模型要能看到失败原因原因必须结构化错误码 可读信息而不是一段堆栈或者一个大字符串第三自动重试策略幂等操作可以重试一到两次非幂等操作必须停下来问用户或换方案。一个常见的问题是工具返回的原始结果经常内容庞大直接塞回上下文会浪费大量 token还会让模型被噪声干扰。我的做法是给工具返回值做一个“摘要层”返回之后先截断或者摘要把核心信息提炼出来再放回上下文。这个摘要层可以用规则写也可以用一个小模型调用根据性能要求来选。5. 核心决策点五与六规划模式和行动执行策略5.1 规划模式动态自由规划和固定流程的取舍规划模式是 Agent 工程里最容易“两头踩坑”的地方。一头是让模型完全自由地规划结果流程不稳定同一个任务每次走法都不一样排查问题像大海捞针另一头是全部用固定工作流写死稳定是稳定了但任务一变化就完全不适应。我先给一个判断标准如果你的任务步骤在绝大多数情况下是固定的就优先用固定流程。固定流程意味着你可以在每一步之间做精细化的校验、容错、人工确认这种稳定性在真实业务里极其值钱。自由规划适合探索性强的场景——比如信息收集、方案生成、研究分析这类目标明确但路径不固定的任务。自由规划模式下模型会被给出任务目标和可用工具列表由模型自己决定先做什么、再做什么。这种模式的工程关键在两点一是给模型足够的“中间结果沉淀”机制每完成一步就把结果写入一个共享状态区方便后续步骤引用二是给模型一个“停止条件”让它知道什么时候算完成任务否则 Agent 可能会无限循环下去。我建议采用一个中间态半自由规划。主线步骤用流程来定但每个步骤内部的执行方式允许模型灵活选择。比如主流程是“收集信息 → 分析 → 生成报告”但第一步收集什么、用哪个工具模型可以自己决定。这种模式兼顾了稳定性和灵活性是大多数业务场景的最优解。5.2 动态路由一个被低估的工程手法动态路由是我在 Agent 工程里很推荐的一套实践。它本质上是把“选哪条路径做”这件事交给模型但不是靠模型完全自由发挥而是给模型提供有限的几个选项让它选一个。举个实际的例子用户消息进来之后Agent 先判断这个消息类型——是想查询已有数据还是想触发一个新的操作还是对之前的执行结果有疑问。每类消息走不同的处理分支分支之间的行为差异非常大。如果没有动态路由把所有逻辑塞进同一个提示词里模型大概率会在分支边界处犯糊涂。动态路由的实现在技术上很简单就是先让模型输出一个分类结果然后基于这个结果走不同的后续逻辑。难的是设计“分类维度”——维度不能太细否则模型分不准也不能太粗否则分了等于没分。我的经验是两个原则分类维度之间要互斥每个分类对应一套明确的后续处理策略。如果模型分类之后你还要在分支里再做一次判断那说明分类维度设计得有问题。Rust 语言在 Agent 工程中的应用最近讨论很多这也是一个热门搜索词。从我实测过的几个项目来看Rust 的强项是并发和资源管控。Agent 系统一旦进入多任务并行同时跑多个 Agent、同时处理多个对话Rust 的性价比会非常明显占内存稳定、行为可控。如果你用 Python 做原型验证并发上来了再转 Rust 做核心引擎这个路线比较稳。需要注意Rust 的生态尤其是 AI 相关的还是要重造不少轮子团队技术储备不足的话建议只在性能瓶颈层用 Rust业务逻辑层继续用你熟悉的主流语言。5.3 行动执行让 Agent 会“好好做事”而不只是“能做事”行动执行是把规划变成现实的关键环节。我把行动分成硬行动和软行动两类。硬行动就是实际产生影响的操作——调 API、写文件、发消息软行动是交互性操作——向用户确认、提出澄清问题、报告执行进度。很多 Agent 工程只实现了硬行动结果用户体验很差。比如用户让 Agent 做一个数据分析Agent 闷头跑半天最后给一个结果用户根本不知道中间发生了什么、依据是什么。如果 Agent 在关键节点先输出“我准备按这几个维度来分析确认一下”用户的信任感会完全不同。行动执行里有一个原则我觉得值得当成铁律来执行高风险操作前必须确认。什么是高风险给外部系统发消息、删除数据、花真金白银的操作统统算高风险。确认的方式可以简单粗暴——在代码里加一个人工审批步骤Agent 生成操作请求人点确认再真正执行。这个步骤看似拖慢了效率实际是保命设计。行动执行还有一个被忽视的细节记录行动的“因果链”。每次行动执行之后把导致这次行动的原因、行动本身、行动结果,三者一起记入日志。因果链是排查问题和做评估时的基础素材。没有因果链Agent 出错了你只能看到模型答了一段话完全没法定位是规划错了还是理解错了。6. 核心决策点七可观测性、评估体系和安全边界6.1 可观测性设计原则可观测性排在决策点里但它在优先级上绝对不低。Agent 系统比传统软件难排查得多因为它的行为不是确定的——同一个输入不同时刻跑可能就是不同结果。这种情况下没有完整的观测数据你连“问题是偶发还是必现”都判断不了。我在项目里强制要求四类日志齐全决策日志模型每一步在做什么、为什么这么做至少要记录输入的关键信息和输出的决策文案、调用日志模型每次调用的完整参数、token 消耗、耗时、工具日志每个工具调用的入参、返回码、返回摘要、耗时、状态快照每轮循环完成后Agent 内部核心状态变量的值。一个实践技巧是给整个 Agent 运行加一个 trace_id从用户请求进来一直到最终返回所有日志都带上这个 ID。排查问题的时候拿着一条日志就能拉出整条链路效率提升非常明显。市面上主流的链路追踪工具OpenTelemetry直接支持这种玩法集成成本不高。观测数据的价值不止在排查问题。我经常拿决策日志去反向分析模型的失败模式——是任务误解、工具选错、还是步骤遗漏分析结果会直接反馈到提示词和流程设计上。这是一个持续的迭代闭环没有日志支撑这个闭环根本转不起来。6.2 评估体系不用拍脑袋判断 Agent“变好了”Agent 好不好不能靠感觉。我建议每个 Agent 项目从第一天就建立评估集一批有标准答案或可校验结果的任务样本定期用更新后的配置跑一遍看正确率和稳定性有没有下降。评估集怎么建最简单的起点是挑 30 到 50 个真实用户请求附上期望行为和成功标准。成功标准不一定是“完全一致”很多 Agent 任务没有唯一答案那就要用可校验的指标来定义比如“最终结果里是否包含了指定的三个必填字段”“是否在 X 步以内完成”“是否误调用了不该调的工具”。有了评估集后面的迭代就有了抓手。每次改提示词、换模型、调工具描述先跑评估集对比分数再决定是否上线。没有这个机制你会发现改来改去全在碰运气。这里要特别提醒一点Agent 系统的回归测试不是可选项是必需品。因为模型是概率性的今天用得好好的明天换个模型版本、或者提示词改一句话可能很多原本通过的用例就不过了。你每周都要跑一遍回归才能及时发现问题。6.3 安全边界与故障止损Agent 的安全边界落到工程上就是一句话给 Agent 的能力画上明确的圈圈外的事情它碰都不能碰。具体来说有三道防线。第一道是工具层Agent 能接触哪些工具、不能接触哪些工具在工具注册时就写死。敏感操作发消息、改数据、花销类操作一律单独加审批步骤。第二道是模型层系统提示词里写入禁止行为这个防线是最弱的因为提示词可以被绕过所以只能当辅助。第三道是执行层真实执行前再加一次独立的规则校验比如发送内容里包含禁止词就强制拦截。三道防线缺一不可。故障止损是安全边界触发后的补救动作。AGENT 出错的代价可能是发错消息、删错数据、产生错误订单。要提前设计好止损方案消息类操作要有撤回或二次确认机制数据操作要有备份和回滚能力外部系统调用要有熔断开关。熔断开关听起来不高级但它能在一次事故中替你挡住多几百倍的损失。我亲身经历过的教训有一个 Agent 在一次测试中把“清空测试数据”的工具描述理解错了真的发起了清空操作。幸好数据有备份恢复只花了 20 分钟但从那以后凡是删除类操作一律改成“先生成删除计划 → 用户确认 → 再执行”。这类设计不是过度谨慎而是见过的坑多了之后建立的基本修养。7. 七个决策点与七要素的映射关系7.1 映射总览把七个决策点和七要素放在一起看你会发现决策点不是孤立的它们最终都落到要素的实现上。我把这层关系整理成一张表决策点直接影响要素核心决策内容模型选型模型、规划能力上限和成本下限之间的取舍上下文管理上下文、记忆信息密度与 token 成本的控制记忆机制记忆短期窗口与长期存储的分工工具架构工具、行动能力边界与接口契约设计规划模式规划固定流程与自由规划的平衡行动执行策略行动、工具交互式行动与安全确认机制观测与安全体系所有要素全链路的观测与红线管控这张表的价值在于做方案评审的时候可以拿“决策点 — 要素”这个二维关系来检查看有没有漏掉的地方。比如你的工具架构设计得很细但行动执行策略里没有确认机制那安全性就缺了一块。7.2 不同场景的决策侧重点不同应用场景对七个决策点的侧重完全不同如果你在手头有具体项目要推进值得先判断一下自己的场景属于哪一类再决定深浅与先后。工具调用型比如让 Agent 自动操作业务系统这一类的核心是工具架构和行动执行策略。Agent 的价值不在于多会聊天而在于工具调用有多准、多稳。工具描述要写得极其清楚高风险操作必须有确认机制。模型选型可以排在后面中等模型一般就能胜任。知识密集型比如企业知识库问答和报告生成类这类场景的胜负手在上下文管理和记忆机制。很多失败案例不是模型不够聪明而是关键信息没有出现在上下文里。检索质量、上下文组织方式这些细节有时候比换一个大模型作用更直接。流程编排型比如跨系统的多步骤事务处理这类场景里规划模式是核心。每一步的输入输出都要有明确校验标准失败分支要有兜底。模型幻觉在这里比较致命因为一步理解错了后面全盘皆错。建议尽量让每步的输入输出收敛不要给模型太多自由发挥空间。实时交互型比如客服、助手类产品这类对行动执行和可观测性要求较高因为用户会盯着 Agent 的每一步表现。交互节奏什么时候问、什么时候做比单步正确率更影响体验。7.3 从决策点到参考架构把决策点落成可执行的方案后一个标准的 Agent 参考架构大致如下入口层接收任务做意图分类动态路由规划层根据任务类型选择固定工作流或自由规划上下文组装层从短期记忆、长期记忆、工具返回中筛选和裁剪信息组装成每次调用的输入执行层调用模型 → 生成决策 → 调用工具 → 校验结果 → 记录日志记忆写入层按策略更新短期记忆和长期记忆观测与安全层全链路日志、trace_id、风险拦截、熔断开关这个架构不绑定任何具体的框架你可以用 LangChain 这类现成框架来搭也可以自己写核心逻辑。用框架的好处是省力坏处是很多细节被隐藏了——而 Agent 系统的坑恰恰都在细节里。我的建议是先用这个架构自己跑通一条最简单的链路再把通用逻辑抽象出来替换或增强框架的默认行为。8. 实操复盘一个 Agent 的完整落地过程8.1 需求与选型阶段拿一个实际做过的项目举例——做一个支持自然语言查询内部数据并自动生成报表的 Agent。需求听起来很简单但第一个决策点就卡住了模型选哪个。当时的候选有两个一个强模型一个中等模型。我用 50 条真实查询做了对比测试结果很有意思简单的查询两模型表现拉不开差距但涉及多表关联和复杂条件查询时强模型明显胜出。最后选了“强模型兜底 中等模型分流”的混合路线简单查询走中等模型复杂查询走强模型。这个方案比全量用强模型省了近一半成本效果几乎没有差别。这个例子说明一个方法论不要凭感觉选模型拿自己的真实任务跑一轮对比选型的效率会高很多。8.2 开发与调试阶段开发阶段的第一个坎是工具描述。我们本来只提供了两个工具查数据和生成报表。跑起来发现 Agent 经常搞混——它会在生成报表时再查一次数据而不是直接使用已经查到的结果。问题就出在工具描述没有体现数据传递的依赖关系。改成三个工具后好多了查询数据、基于上次查询结果生成报表、保存报表。每个工具的输入参数都注明依赖上一次的查询结果。这个调整在代码上只改了几行描述但在效果上是质的提升。调试阶段的另一个教训是上下文长度。早期为了“让 Agent 看得全”把查询结果全量塞进上下文结果模型经常被大量无关列干扰生成的报表结构反而更差。后来加了一个结果摘要层大结果集只保留 schema 和行数统计模型的表现稳定多了。8.3 上线后的迭代上线运行三周后我们做了一次日志复盘发现两类典型失败一类是用户问题本身存在歧义比如“最近的数据”到底指多长时间范围Agent 闷头做了选择但没有主动确认另一类是面对之前从未遇到过的提问模式时模型给了不完整的结果。针对第一类问题我们在行动执行策略里增加了一个“澄清优先”的软行动当检测到问题里有模糊的时间或范围描述时Agent 必须先追问确认再执行查询。针对第二类问题我们把失败案例加入评估集然后优化了系统提示词里对“不清楚时如何应对”的指导——让模型宁可如实说“这个问题我无法用现有工具回答”也不要硬编一个答案。这个迭代过程让我更确信Agent 不是“写完就能跑”的东西它是一场持续的调优。你投入最多时间的地方往往不是模型选型和功能开发而是让错误率一步步降下来的那些细节打磨。8.4 踩过的那些坑总结几条最疼的绕了一圈把实战中反复遇到、教训最深的坑集中列一下第一坑工具描述写得太简单。你以为模型“应该能理解”的事模型真的不一定理解。工具描述里必须显式写出使用条件、边界、依赖、禁忌。宁可啰嗦一点也要把行为预期写清楚。这一条能解决一半的误调用问题。第二坑上下文里噪声太多。信息越多模型越糊涂是真的。上下文要做减法保留和当前步骤直接相关的其余的一律不进模型。做减法的速度要快因为每一步循环都要做。第三坑没有元数据和 trace_id。一开始偷懒没做全链路日志出问题时排查成本高得让人崩溃。后来补上之后很多问题从“大海捞针”变成“一条 SQL 拉出来”。观测体系越早建越好后面补永远更贵。第四坑没有从第一天就定义成功标准。在需求阶段多花一点时间把“什么算成功”写清楚后面能省掉大量“我觉得这样不行”的扯皮。成功的定义不是流程文档而是可执行的校验规则。第五坑重规划、轻执行。很多团队把精力倾注在让 Agent 会做更复杂的规划上却忽略了行动执行时最基本的容错和安全。再聪明的规划碰上执行层的低级故障结果也是归零。先把执行这条线打结实再去想更聪明的规划方式。9. 从七要素到七个决策点我的最后一句话说了这么多如果把所有方法论压缩成一句我在实操中反复验证的话那就是Agent 工程不是“选个聪明模型”的问题而是“把系统拆到每个部分都可控、可观测、可干预”的问题。七要素帮你看清结构七个决策点帮你在约束下做取舍。你不需要在所有环节一步到位但你需要知道每个环节为什么存在、怎么判断好坏、从哪里入手优化。我自己现在的做法是每接一个新的 Agent 项目先花半天把七要素梳理一遍再花半天把七个决策点过一遍输出一份两页纸的设计说明。这两页纸看起来简单但它能挡住后续开发中 80% 的方向性返工。这篇内容讲的是工程方法但底层其实是工程心态——对不确定性的敬畏对可观测性的执念以及永远在“模型很聪明”和“模型随时会犯错”之间保持清醒。把这种心态带进你做的每一个 Agent 项目你会少踩很多坑。