聊 AI Agent 的人很多真把 Agent 跑进生产环境的人没那么多。我见过太多团队从开源仓库里拉一个 LangChain 示例就往上冲结果要么 token 账单先炸要么 Agent 在工具调用里原地打转最后丢下一句“大模型做 Agent 不可靠”就撤了。以我自己的实操经验看问题很少出在模型身上多数是工程实现没做扎实该拆的组件没拆该提前拍板的决策拖到了线上才暴露。这篇文章就把我踩过的坑和沉淀下来的方法论一起聊透从 Agent 的七个组成要素讲到工程实现里必须面对的七个决策点适合正在搭 Agent、准备上生产的同学也适合想搞懂 Agent 到底是怎么跑起来的开发者。1. Agent 不是一个大 Prompt先把七个要素拆开看很多人谈起 Agent第一反应是“给大模型写个厉害的系统提示词”。这种理解不能说全错但离工程实现太远。一个能稳定工作的 Agent本质是一套由多个部分协作组成的系统我习惯把它拆成七个要素来看模型内核、系统提示词、规划器、记忆、工具集、执行反馈闭环、安全护栏。1.1 模型内核一切决策的发动机模型内核是整个 Agent 里唯一具备“智力”的部分它负责理解目标、拆解问题、判断该调用什么工具、理解工具返回的内容最后组织成用户能看懂的回答。没有模型内核后面所有组件都是死物。这里有个很容易被忽略的点Agent 场景下的模型能力要求和纯聊天完全不同。纯聊天只要表达流畅就行但 Agent 需要模型做多步推理还要能严格按格式输出。我在选型时会把函数调用准确率、长文本指令遵循能力排在第一位而不是看榜单上的综合分。因为一个工具参数都填不对的模型即使文笔再好跑 Agent 也是灾难。1.2 系统提示词给 Agent 的一份岗位说明书系统提示词不是用来“哄模型开心”的它的本质是约束行为边界和输出格式。一个合格的系统提示词至少要写清楚三件事角色和任务边界、可用的工具清单、工作流程和输出格式。我见过最典型的错误是把系统提示词写得像营销文案塞满各种形容词。真正好用的提示词恰恰像一份岗位说明书冷静、明确、可执行。举个例子与其写“你是一个智能助手请尽可能帮助用户”不如写清楚“你只能使用以下三个工具完成任务如果工具无法解决用户问题直接说明无法处理所有工具调用必须输出 JSON不要输出多余解释”。1.3 规划器从“走一步看一步”到“先画地图再出发”规划器是决定 Agent 行为路径的组件。简单的 Agent 不显式做规划走一步看一步典型代表就是 ReAct 模式思考一步、执行一步、观察结果、再思考下一步。复杂一点的 Agent 会用 Plan-and-Execute先把目标拆成一份子任务清单再逐个执行。这两种路线没有绝对优劣关键看任务场景。单步判断型任务用 ReAct 更灵活因为每步都在依据最新信息调整方向多步骤固定流程用 Plan-and-Execute 更稳定因为先规划可以减少中间跑偏。我在生产项目里经常混合使用先用规划器生成计划再在执行每个子任务时走 ReAct 循环。1.4 记忆Agent 的短期工作台和长期档案库记忆要素在 Agent 架构里被严重低估。它至少分两层短期记忆是当前对话上下文窗口里的信息长期记忆是需要持久化保存的用户偏好、历史决策、中间结果。工程实现时短期记忆要考虑的是上下文塞多少、什么时候截断、什么时候做摘要压缩长期记忆要考虑的是存哪里、用什么结构、怎么检索。不要一听到记忆就上向量数据库很多场景其实只需要一个普通的业务表。记忆选型没有标准答案只有最贴合业务场景的答案。1.5 工具集Agent 的手和脚工具是 Agent 对外部世界产生影响的通道。一个能查天气的 Agent工具就是气象 API一个能操作浏览器的 Agent工具就是浏览器控制接口一个能自动发布内容的 Agent工具就是内容平台的发布接口。工程实现上工具层的核心不是“能调用多少个 API”而是“把工具定义清楚”。一个工具要包含名称、功能描述、参数 schema、返回格式。模型就是靠着工具的描述来决定什么时候调用、传什么参数所以工具描述里写清楚“这个函数是干嘛的”“参数限制是什么”直接影响成功率。我见过团队花一周调模型最后发现只是工具描述写得有歧义。1.6 执行与反馈闭环里最容易被忽略的一环Agent 和普通程序最大的区别在于它是闭环控制模型输出一个动作执行器去调工具工具返回结果再把结果交给模型继续推理。看起来简单但执行反馈环节有大量脏活要做。工具调用于是成功还是失败要有明确的结构化返回值工具执行超时了要触发重试还是换策略工具返回的结果太长要先做摘要再喂回模型连续多轮工具调用之间还要判断状态是否一致。这些细节决定了一个 Agent 是从“能跑 demo”变成“能跑生产”。1.7 安全护栏让 Agent 按规矩做事安全护栏不是最后才加的装饰它应该是 Agent 系统的地基。护栏分两层一层是输出侧限制模型不能生成敏感内容、不能执行越权操作另一层是流程侧限制 Agent 单次任务的最大步数、限制工具调用的范围、拦截高危险操作。我习惯把护栏拆成三段来写任务前校验用户输入是否合规任务中限制步数和工具白名单任务后审计完整执行轨迹。很多团队把 Agent 跑挂了才想起来加护栏其实在架构设计阶段把护栏放进去后面能省下大把排查时间。2. 为什么工程实现绕不开七个决策点搞清楚七个要素只是第一步真正干活的时候你会发现每个要素落到工程里都有一堆岔路口。这些岔路口就是我说的七个决策点模型选型、框架选择、规划策略、工具协议、记忆存储、任务生命周期、可观测性与评估。2.1 要素解决“是什么”决策解决“怎么做”七个要素是逻辑上的组成它们告诉你 Agent 系统里必须有这些东西七个决策点则是工程上的取舍它们告诉你每个组成到底怎么实现。你可以用七要素去评审一个 Agent 架构是否完整用七个决策点去判断一个实现方案是否合理。这里有一个很容易走的弯路很多团队拿到需求后直接开始写代码模型没选、框架没定、规划策略没想顺手拉起一个 demo 就开始填功能。结果做到一半发现当前模型工具调用太弱换模型又导致提示词重写眼看着上线日期一天天逼近只能硬着头皮交付。更稳妥的做法是在设计阶段就把七个决策点逐项过一遍。2.2 决策之间会连锁反应七个决策点不是相互独立的一个决策会强烈影响其他决策。选了大上下文模型你的记忆方案就可以少做压缩选了 ReAct你的工具输出格式就要设计得非常严格选了自研框架你的可观测性基建就得自己从零搭。所以我在真正的项目里不会一个个孤立做决策而是先定一个“主心骨”这套 Agent 的核心场景是什么对延迟敏感还是对成本敏感任务流程是固定还是开放。这个主心骨定了七个决策里有一半其实就自动有了倾向性答案。3. 七个决策点逐一拆解下面把七个决策点逐个展开。每个决策点我都会给出判断标准和常见的坑方便你对着自己的场景做取舍。3.1 模型选型API 还是开源多大才算够模型选型是最先要拍板的决策点因为它决定了成本上限和能力下限。闭源 API 的优势是省心、能力领先劣势是 token 成本会随调用量线性增长开源模型可以私有部署适合高并发和数据敏感场景劣势是推理性能通常要自己调优。我的判断标准一般是这样如果场景里需要很强的工具调用和复杂推理先试闭源模型的最新中杯型号如果场景固定、流程明确开源模型完全够用。至于参数量不要机械地认为“越大越好”。Agent 场景里模型够用的标志是能稳定按格式输出、能正确理解工具描述、能执行多步推理不迷路。拿一个简单测试集跑一遍比看任何评测榜单都靠谱。3.2 框架选择LangChain、LlamaIndex、自研还是 Rust 运行时框架选择是这个领域争论最多的话题。LangChain 生态大、组件全但抽象层厚出了问题不太好查LlamaIndex 更擅长文档检索场景做 RAG 类 Agent 很顺手自研则能精确控制循环和状态但对团队的工程能力要求高。最近 Rust 在 Agent 运行时方向的热度也确实高越来越多的轻量运行时开始用 Rust 写核心循环。Rust 做 Agent 运行时最大的优势是性能稳定、内存占用可控适合需要高并发承载 Agent 实例的场景。但前提是团队有人能啃 Rust。我的建议是小步快跑阶段别排斥框架但一定要理解框架下面到底发生了什么等业务稳定了再考虑是否换更可控的自研或 Rust 运行时。3.3 规划策略ReAct 还是 Plan-and-Execute规划策略决定了 Agent 面对一个复杂目标时的行为模式。ReAct 模式代码简单模型每步都能根据最新反馈调整下一步特别适合工具有依赖关系、结果不可预知的场景。但没有整体计划容易在多步任务中走偏或重复劳动。Plan-and-Execute 模式先让模型输出一个计划然后逐个执行。优点是任务方向稳定、中间状态清晰缺点是计划一旦制定就很难吸收中途发现的新信息。我的混合方案是先让 Agent 用规划器生成一个粗粒度计划然后在执行每个计划项时用 ReAct 模式做细粒度操作两个策略在同一套架构里各吃一段。3.4 工具协议Function Calling 还是自由文本工具调用的交互协议是 Agent 工程里直接影响稳定性的决策。闭源模型通常支持原生的 Function Calling模型直接输出结构化的工具调用参数解析稳定这是体验最好的方案。开源模型不一定支持 Function Calling常见替代是让模型输出一段 JSON再用代码解析。这段 JSON 的解析就是很多坑的来源模型输出的 JSON 里带多余换行、带解释文字、字段名被缩写、甚至是合法 JSON 但 schema 不对。我的经验是无论用哪种协议都要在模型输入里把工具调用格式用 few-shot 示例固定住并在代码里做一层宽容的解析器既要支持正则抽取 JSON也要支持失败后要求模型重试。3.5 记忆存储上下文、向量库还是业务数据库记忆持久化的决策取决于你要记什么。只记当前对话放在上下文就够了要记录用户长期偏好业务数据库就能解决要让 Agent 能在海量历史文档里检索相关信息才轮到向量数据库登场。很多团队一听说 Agent 要记忆立刻拿着 PDF 去搞向量化搞了半个月发现业务根本不需要语义检索反而因为检索结果太“相关”而带偏了 Agent 的回答。正确的姿势是先列清单这个 Agent 必须记住哪些信息、信息多久有效、用户是否会更新信息。清单列完存储选型基本也清楚了。3.6 任务生命周期同步调用、任务队列还是常驻进程Agent 任务的运行模式单独拎出来是一个决策点。简单问答型 Agent 适合同步调用请求进来直接返回耗时任务比如批量处理文档、自动发布内容必须丢进任务队列异步执行需要长期驻留、主动感知状态变化的 Agent比如监控型 Agent则要设计成常驻进程。我在这块踩过大坑一开始把所有 Agent 任务都做成同步 API结果业务方发了 100 条批量请求直接把上游 API 和下游工具同时打爆。后来改成两步走第一步 API 只接受任务并返回 task_id第二步由 Worker 进程去消费任务队列逐个调用模型和工具这才算把任务生命周期理顺。3.7 可观测性与评估你凭什么信任它最后一个决策点也是最容易被欠债的可观测性与评估体系。Agent 的每一轮循环都涉及模型调用和工具调用任何一次输出异常都可能导致结果全错。没有完整 trace 的 Agent 系统线上出问题的时候基本只能靠猜。我建议每个 Agent 项目从第一天就记录以下内容完整的输入输出、每一轮的模型返回内容、工具调用参数和返回结果、每次调用消耗的 token 数、单次任务的步数和耗时。评估层面则要构建一个覆盖典型场景的测试集每次改提示词或换模型都跑一遍回归。没有评估集的 Agent 优化本质上就是在赌运气。4. 最小可运行的 Agent手写一个 ReAct 循环把决策点聊完直接上一段能跑的代码。很多人觉得手写 Agent 很难其实核心循环并不复杂我用一个最简单的 ReAct Agent 来展示它的骨架。这段代码省掉了框架层方便你理解真正发生的事。4.1 为什么从手写循环开始用框架之前我强烈建议先手写一遍核心循环。因为 LangChain 这类框架把 ReAct 封装得太黑盒出了问题你根本不知道在哪一步只有自己写过一遍才能理解框架里每个组件到底在做什么。理解了原理之后再换框架或自研心里都有底。4.2 核心循环代码与执行逻辑以下代码用 Python 和 OpenAI 风格的 SDK 写核心逻辑不依赖特定某个框架。工具集只准备两个一个查天气一个做计算。import json from openai import OpenAI client OpenAI() TOOLS { # 注意这里用 lambda 只是为了演示生产环境请换成真实 API get_weather: lambda city: { city: city, temperature: 26, condition: 多云 }, calc: lambda expr: {result: eval(expr)}, } SYSTEM_PROMPT 你是一个可以调用工具完成任务的助手。 工作流程如下 1. 先输出 Thought简要说明你这一步的思考。 2. 如果需要调用工具只输出一行 JSON格式为 {tool: 工具名, params: {参数名: 参数值}} 3. 如果已经拿到足够信息直接输出最终回答。 必须使用中文回答。 def run_agent(user_input, max_steps5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, # 生产环境请按实际选型替换 messagesmessages, temperature0, # Agent 场景建议用低温减少随机性 ) content resp.choices[0].message.content # 尝试把模型输出解析成工具调用 try: action json.loads(content) except json.JSONDecodeError: # 解析失败说明模型认为可以直接回答把结果返回给用户 return content tool_name action[tool] params action[params] # 执行工具 tool_result TOOLS[tool_name](**params) # 把工具调用和工具结果都放回消息序列 messages.append({role: assistant, content: content}) messages.append( {role: tool, content: json.dumps(tool_result, ensure_asciiFalse)} ) return 已达到最大步数任务可能未收敛。 print(run_agent(北京今天多少度顺便计算 23 * 17 等于多少。))这个循环的核心逻辑只有四步把最新的模型输出尝试解析成 JSON解析成功就执行对应工具把工具结果写回消息序列再送给模型推理。直到模型输出无法被解析成 JSON说明它已经准备直接回答用户循环结束。代码里的max_steps非常关键它就是最基础的安全护栏。没有这个上限模型一旦陷入重复调用同一个工具的死循环你就要眼睁睁看着 token 烧钱。这是所有 Agent 项目都必须有的底线。另外要特别强调示例里calc工具直接用了eval生产环境绝对不要这么写eval执行任意代码的风险太高了。真实场景应该用表达式解析器或者直接调计算引擎。4.3 把记忆、工具、护栏加回去之后上面这段代码只有最核心的循环连记忆都只是 context 累积。你把七要素套进去看会立刻发现缺了什么工具集太薄、没有长期记忆、没有评估、护栏只有 max_steps。工程化就是在这个骨架上逐步加厚。工具层要改成注册中心模式用统一 schema 描述工具让模型按 schema 生成参数记忆层要在循环里加入摘要和持久化反馈层要捕获工具异常并转成结构化错误信息护栏层要加白名单校验和审计日志。每加一层代码都会更复杂但稳定性也会明显提升。5. 常见问题与排查技巧实录这节我把自己实际遇到过的典型问题和排查思路整理成一份速查表每一条都是真金白银换来的经验。5.1 Token 消耗失控症状是任务没跑几步账单先飞了。最常见的原因是循环没有步数上限或者每次循环都把完整历史塞进上下文导致 token 数随步数指数膨胀。排查思路先看 trace 里单次任务的 token 曲线如果在某个工具调用后 token 暴涨基本就是历史消息重复累积或工具返回结果太长。解法是给上下文加摘要压缩对工具返回结果做截断并严格控制循环步数。建议对每个 Agent 任务设定 token 预算超过预算直接终止并告警。5.2 工具返回结构化数据却解析失败模型输出的 JSON 经常不干净要么带前后缀文字要么把字段名写成相近词。这个问题在开源模型上尤其明显。排查思路把模型原始输出打出来看确认是格式问题还是 schema 问题。如果是格式问题用宽容的 JSON 抽取器先正则取大括号片段再解析解析失败就追加一条“请只输出 JSON不要解释”的消息让模型重试如果是 schema 问题把工具参数描述写得更细并加 one-shot 示例。5.3 Agent 陷入死循环典型表现是同一个工具被反复调用或者在一个错误结果上反复重试。根本原因通常是模型无法从工具结果里获得进展信号。排查思路一是看工具返回内容是否足够信息量如果工具返回空结果模型很容易原地打转二是检查系统提示词里是否明确写了“如果某工具连续失败两次请换一种方式或直接回答用户”三是在代码里加连续同工具调用次数的检测。我给每个 Agent 任务都加了步数上限同时把 max_steps 的默认值调小宁可任务失败也不要死循环无限烧钱。5.4 上下文被无效信息污染有些信息看起来有用塞进上下文反而让模型决策变差。最常见的例子是向量检索出一堆相似但不相关的文档模型被这些噪声带偏。排查思路给检索环节加相关性阈值过滤低于阈值的文档直接不进入上下文检索结果按和当前问题的相关度重新排序如果上下文太长先让模型做一次摘要再参与决策。很多人只关注“能不能检索到”忽略了“检索到的内容会不会干扰推理”这个坑一踩一个准。5.5 从 Demo 到生产任务队列、限流与人工兜底最后说一个经常被忽视的问题Agent 从 demo 到生产的落差。demo 里一个请求同步跑能出结果生产里一秒来几十个请求模型 API 限流、工具 API 超时、任务堆积全是新问题。我的建议是尽早把 Agent 任务改造成异步模式通过任务队列控制并发。模型调用要加限流和重试工具调用要加超时和熔断。更重要的是人工兜底给每个 Agent 任务设计一个评审态高风险的执行结果让用户或运营确认后再生效。不要指望 Agent 百分百可靠设计一个可控的失败路径比追求完美输出更实际。我个人做 Agent 项目这么久的体会是模型的智力水平会不断上涨但工程问题永远是那套老生常谈的结构性问题。把七要素拆明白把七个决策点想清楚比追着各种新框架跑要重要得多。如果你现在正在做 Agent建议先别急着接业务花一个下午把你的架构对照七个要素和七个决策点捋一遍大概率能提前发现好几个会在线上暴雷的点。