AI Agent 这个词在过去一年里被反复提及但真正动手搭过一套能跑起来的 Agent 系统的人都知道从能对话到能干活之间隔着一整套工程决策。我前后做过几个不同形态的 Agent 项目有基于工具调用的任务型 Agent也有带记忆和规划能力的多轮协作系统踩过的坑从工具描述写错一个字段导致模型反复调用同一个接口到循环没有终止条件把 token 烧光。这些经历让我意识到Agent 的工程实现本质上不是调个大模型 API 就完事而是一系列关于边界、状态、决策权的设计问题。这篇内容我想把 Agent 的工程实现拆成两个视角来讲一个是构成 Agent 的七个核心要素另一个是搭建过程中绕不开的七个决策点。前者帮你理解一个 Agent 由什么组成后者帮你理解每一步你该怎么选。适合已经了解 LLM 基本用法、想真正落地一个 Agent 系统的开发者也适合正在评估 Agent 架构方案的技术负责人。全文会尽量用我实际项目里的例子来说明不讲空泛的概念。1. 七个要素拆开一个 Agent 到底由什么构成很多人第一次接触 Agent 会把它理解成会调用工具的聊天机器人这个理解不算错但太粗糙。真正拆开来看一个可用的 Agent 至少包含七个要素缺一个都会在某个场景下出问题。我按重要性从底层往上讲。1.1 模型不只是选个大的就行模型是整个 Agent 的推理核心但选型远不是越大越好。我在实际项目里的经验是模型能力要和任务复杂度匹配。一个只做固定格式信息抽取的 Agent用中等规模的模型配合好的提示词效果往往比用最大模型加模糊提示词更稳定而且成本和延迟都低得多。选模型时要重点看三个维度指令遵循能力、工具调用格式的稳定性、长上下文下的注意力保持。第一点决定它能不能按你的格式输出第二点决定它调用工具时会不会漏参数或编造参数第三点决定多轮对话后它还记得多少。我遇到过一个小模型在单轮任务里表现很好但到第五轮就开始忘记最初设定的约束这就是长上下文注意力的问题。还有一个容易被忽略的点模型的拒答倾向。有些模型在安全对齐上比较激进遇到稍微模糊的指令就直接拒绝这在 Agent 场景里很致命因为 Agent 的中间步骤经常是模型自己生成的、看起来有点奇怪的指令。选型时最好用你真实的业务指令去测一轮而不是只看公开榜单。1.2 工具Agent 的手和脚工具是 Agent 与外部世界交互的接口。没有工具Agent 就只是个会说话的模型有了工具它才能查数据、写文件、发请求、操作系统。工具的设计有几个关键原则。第一工具粒度要适中。太粗的工具比如一个处理订单的工具包揽所有逻辑会让模型难以正确使用因为它不知道内部发生了什么太细的工具比如把一次数据库查询拆成连接、查询、关闭三步会让模型在编排上浪费大量 token。我的经验是一个工具对应一个语义完整的动作比如查询用户订单列表而不是执行 SQL。第二工具描述就是提示词。模型判断该不该调用某个工具、传什么参数完全依赖你写的描述。描述里要包含这个工具做什么、什么时候用、参数的含义和格式、返回什么。我踩过最典型的坑是工具描述里没写清楚参数是用户 ID 还是用户名结果模型一会儿传 ID 一会儿传名字接口直接报错。第三工具要有明确的失败语义。工具执行失败时返回什么直接决定 Agent 能不能自我纠正。返回一个笼统的操作失败模型只能瞎猜返回用户 ID 不存在请检查后重试模型就知道该换个参数再试。1.3 记忆短期、长期与工作记忆的分层记忆是 Agent 区别于单次问答的核心能力之一。我习惯把记忆分成三层短期记忆当前对话的上下文通常就是消息历史。它决定了 Agent 在当前任务里的连贯性。长期记忆跨会话持久化的信息比如用户偏好、历史决策、知识库。通常用向量库或结构化存储实现。工作记忆当前任务执行过程中的中间状态比如已经查到的数据、已经完成的步骤、待办清单。这三层的管理策略完全不同。短期记忆要控制长度超了就得做摘要或截断长期记忆要解决检索准确率的问题召回错了比不召回还糟工作记忆要显式维护否则模型在多步任务里会忘记自己做到哪了。我见过很多 Agent 项目只做了短期记忆结果用户每次回来都要重新交代背景体验很差。也见过长期记忆做得太重每次对话都塞一大堆检索结果进上下文反而干扰了模型判断。记忆的关键不是记得多而是在对的时候想起对的事。1.4 规划把大目标拆成可执行步骤规划能力决定 Agent 能不能处理复杂任务。一个没有规划的 Agent 只能做一步到位的事比如查一下天气有了规划它才能做帮我安排下周的出差这种需要多步协调的任务。规划的实现方式大致有三种。第一种是隐式规划让模型在推理过程中自己决定下一步不显式输出计划。这种方式灵活但不可控容易跑偏。第二种是显式规划先让模型输出一个步骤列表再逐步执行。这种方式可控、可审计但计划一旦定死遇到意外就不好调整。第三种是混合式先出粗粒度计划每执行一步再根据结果细化下一步。我在实际项目里更倾向混合式。纯显式规划在真实环境里太脆因为工具返回的结果经常和预期不一样纯隐式规划又太难调试。混合式的好处是既有全局方向又保留了局部调整空间。1.5 循环机制Agent 的心跳循环机制是 Agent 的运行时骨架。它决定了 Agent 什么时候思考、什么时候行动、什么时候停止。最基础的循环是思考-行动-观察三步反复直到任务完成或达到终止条件。循环设计里最关键的是终止条件。我见过太多 Agent 因为没有好的终止条件要么提前停止任务没做完就以为做完了要么无限循环一直调用工具停不下来。好的终止条件应该包含任务完成的明确信号、最大步数限制、连续失败次数限制、以及超时控制。另一个关键是每轮循环里给模型看什么。把所有历史都塞进去会爆上下文只给最后一步又会让模型失去全局视角。我的做法是保留完整的行动-观察记录但对早期的推理过程做压缩只保留结论。1.6 上下文管理决定 Agent 能走多远上下文管理是 Agent 工程里最容易被低估的部分。它直接决定了 Agent 能处理多复杂的任务、能持续多少轮对话。核心矛盾是模型需要足够的信息来做决策但上下文窗口是有限的。解决思路有几个摘要压缩把早期对话总结成一段话、检索增强需要时再召回相关历史、结构化状态把关键信息抽成结构化字段而不是留在自然语言里、分层上下文系统提示、任务状态、近期对话分开管理。我个人的经验是结构化状态最有效。与其让模型从一堆对话里自己找用户要订的是哪天的机票不如在状态里明确存一个departure_date字段。这样既省 token又减少模型出错的机会。1.7 安全与边界让 Agent 知道什么不能做安全边界是 Agent 从 demo 走向生产必须解决的问题。一个能调用工具的 Agent理论上能做的事情非常多如果不加约束它可能删数据、发错消息、泄露信息。安全边界的设计分几层工具层做权限控制敏感操作需要额外确认提示层明确告诉模型哪些操作需要谨慎运行时层做参数校验和结果过滤审计层记录所有工具调用便于事后追溯。我特别想强调一点不要指望靠提示词就能管住 Agent 的行为。提示词是软约束模型可能因为各种原因绕过它。真正的安全要靠硬约束也就是在工具执行前做校验不符合条件的调用直接拒绝。2. 七个决策点搭建 Agent 时你真正要做的选择理解了七个要素之后接下来是实操层面的问题每一步你该怎么选。我把搭建过程中最关键的七个决策点列出来每个都附上我的实际取舍和理由。2.1 决策一Agent 的自主程度定在哪一档这是最上层的决策决定了整个系统的形态。自主程度大致可以分三档档位特征适用场景我的建议低自主固定流程模型只在特定节点做判断客服问答、表单填写稳定优先别过度设计中自主模型决定调用哪些工具但流程有边界信息检索、数据分析大多数业务场景的最优解高自主模型自主规划、自主执行、自主纠错开放式研究、复杂自动化只在容错高的场景用我的经验是绝大多数业务场景应该选中自主。低自主浪费了模型能力高自主又太难控制。中自主的核心是给模型选择权但限定选择范围比如给它五个工具让它决定用哪个、按什么顺序用但不让它自己发明新工具。2.2 决策二工具调用用原生还是自己解析现在主流模型都支持原生的工具调用function calling / tool use但有些场景下自己解析文本输出反而更灵活。原生工具调用的好处是格式稳定、模型专门训练过、解析可靠。坏处是受模型支持的工具数量限制而且有些模型对复杂嵌套参数支持不好。自己解析文本输出的好处是灵活可以定义任意复杂的输出结构。坏处是模型可能不按格式输出需要大量容错处理。我的选择是能用原生就用原生原生搞不定的复杂结构再用文本解析兜底。比如简单的参数传递用原生需要模型输出一个复杂的多步计划时用结构化文本加解析器。2.3 决策三循环的终止条件怎么设这个决策直接关系到 Agent 会不会失控。我的终止条件通常是组合式的显式完成信号模型输出特定的完成标记或者调用了任务完成工具。最大步数硬性上限比如 15 步。超过就强制停止并返回当前结果。连续失败阈值连续 3 次工具调用失败就停止避免死循环。超时控制整个任务的总时长上限。这里有个细节最大步数不能设得太小否则复杂任务做不完也不能太大否则出问题时浪费资源。我的经验值是简单任务 5 步中等任务 10 步复杂任务 20 步超过 20 步基本说明任务拆解有问题。2.4 决策四记忆用什么存储方案记忆存储的选型要看具体需求纯对话历史直接用消息列表最简单适合短会话。向量数据库适合语义检索比如找出和当前问题相关的历史对话。结构化数据库适合精确查询比如用户上次下单是什么时候。混合方案结构化存事实向量库存语义两者配合。我在项目里用得最多的是混合方案。用户的基本信息、偏好设置这类明确的事实存结构化库对话历史、知识片段这类模糊的内容存向量库。检索时先查结构化拿到硬事实再用向量库补充相关背景。提示向量检索的召回质量高度依赖 embedding 模型和分块策略。分块太大召回不准太小又丢失上下文。我的经验是按语义段落分块每块 200-500 字重叠 50 字左右。2.5 决策五错误处理放在哪一层Agent 执行过程中出错是常态关键是错误在哪一层被处理。我通常分三层工具层捕获工具本身的异常返回结构化的错误信息给模型。循环层判断错误是否可重试决定是继续还是终止。模型层让模型根据错误信息决定下一步比如换个参数重试或换条路径。这里的关键是错误信息要写给模型看不是写给人看。堆栈信息对模型没用它需要的是哪里错了、可能的原因、建议怎么做。我一般会把工具错误转成自然语言描述再返回给模型。2.6 决策六怎么控制 token 成本token 成本是 Agent 项目绕不开的现实问题。一个多轮 Agent 任务动辄消耗几万 token如果不控制成本会失控。我的控制手段有几个上下文压缩定期把历史摘要化、工具结果裁剪只返回模型需要的字段不要整个 JSON 塞进去、模型分级简单判断用小模型复杂推理用大模型、缓存相同输入直接返回缓存结果。其中效果最明显的是工具结果裁剪。我见过一个项目工具返回的 JSON 有几十个字段但模型实际只用其中三个剩下的全是浪费。裁剪之后 token 消耗直接降了一半。2.7 决策七怎么评估 Agent 好不好用Agent 的评估比传统软件难得多因为它的输出不是确定性的。我的评估方法分两个层面离线评估准备一批标准任务每个任务有明确的成功标准跑一遍看成功率。同时记录平均步数、平均 token 消耗、平均耗时。在线评估上线后收集真实用户的任务完成率、人工介入率、用户反馈。离线评估里最重要的是任务集的代表性。如果任务集太简单Agent 看起来表现很好上线就崩如果太难又看不出改进效果。我的做法是从真实日志里采样覆盖简单、中等、困难三档。3. 从零搭一个 Agent 的完整流程前面讲了要素和决策点这一节我把它们串起来讲一个从零搭建的完整流程。以一个帮用户查询和处理订单的 Agent 为例。3.1 第一步定义任务边界和能力清单动手写代码之前先明确这个 Agent 要做什么、不做什么。订单 Agent 的能力清单可能是查询订单状态、修改收货地址、申请退款、查询物流。不做的事情直接修改订单金额、删除订单、处理支付问题。这个边界很重要它决定了你要暴露哪些工具也决定了安全约束怎么设。边界模糊的 Agent 最后往往什么都能做一点但什么都做不好。3.2 第二步设计工具接口根据能力清单设计工具。每个工具要有清晰的名称、描述、参数定义、返回格式。以查询订单状态为例{ name: query_order_status, description: 根据订单号查询订单的当前状态包括支付状态、发货状态、物流信息。当用户询问订单进度时使用此工具。, parameters: { order_id: { type: string, description: 订单号通常是 16 位数字字符串, required: true } } }注意描述里明确写了当用户询问订单进度时使用这就是在引导模型判断调用时机。参数描述里写了格式减少模型传错的可能。3.3 第三步搭建循环骨架循环骨架是整个 Agent 的运行时。一个最小可用的循环大概是这样def run_agent(user_input, max_steps10): messages [{role: system, content: SYSTEM_PROMPT}] messages.append({role: user, content: user_input}) for step in range(max_steps): response call_llm(messages, toolsTOOLS) if response.has_tool_call: tool_result execute_tool(response.tool_call) messages.append(response.message) messages.append({role: tool, content: tool_result}) else: return response.content return 任务未在限定步数内完成这个骨架很简单但包含了核心逻辑调用模型、判断是否要调工具、执行工具、把结果喂回去、继续循环。实际项目里还要加上错误处理、日志、超时控制等。3.4 第四步写系统提示词系统提示词是 Agent 的人格设定和行为准则。它要包含角色定义、能力范围、行为约束、输出格式要求。我写系统提示词的经验是具体优于抽象正面优于负面。与其说不要做危险操作不如说修改地址前必须先确认用户身份。与其说友好地回复不如给出具体的回复风格示例。3.5 第五步接入记忆和状态管理在循环骨架里加入状态管理。每次工具调用后把关键信息存进状态对象而不是全靠消息历史。比如查到订单后把订单号、状态、金额存进state.order_info后续需要时直接引用。这样做的好处是即使对话很长、早期消息被压缩了关键信息依然在状态里不会丢。3.6 第六步加错误处理和重试给工具调用加上 try-catch把异常转成模型能理解的错误信息。同时加上重试逻辑如果是临时性错误比如网络超时自动重试如果是参数错误把错误信息返回给模型让它修正。3.7 第七步测试和迭代用真实场景测试记录失败案例分析失败原因。常见的失败模式有工具选错、参数传错、循环不终止、上下文丢失。针对每种失败模式调整对应的设计。4. 那些文档里不会写的踩坑经验这一节是我最想分享的部分都是实际项目里踩出来的教训。4.1 工具描述里的一个词能决定成败我遇到过一个案例一个查询工具的描述写的是查询用户信息结果模型在用户问我的订单到哪了的时候也调用了它因为它觉得用户信息包含订单。后来把描述改成查询用户的基本资料包括姓名、注册时间、会员等级不包含订单信息问题就解决了。工具描述要精确到包含什么、不包含什么尤其是容易混淆的工具之间要明确区分。4.2 模型会假装完成了任务这是最隐蔽的坑。模型有时候会输出我已经帮您修改了地址但实际上它根本没调用修改工具或者调用了但失败了。这种情况在提示词不够严格时特别常见。解决办法是在系统提示词里明确要求只有工具返回成功后才能声称完成。同时在代码层面校验如果模型声称完成但没有对应的成功工具调用记录就强制它重新执行。4.3 上下文压缩会丢关键信息做上下文压缩时如果只是简单摘要很容易丢掉关键细节。比如把用户要改地址新地址是 XX 市 XX 区 XX 路 1 号压缩成用户要改地址新地址就丢了。我的做法是压缩时保留所有实体信息地址、订单号、金额、时间只压缩推理过程和寒暄。或者干脆把实体信息抽到结构化状态里压缩时只压缩对话本身。4.4 并行工具调用不一定更快有些模型支持一次返回多个工具调用看起来能并行执行提速。但实际上如果这些调用之间有依赖关系并行执行会出错。而且并行调用的结果返回顺序不确定模型可能对不上号。我的建议是只在工具之间确实无依赖时才用并行否则老老实实串行。串行虽然慢一点但可控。4.5 温度参数对 Agent 的影响比想象中大做对话时温度高一点让回复更自然但做 Agent 时温度高会导致工具调用不稳定。同一个任务温度 0.7 时可能这次调 A 工具下次调 B 工具。我的经验是Agent 场景温度设低一点0 到 0.3 之间。需要创造性的时候再单独调高。4.6 日志要记全但别只记文本Agent 调试最痛苦的是复现问题。所以日志要记全每轮的输入、模型的原始输出、工具调用参数、工具返回结果、状态变化。但只记文本不够最好把每轮的消息结构、token 数、耗时都结构化记录下来。这样分析问题时能快速定位是模型的问题、工具的问题还是编排的问题。5. 不同场景下的架构取舍Agent 的架构没有标准答案不同场景要不同设计。这一节我按几个典型场景讲讲取舍。5.1 单任务型 Agent简单直接最好如果 Agent 只做一件事比如根据描述生成 SQL那就不需要复杂的循环和记忆。一次模型调用加一次工具执行就够了。过度设计反而增加出错概率。5.2 多轮对话型 Agent记忆是核心如果 Agent 要和用户多轮交互记忆管理就是核心。要解决怎么记住用户说过的话、怎么在长对话里保持连贯、怎么跨会话记住用户偏好。这类 Agent 的架构重点在记忆层循环反而简单。5.3 复杂任务型 Agent规划和状态是关键如果 Agent 要完成一个需要多步协调的复杂任务比如分析这份销售数据并生成报告那规划和状态管理就是关键。要有明确的任务分解、步骤追踪、中间结果管理。这类 Agent 最容易失控所以终止条件和错误处理要特别完善。5.4 多 Agent 协作通信协议是难点多个 Agent 协作时难点不在单个 Agent而在它们之间怎么通信、怎么分工、怎么解决冲突。我的经验是多 Agent 系统要有一个明确的协调者负责分配任务和汇总结果避免 Agent 之间互相等待或重复劳动。6. 评估与迭代让 Agent 越用越好Agent 上线不是终点而是迭代的起点。这一节讲怎么持续改进。6.1 建立失败案例库每次 Agent 失败都把案例存下来用户输入、Agent 的执行轨迹、失败原因。积累到一定量后分析失败模式找出高频问题。我一般会按失败类型分类工具选择错误、参数错误、循环问题、上下文问题、模型能力不足。每类问题对应不同的改进方向。6.2 用失败案例反哺提示词和工具设计失败案例是改进的最好素材。工具选错就优化工具描述参数传错就补充参数说明和示例循环不终止就调整终止条件。这个过程是迭代的改一轮测一轮看失败率有没有下降。6.3 监控关键指标上线后要持续监控几个指标任务完成率、平均步数、平均 token 消耗、平均耗时、人工介入率。任何一个指标异常波动都说明有问题。我特别关注平均步数因为它能反映 Agent 的效率。如果平均步数突然上升可能是模型变懒了也可能是某个工具出问题了。6.4 定期回归测试每次改动提示词或工具后都要跑一遍回归测试确保没有引入新问题。回归测试集要覆盖历史失败案例防止老问题复发。7. 关于 Agent 工程的一些个人判断做了几个 Agent 项目之后我对这个领域有一些自己的判断不一定对但都是实践出来的。第一Agent 的瓶颈往往不在模型而在工程。模型能力已经足够强了真正难的是怎么把模型能力稳定地组织起来。工具设计、状态管理、错误处理这些脏活才是决定 Agent 好不好用的关键。第二简单架构往往比复杂架构更可靠。我见过很多项目一上来就搞多 Agent 协作、复杂规划结果调试成本极高效果还不如一个设计良好的单 Agent。能用简单方案解决就别上复杂方案。第三评估比开发更重要。没有好的评估你根本不知道改动是变好了还是变坏了。我现在的习惯是先搭评估框架再开发功能。第四安全边界要从第一天就设计。不要等到上线前才想安全问题那时候架构已经定型改起来很痛苦。工具权限、参数校验、审计日志这些要在设计阶段就考虑进去。第五Agent 不是万能的。有些任务用传统程序解决更好更快更稳更便宜。Agent 适合的是那些规则不明确、需要灵活判断的场景。别为了用 Agent 而用 Agent。最后分享一个我常用的调试技巧当 Agent 行为异常时先把温度设成 0把工具数量减到最少把提示词简化到最核心看问题还在不在。如果不在就逐步加回复杂度定位是哪部分导致的。这个方法能快速缩小问题范围比盯着日志猜有效得多。