1. 为什么“七要素”和“七个决策点”是理解 Agent 的两把钥匙很多人第一次接触 AI Agent 这个概念时脑子里浮现的画面是科幻电影里那种能自己思考、自己行动的智能体。但真到了动手做工程实现的时候你会发现事情完全不是那么回事。你面对的是一个 LLM、一堆 API、一个循环控制逻辑以及无数个需要你拍板的细节。Agent 这个词被用得太泛了泛到几乎失去了工程指导意义。我做了几个 Agent 项目之后逐渐意识到一个事实Agent 的工程实现本质上是在回答两类问题——它由哪些部件构成以及在运行过程中需要做哪些关键决策。前者是静态的结构拆解后者是动态的流程控制。把这两件事想清楚了Agent 就不再是一个模糊的概念而是一个可以逐步搭建、逐步调试的系统。这篇文章要聊的“七要素”和“七个决策点”就是我在实际项目中反复验证过的一套拆解框架。七要素回答的是“一个 Agent 最少需要哪些东西才能跑起来”七个决策点回答的是“在它跑起来之后每一步需要做什么判断”。这两者结合起来基本上覆盖了从零搭建一个 Agent 的核心工程问题。适合谁看如果你已经了解 LLM 的基本用法知道什么是 prompt、什么是 API 调用但还没真正动手搭过一个完整的 Agent那这篇文章就是写给你的。如果你已经搭过简单的 Agent但总觉得哪里不对劲、行为不可控、调试起来很痛苦那这篇文章也能帮你找到一些结构性的原因。提示本文讨论的 Agent 指的是基于 LLM 的软件系统不涉及机器人、具身智能等硬件方向。所有内容都围绕软件工程层面的实现展开。2. 七要素拆解一个 Agent 从概念到可运行的最小集合2.1 模型层不只是选一个 LLM 那么简单模型层是 Agent 的“大脑”但选模型这件事远比大多数人想象的复杂。很多人上来就问“哪个模型最强”这个问题本身就问错了。你需要问的是我的任务需要模型具备哪些能力这些能力对应的成本是多少延迟能接受多少。我拿一个实际场景举例。假设你要做一个自动处理客服工单的 Agent它需要理解用户描述、查询知识库、生成回复、判断是否需要转人工。这个任务对模型的要求是中文理解要过关、指令遵循要稳定、输出格式要可控。至于创意写作能力、代码生成能力完全不需要。这种情况下选一个中等规模的模型就够了没必要上最大的那个。但如果你做的是一个代码审查 Agent需要理解复杂的代码逻辑、发现潜在的边界条件问题那模型能力就是核心瓶颈这时候在模型上省钱就是给自己找麻烦。模型层还有一个容易被忽略的点输出格式的稳定性。Agent 的后续流程往往依赖模型输出的结构化数据比如 JSON如果模型经常输出格式不对的内容你的整个流程就会频繁中断。实测下来不同模型在格式遵循上的表现差异非常大有些模型即使你给了明确的格式要求它还是会“自由发挥”。这个问题在选型阶段就一定要验证不要等到开发到一半才发现。另外模型层还需要考虑的一个工程问题是是否需要多模型协作。有些 Agent 架构会用一个便宜的小模型做意图分类和路由用一个大模型做核心推理。这种设计在成本敏感的场景下很常见但也会带来额外的复杂度——你需要管理多个模型的调用、处理它们之间的衔接问题。2.2 工具层Agent 与外部世界交互的唯一通道工具层是 Agent 的“手脚”。没有工具Agent 就只是一个聊天机器人只能基于训练数据回答问题。有了工具它才能查数据库、调 API、读写文件、发送请求。工具的设计有几个核心原则。第一工具的描述要足够清晰。模型是根据工具的名称和描述来决定是否调用、怎么调用的。如果你的工具描述含糊不清模型就会用错工具或者传错参数。我见过一个案例开发者定义了一个叫search的工具描述写的是“搜索信息”结果模型在任何需要查找信息的时候都调这个工具包括本该调数据库查询的场景。后来把描述改成“在互联网上搜索公开信息适用于查找新闻、百科等通用知识不适用于查询内部数据库”问题就解决了。第二工具的参数设计要尽量简单。每多一个参数模型传错的概率就增加一分。如果一个工具需要五个以上的参数你就该考虑是不是可以拆成多个更简单的工具或者把一些参数设成有默认值的可选参数。第三工具的错误处理要完善。模型调用工具时传错参数是常态工具本身要能返回清晰的错误信息让模型知道哪里错了、怎么改。如果工具直接抛一个异常然后整个流程崩溃那用户体验就会非常差。# 一个工具定义的示例伪代码 tool_definition { name: query_order, description: 根据订单号查询订单状态和详情。仅在用户提供了明确的订单号时使用。, parameters: { order_id: { type: string, description: 订单号格式为纯数字通常为12位, required: True } } }工具层还有一个工程上的关键决策工具的粒度。粒度太粗模型不好控制粒度太细模型需要调用的次数太多延迟和成本都会上升。我的经验是一个工具最好对应一个完整的业务操作而不是一个技术步骤。比如“查询订单并返回格式化结果”是一个合理的工具粒度而“连接数据库”和“执行 SQL”拆成两个工具就太细了。2.3 记忆层让 Agent 不再“金鱼脑”记忆层是很多初学者最容易忽略的部分。没有记忆的 Agent每次对话都是全新的开始用户上一句说的话它下一句就忘了。这种体验在简单问答场景下还能忍但在多轮任务场景下就是灾难。记忆层通常分为短期记忆和长期记忆。短期记忆就是当前对话的上下文通常直接放在 prompt 里传给模型。长期记忆则是跨对话持久化的信息需要存储和检索机制。短期记忆的管理核心是上下文窗口的分配。模型的上下文窗口是有限的你不能把所有历史对话都塞进去。常见的策略有几种只保留最近 N 轮对话、对历史对话做摘要压缩、根据相关性筛选历史信息。每种策略都有取舍保留最近 N 轮简单但可能丢失重要信息摘要压缩能保留更多信息但会引入额外的模型调用相关性筛选需要额外的检索逻辑。长期记忆的实现方式就更多了。简单的可以用文件存储复杂的可以用向量数据库做语义检索。我个人的经验是不要一上来就上向量数据库。很多场景下用结构化的键值存储加上简单的关键词匹配就能满足需求。向量检索确实强大但它引入了 embedding 模型、向量索引、相似度阈值等一系列需要调优的参数在需求还不明确的时候过早引入这些复杂度往往得不偿失。2.4 规划层Agent 的“战略思维”规划层决定 Agent 是“走一步看一步”还是“先想好再动手”。这两种模式没有绝对的好坏取决于任务的性质。对于简单的单步任务比如“查一下明天的天气”不需要规划直接调用工具就行。但对于复杂的多步任务比如“帮我安排一次出差包括订机票、订酒店、生成行程表”就需要规划能力。Agent 需要把大任务拆解成子任务确定执行顺序处理子任务之间的依赖关系。规划的实现方式主要有两类。一类是显式规划让模型先输出一个完整的计划然后按计划逐步执行。另一类是隐式规划模型在每一步根据当前状态决定下一步做什么不预先制定完整计划。显式规划的好处是全局视角清晰不容易遗漏步骤坏处是计划可能在实际执行中发现不可行需要重新规划。隐式规划更灵活但容易陷入局部最优做着做着就偏离了原始目标。实际项目中我倾向于用一种混合方式先让模型生成一个粗粒度的计划框架然后在执行过程中允许动态调整。这样既有全局方向又保留了灵活性。2.5 执行层把决策变成行动执行层是 Agent 的“肌肉”负责实际调用工具、处理返回结果、更新状态。这一层看起来简单但实际工程中有很多细节需要注意。首先是超时和重试。工具调用可能因为网络问题、服务端问题而失败执行层需要有合理的超时设置和重试策略。但重试不能无脑重试对于幂等操作可以安全重试对于非幂等操作比如创建订单就要小心重试可能导致重复创建。其次是并发控制。有些 Agent 需要同时调用多个工具比如同时查询多个数据源。这时候需要考虑并发数限制、结果聚合、部分失败的处理等问题。最后是状态管理。Agent 在执行过程中会产生大量中间状态——已经完成了哪些步骤、当前在哪个步骤、每个步骤的结果是什么。这些状态需要被妥善管理以便在出错时能够恢复或者在需要时能够回溯。2.6 编排层让所有部件协同工作编排层是 Agent 的“神经系统”负责协调模型层、工具层、记忆层、规划层和执行层的工作。它决定了整个 Agent 的控制流——什么时候调用模型、什么时候调用工具、什么时候读写记忆、什么时候触发规划。编排层的实现方式从简单到复杂有很多选择。最简单的就是一个 while 循环不断调用模型、执行工具、更新状态直到模型输出终止信号。复杂一点的可以用状态机、DAG有向无环图或者专门的工作流引擎。选择哪种编排方式取决于你的 Agent 需要多复杂的控制逻辑。如果只是简单的“模型决定调什么工具就调什么工具”一个循环就够了。如果需要条件分支、并行执行、错误恢复等复杂逻辑就需要更结构化的编排方式。2.7 安全层Agent 的“刹车系统”安全层是最后但绝不是最不重要的一个要素。Agent 有了自主决策和调用工具的能力也就有了“闯祸”的能力。安全层要做的就是给 Agent 装上刹车。安全层要解决的问题包括权限控制Agent 能调用哪些工具、能访问哪些数据、输入输出过滤防止 prompt 注入、防止敏感信息泄露、行为边界Agent 不能执行哪些操作、审计日志记录 Agent 的每一步操作以便追溯。我见过一个真实的案例一个开发者做了一个可以操作数据库的 Agent但没有做权限控制结果模型在用户的一句诱导下执行了删除操作。这个教训说明安全层不是可选项而是必选项。注意安全层的设计要遵循“最小权限原则”——Agent 只应该拥有完成当前任务所需的最小权限。不要为了方便而给 Agent 过大的权限。3. 七个决策点Agent 运行时的关键判断逻辑3.1 决策点一当前输入是否需要调用工具这是 Agent 运行时的第一个判断用户说了这句话我是直接回答还是需要调用工具这个判断看起来简单实际上很容易出错。模型有时候会过度调用工具——明明自己知道答案非要去查一下有时候又会该调工具而不调——明明需要实时数据却凭训练数据瞎编。影响这个判断的关键因素有几个。一是工具描述的清晰度如果工具描述明确说了“适用于什么场景”模型判断的准确率会高很多。二是 prompt 中的引导你可以在系统 prompt 中明确告诉模型“当需要实时数据时必须调用工具不要凭记忆回答”。三是模型本身的能力不同模型在这方面的表现差异很大。我的经验是在这个决策点上宁可让模型多调工具也不要让它少调。多调工具最多是浪费一点时间和成本少调工具可能导致给出错误信息后者对用户体验的伤害更大。3.2 决策点二选择哪个工具来执行确定了需要调用工具之后下一个问题是调哪个工具当工具数量少的时候比如三五个模型基本不会选错。但当工具数量增加到几十个的时候选择就变得困难了。模型可能会选一个功能相似但不完全匹配的工具或者选一个名字看起来相关但实际不合适的工具。解决这个问题的常见策略有几种。一是工具分组把功能相关的工具放在一组先让模型选组再在组内选具体工具。二是工具检索根据当前输入用检索算法找出最相关的几个工具只把这几个工具的描述给模型。三是层级化工具设计把一些工具作为另一些工具的子操作。实测下来工具数量超过 20 个之后选择准确率会明显下降。这时候就需要引入额外的工具筛选机制。3.3 决策点三工具参数如何填充选好了工具接下来要确定传什么参数。这个决策点的难点在于用户输入往往是模糊的而工具参数需要精确的值。比如用户说“帮我查一下最近的订单”这里的“最近”是多久一天一周一个月如果工具需要的是一个具体的时间范围模型就需要做一个合理的推断。再比如用户说“帮我订一张去北京的票”这里缺少出发地、出发时间等信息模型需要决定是追问用户还是用默认值。这个决策点的处理策略取决于你的产品设计。有些场景下追问用户是更好的选择有些场景下用合理的默认值然后让用户确认更流畅。关键是要在 prompt 中明确告诉模型你的偏好。3.4 决策点四工具返回结果如何解读工具调用返回的结果模型需要理解它意味着什么然后决定下一步怎么做。这里最常见的问题是工具返回了错误模型却当成成功来处理。比如 API 返回了一个包含错误码的 JSON模型可能只看到了里面的某些字段忽略了错误码然后基于错误的数据继续推理。解决这个问题的方法是在工具层做一层封装把工具返回的结果标准化明确标识成功还是失败失败时给出清晰的错误原因。同时在 prompt 中告诉模型“如果工具返回结果中包含 error 字段说明调用失败你需要根据错误信息决定是重试、换一个工具、还是告知用户”。3.5 决策点五是否需要调整计划在执行过程中Agent 可能会发现原来的计划不可行或者出现了新的信息需要重新规划。这时候就需要判断是继续按原计划执行还是调整计划这个决策点的难点在于判断“什么时候该坚持什么时候该放弃”。如果一遇到困难就调整计划Agent 可能会陷入反复规划的循环如果死守原计划又可能在错误的路上越走越远。我的经验是设定一个明确的重规划触发条件。比如连续两次工具调用失败、发现关键信息缺失、用户明确改变了需求。满足这些条件时才触发重规划否则继续执行。3.6 决策点六何时终止循环Agent 的核心是一个循环思考、行动、观察、再思考。这个循环什么时候结束终止条件通常有几种任务完成模型判断目标已达成、达到最大步数防止无限循环、遇到不可恢复的错误、用户主动中断。其中最重要的是最大步数限制。没有这个限制Agent 可能会陷入死循环不断调用同一个工具、不断产生相同的输出。我一般会设置一个合理的最大步数比如 10 到 15 步超过之后就强制终止并返回当前结果。3.7 决策点七最终输出如何组织循环结束后Agent 需要把执行过程中的结果组织成最终输出返回给用户。这个决策点看起来简单实际上很容易被忽视。Agent 在执行过程中可能调用了多个工具、产生了大量中间结果但用户不需要看到所有这些细节。最终输出应该是简洁的、面向用户需求的、去除了技术细节的。同时最终输出还需要考虑可追溯性。如果用户想知道 Agent 是怎么得出结论的你应该能够提供执行过程的摘要。这在调试和信任建立阶段特别重要。4. 从七要素到七个决策点工程实现的完整链路4.1 要素与决策点的映射关系七要素和七个决策点不是孤立的它们之间存在明确的映射关系。理解这种映射关系能帮你在实现时知道每个决策点应该在哪一层处理。决策点主要涉及的要素层关键实现位置是否调用工具模型层、工具层系统 prompt 工具描述选择哪个工具工具层、编排层工具注册与检索机制参数如何填充模型层、工具层工具参数 schema prompt结果如何解读执行层、模型层工具返回封装 prompt是否调整计划规划层、编排层重规划触发条件何时终止循环编排层、执行层循环控制逻辑输出如何组织模型层、安全层输出格式化 过滤这张表在实际开发中非常有用。当你发现 Agent 在某个决策点上表现不好时可以快速定位到应该去调整哪个要素层。4.2 一个最小可运行 Agent 的实现骨架理论说了这么多来看一个实际的实现骨架。下面这段伪代码展示了一个最小可运行 Agent 的核心逻辑涵盖了七要素和七个决策点的基本框架。class Agent: def __init__(self, model, tools, memory, max_steps10): self.model model self.tools tools self.memory memory self.max_steps max_steps def run(self, user_input): # 初始化状态 self.memory.add_user_message(user_input) step 0 while step self.max_steps: step 1 # 决策点123模型决定是否调工具、调哪个、传什么参数 response self.model.generate( messagesself.memory.get_context(), toolsself.tools.get_definitions() ) # 决策点6检查是否终止 if response.is_final_answer(): break # 执行工具调用 if response.has_tool_calls(): for tool_call in response.tool_calls: # 决策点4执行并解读结果 result self.execute_tool(tool_call) self.memory.add_tool_result(result) # 决策点5检查是否需要重规划 if self.should_replan(): self.memory.add_system_message(请重新评估当前计划) # 决策点7组织最终输出 return self.format_output(response)这个骨架虽然简单但已经包含了 Agent 的核心逻辑。实际项目中你需要在每个决策点上做更多的处理比如错误重试、并发控制、安全过滤等。4.3 常见架构模式与选型建议在实际工程中Agent 的架构模式主要有几种每种适用于不同的场景。ReAct 模式是最经典的 Agent 架构核心思想是“推理行动”交替进行。模型先推理当前应该做什么然后执行行动观察结果再推理下一步。这种模式实现简单适用于大多数场景但效率不高因为每一步都需要调用模型。Plan-and-Execute 模式是先制定完整计划再执行。这种模式减少了模型调用次数提高了效率但灵活性较差计划一旦制定就很难调整。Multi-Agent 模式是多个 Agent 协作完成任务。每个 Agent 负责不同的角色或子任务通过消息传递协调。这种模式适用于复杂任务但实现和调试的复杂度都高很多。我的选型建议是从 ReAct 模式开始遇到性能瓶颈再考虑 Plan-and-Execute只有在任务确实需要多角色协作时才上 Multi-Agent。不要一开始就追求复杂的架构简单能跑通比复杂但跑不起来强得多。5. 工程实践中那些文档不会告诉你的坑5.1 模型输出的不确定性如何影响决策点LLM 的输出本质上是概率性的同样的输入可能产生不同的输出。这个特性在 Agent 场景下会被放大因为 Agent 是一个多步决策的过程每一步的微小差异都可能在后续步骤中被放大。我遇到过一个典型案例一个查询类 Agent在测试时表现很好但上线后偶尔会出现“答非所问”的情况。排查后发现问题出在决策点二选择工具上。模型在大多数情况下会正确选择查询工具但偶尔会选择另一个功能相似的工具导致返回了不相关的数据。解决这个问题的办法不是去“修复模型”而是在工程层面增加确定性。具体做法包括在 prompt 中给出更明确的工具选择规则、在工具层增加参数校验、在输出层增加结果合理性检查。这些工程手段比试图让模型“每次都选对”要可靠得多。5.2 工具调用失败的连锁反应与隔离策略工具调用失败是常态不是异常。网络抖动、API 限流、服务端错误这些都会导致工具调用失败。如果 Agent 没有处理好这些失败就会出现连锁反应——一个工具失败导致整个流程崩溃。我的做法是在工具层做隔离。每个工具调用都包一层错误处理失败时返回一个结构化的错误结果而不是抛出异常。这样模型能感知到失败并根据错误信息决定下一步怎么做。def safe_tool_call(tool, params): try: result tool.execute(params) return {status: success, data: result} except TimeoutError: return {status: error, reason: timeout, suggestion: retry} except ValidationError as e: return {status: error, reason: str(e), suggestion: check_params} except Exception as e: return {status: error, reason: unknown, suggestion: skip}这种结构化的错误返回让模型能够做出更合理的决策而不是面对一个异常不知所措。5.3 上下文膨胀与性能衰减的应对Agent 运行过程中上下文会不断增长——每一轮对话、每一次工具调用结果都会加到上下文里。当上下文增长到一定程度会出现两个问题一是超出模型的上下文窗口限制二是模型在长上下文中的表现会下降所谓的“lost in the middle”问题。应对策略有几个。一是定期压缩上下文把早期的对话和工具结果做摘要只保留关键信息。二是滑动窗口只保留最近 N 轮的内容。三是外部化存储把不常用的信息存到外部需要时再检索回来。我通常会在上下文达到模型窗口的 60% 到 70% 时触发压缩。压缩时保留最近几轮的完整内容对更早的内容做摘要。摘要的质量很关键要保留关键的事实信息和决策依据去掉冗余的对话内容。5.4 安全边界的设计与验证安全层的设计需要在 Agent 开发的早期就介入而不是等到最后再补。我见过太多项目功能开发完了才想起来做安全控制结果发现架构上不支持细粒度的权限控制只能推倒重来。安全设计的第一步是明确 Agent 的能力边界。列出 Agent 能做的所有操作然后逐一评估每个操作的风险等级。高风险操作如删除数据、发送消息、执行支付需要额外的确认机制低风险操作如查询信息可以放开。第二步是实现权限控制。每个工具都应该有权限标签Agent 在调用工具前要检查当前上下文是否有权限。权限可以基于用户角色、会话状态、操作类型等维度来分配。第三步是输入输出过滤。输入侧要防止 prompt 注入输出侧要防止敏感信息泄露。这两件事都不容易做到完美但基本的防护措施必须有。注意安全层的验证不能只靠测试用例还需要做对抗性测试。尝试用各种方式诱导 Agent 越权操作看看它会不会上当。这种测试往往能发现一些你意想不到的漏洞。6. 从能跑到好用Agent 调优的实战思路6.1 建立可观测性日志、追踪与回放Agent 调优的第一步不是改代码而是建立可观测性。你需要能够看到 Agent 每一步在做什么、为什么这么做、结果是什么。没有这个基础调优就是盲人摸象。我在项目中会记录以下几类信息每次模型调用的完整输入输出包括 prompt、模型返回、token 消耗、每次工具调用的参数和结果、每个决策点的判断依据、整个会话的状态变化。这些信息不仅用于调试也用于后续的分析和优化。回放功能也很重要。当发现一个 bad case 时你需要能够重现它。把当时的输入、上下文、模型版本都记录下来才能在本地复现问题、验证修复方案。6.2 针对七个决策点的定向优化有了可观测性之后就可以针对性地优化了。优化的思路是先定位是哪个决策点出了问题再针对性地调整。如果问题出在决策点一是否调工具就去优化系统 prompt 中的工具使用引导。如果问题出在决策点二选哪个工具就去优化工具描述或引入工具检索。如果问题出在决策点四结果解读就去优化工具返回的格式或增加结果校验。这种定向优化的效率远高于盲目调整。我见过一些开发者遇到问题就改 prompt改来改去也不知道哪个改动起了作用。正确的做法是先定位决策点再定位要素层然后做最小化的修改验证效果。6.3 评估体系的搭建与迭代节奏Agent 的评估比传统软件复杂得多因为它的输出不是确定性的。你不能简单地用“通过/不通过”来评估需要建立多维度的评估体系。我通常会从几个维度来评估任务完成率Agent 是否完成了用户的目标、步骤效率用了多少步完成、工具调用准确率工具选择和参数填充是否正确、输出质量最终输出是否满足用户需求、安全性是否有越权或泄露风险。评估集的建设也很关键。需要覆盖典型场景、边界场景、对抗场景。每次修改后都在评估集上跑一遍确保没有引入回归。迭代节奏上我的建议是小步快跑。每次只改一个地方改完立即验证。不要一次性做大量修改那样出了问题很难定位是哪个改动导致的。7. 我对 Agent 工程实现的一点个人体会做了几个 Agent 项目之后我最大的体会是Agent 的工程实现难点不在 AI而在工程。模型能力固然重要但决定一个 Agent 好不好用的往往是那些工程细节——工具设计得好不好、错误处理得完不完善、上下文管理得合不合理、安全边界划得清不清楚。七要素和七个决策点这套框架本质上是在帮你把“做一个 Agent”这个模糊的任务拆解成一系列具体的、可操作的工程问题。每当你觉得 Agent 行为不对劲的时候可以对照这套框架看看是哪个要素没做好或者哪个决策点的逻辑有问题。另外一个体会是不要追求一步到位。先做一个能跑通的最小版本哪怕它很粗糙。跑通之后你才能看到真正的问题在哪里才能有针对性地优化。我见过太多人在还没跑通的时候就纠结架构选型、纠结用哪个框架结果时间都花在了纠结上东西一直没做出来。最后分享一个实用的小技巧在开发阶段把 Agent 的每一步决策都打印出来。不只是最终输出还包括每次模型调用的输入输出、每次工具调用的参数和结果、每个决策点的判断依据。这些信息在调试时的价值远超你的想象。等到上线时再把这些日志关掉或降级但在开发阶段它们是你最好的朋友。