AI Agent 这两年被聊得太满，满到很多刚入行的朋友以为它是个新模型的名字。其实不是，它是一套工程结构：把大模型的推理能力、外部工具的动手能力、以及一套能自我纠错的循环拼在一起，让系统从"能答"变成"能办"。前阵子技术社区里流传的一份 AI Agent 系统笔记，据说收藏数冲到了两万五以上，我翻完之后的第一反应不是"写得好"，而是"终于有人把散落在各处的工程经验串成一条线了"。市面上讲 Agent 的文章，要么停在概念层，画个框图说这是感知那是决策；要么直接甩一个框架 demo，跑通了天气查询就没了下文。真正难的部分——工具描述怎么写成模型能懂的、上下文涨到八千 token 之后怎么压、评测怎么在非确定性系统上做——基本没人系统讲。这篇我按自己的落地经验，把这份资料里值得抄的部分、我自己踩过的坑、以及可以直接上手的骨架，完整铺一遍。适合已经会用 API 调模型、但一上真实业务就发现"它怎么老是不按我说的做"的开发者，也适合正在评估要不要把某个流程交给 Agent 的团队负责人。
1. 先搞清楚这套东西到底在解决什么问题
很多人第一次接触 AI Agent，是被"自主完成复杂任务"这句话吸引的。但我见过太多项目死在这一步：需求方以为丢一句话进去，系统就能自己规划一个月的工作；开发者照着 demo 搭了个循环，结果模型第三步就开始胡编工具名。问题不在模型，在于大家对 Agent 的能力边界没有一个物理直觉。
1.1 从"会聊天"到"会办事"的那道分水岭
单轮对话的本质是一次函数映射：输入一段文本，输出一段文本，中间没有状态，没有反馈，也没有"做错了再改"的机会。Agent 的本质是一个带反馈的循环：观察当前状态，决定下一步动作，执行动作拿到结果，把结果塞回上下文，再决定下一步。差别听起来很小，实际影响巨大。
举个我实际做过的例子。用户说"帮我查一下上周那笔退款到哪一步了"。纯对话模型只能回你"请联系客服"或者干巴巴地问"请问订单号是多少"。而一个搭好的 Agent 会这样走：第一步，它意识到自己缺订单号这个关键参数，于是调用订单查询工具按用户身份拉最近订单；第二步，拿到三条候选订单，它判断"上周"这个时间限定，筛出最可能的一条；第三步，调用退款状态接口；第四步，根据返回的状态码决定是直接回复用户，还是再查一次物流或支付渠道。整个过程四到五步，每一步都可能失败，每一步都需要根据上一步的真实返回做决策。
这个"根据真实返回做决策"就是分水岭。它意味着系统必须处理不确定性：工具可能超时，可能返回空，可能返回一个模型没见过的错误码。把这些情况都覆盖住，才叫工程，否则只是演示。
1.2 四件套：模型、规划、记忆、工具，缺一不可但权重不同
行业里通用的拆法是四层：模型是大脑，负责理解和决策；规划负责把大目标拆成可执行的步骤序列；记忆负责管理上下文和跨会话的信息；工具是手脚，负责真正对外部世界产生作用。
这四层在纸面上是并列的，在实际工程里的投入比例完全不是。我的经验是：工具层占五成精力，记忆层占三成，规划和模型各占一成。原因很朴素——工具是模型和真实世界之间唯一的接口，工具描述写得含糊，模型就必然乱调；上下文管理做不好，跑到第五步就开始忘记前面查过什么，然后重复调用同一个接口，把配额耗光。
规划这一层，很多资料会介绍复杂的树搜索、多路径回溯。我建议新手先绕开。真实业务里八成的任务只需要线性的、最多带一个条件分支的步骤序列，为了那两成的复杂场景上一套重型规划器，调试成本会把你劝退。等你的 Agent 在简单场景下稳定跑了两个月，再考虑加。
1.3 为什么这类系统性资料会被大量收藏
我观察到一个现象：关于 Agent 的单点教程遍地都是，但把"从零到能上线"整条路走完的资料极少。大家收藏的其实不是知识，是路径。一份好资料的价值在于它告诉了你顺序：先做什么、后做什么、哪一步可以先糊弄过去、哪一步必须死磕。
比如工具注册这件事，几乎所有教程都告诉你要写 JSON Schema。但没人告诉你，工具名最好用动词开头的短句，别用驼峰缩写；参数描述里要写清楚单位和格式，别指望模型猜"时间戳是秒还是毫秒"；每个工具的错误返回必须是模型能读懂的自然语言，而不是一个 HTTP 500。这些细节单看都是小事，攒在一起就是"为什么我的 Agent 老出错"和"为什么我的 Agent 挺稳"的差距。
2. 内核拆解：一个能跑的 Agent 循环长什么样
抛开所有框架，Agent 的核心就是一个 while 循环加一个工具注册表。理解了这个，再看任何框架都不会迷路，因为你一眼就能看出它在哪一层做了封装、封装掉了哪些你能控制的东西。
2.1 ReAct 循环：思考、行动、观察，每一步都在做什么
ReAct 是目前最主流也最实用的范式，核心就三步轮转：Thought（想一下现在缺什么）、Action（调一个工具）、Observation（看工具返回了什么）。我把这三步翻译成人话：我现在手里有什么信息、我下一步该干什么、干完之后情况变成什么样了。
关键点在于，Thought 这一步不是装饰。很多实现为了省 token 把思考过程砍掉，直接让模型输出工具调用，结果稳定性明显下降。原因是模型需要一个"显式写下推理"的位置，把隐式的判断外化，它才能在下一次调用时读到自己的推理痕迹。我做过对比，保留简短思考（一到两句话）的版本，在多步任务上的完成率比纯工具调用版本高出一截。
还有一点是循环的终止条件。必须同时设三个：模型主动输出最终答案、达到最大步数上限、连续两次调用同一个工具且参数相同（说明它卡住了）。第三个尤其重要，我见过真实系统因为少了这个判断，在一个坏掉的下游接口上死循环，把整月的调用额度打穿。
2.2 工具描述怎么写，模型才不瞎调
这是我最想强调的一节。工具调用出问题，九成不是模型笨，是描述写得烂。
先看工具名。用query_order_status而不是qryOrdSt，用create_refund_ticket而不是refund。名字本身就是最强的语义信号，模型在几十个工具里做选择时，第一眼看的就是名字。动词开头、名词结尾、全小写带下划线，这套命名约定不是为了好看，是为了让模型的注意力能精准落在动作和对象上。
再看参数。每个参数除了类型，必须写清楚三件事：格式、单位、取值范围。时间参数明确写"ISO 8601 格式，例如 2024-03-15T10:00:00Z"；金额明确写"单位：元，保留两位小数"；枚举参数把所有合法值列全，一个都不能省。我踩过一次坑，一个状态字段只写了 string，模型把"已完成"三个中文字直接传了进去，下游接口直接报错。
{ "name": "query_order_status", "description": "根据订单号查询订单当前的履约状态。当用户询问订单进度、物流、退款到哪一步时使用。订单号必须是纯数字，不含字母或短横线。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，纯数字字符串，长度 16 到 20 位。不要传用户昵称或手机号。" }, "need_logistics": { "type": "boolean", "description": "是否需要同时返回物流轨迹。用户明确问'到哪了''快递'时传 true，其余情况传 false 以节省响应时间。" } }, "required": ["order_id"] } }注意 description 里那句"不要传用户昵称或手机号"。这种负向约束看起来多余，实际能挡掉相当一部分误传。模型在信息不全时会有很强的"凑一个值填进去"的倾向，明确告诉它什么是错的，比只告诉它什么是对的有效。
最后是错误返回。工具执行失败时，不要抛异常给上层，也不要返回{"code": 500}。返回一段模型能理解的话，比如"订单号 12345 查询失败，原因：该订单号不存在，可能是用户记错了。建议：请用户确认订单号，或改用手机号查询接口。"这段文字会被塞回上下文，模型下一步就会照着建议走。这叫错误自描述，是我认为性价比最高的一个工程技巧。
2.3 记忆分层：上下文窗口不是越多越好
很多人对记忆的理解是"把历史全塞进去"。在 Agent 场景下这是灾难。原因有三：token 成本随步数线性上涨；无关历史会稀释模型的注意力；更关键的是，早期读到的错误信息会一直留在上下文里反复干扰。
我习惯分三层处理。第一层是工作记忆，也就是最近几轮的完整对话和工具返回，原样保留，这是模型判断"我现在在哪一步"的主要依据。第二层是状态快照，用结构化数据维护一个任务状态对象，比如{已获取订单号, 已查到状态, 待确认退款金额}，每步更新，以紧凑的 JSON 形式注入上下文。这层最有用，它把冗长的历史压缩成了几行关键事实。第三层是长期记忆，跨会话的用户偏好、历史工单结论，放外部存储，按需检索，绝不无脑注入。
实践中我还加了一个小机制：当上下文超过阈值时，触发一次摘要，把前面若干轮压成三五句话，但保留原始的工具调用记录 ID。这样既控住了长度，出问题时又能顺着 ID 回查完整日志。这个设计救过我几次——模型忽然说"我查过了"，我看摘要里没有，回查原始记录发现它确实查了，只是摘要把这条信息丢了。
2.4 最小可运行骨架
不用任何框架，两百行以内能跑起来。下面这个是核心循环，我删掉了业务细节，保留了结构。
import json MAX_STEPS = 8 def run_agent(user_input, tools, call_llm): messages = [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user_input}, ] last_call = None repeat_count = 0 for step in range(MAX_STEPS): resp = call_llm(messages, tools=tools) if resp.get("final_answer"): return resp["final_answer"] tool_name = resp["tool_name"] args = resp["tool_args"] # 卡死检测：同名同参连续调用 sig = (tool_name, json.dumps(args, sort_keys=True)) if sig == last_call: repeat_count += 1 if repeat_count >= 2: messages.append({ "role": "user", "content": "检测到重复调用同一工具且参数未变，请停止调用，" "基于现有信息直接给出答案，或说明缺少什么信息。" }) continue else: repeat_count = 0 last_call = sig fn = tools.get(tool_name) if fn is None: result = f"工具 {tool_name} 不存在。可用工具：{list(tools.keys())}" else: try: result = fn(**args) except Exception as e: result = f"工具执行失败：{e}。请判断是参数问题还是服务问题，并调整策略。" messages.append({"role": "assistant", "content": resp["raw"]}) messages.append({"role": "tool", "content": str(result)[:4000]}) return "任务未在限定步数内完成，已转人工。"骨架里有三个地方值得细看：重复调用检测、工具不存在时的兜底提示、以及工具返回结果的截断。截断这一条经常被忽略，某些接口会返回几十 KB 的 JSON，直接塞进去一次就把上下文撑爆，后面几步全废。我一般截到 4000 字符，同时把关键字段提前。
3. 工程落地的取舍：模型、上下文、框架、成本
跑通 demo 和上线之间隔着一整个工程。这一节讲四个我认为最影响成败的决策点，每个都给出我的选择和背后的算账过程。
3.1 模型选型：不是越强越好，是越匹配越好
一个常见误区是全程用最强模型。我做过一个粗略统计，在一个典型的三到五步任务里，真正需要强推理的只有"规划下一步"这一环，工具参数填充、结果抽取、格式化输出这些步骤，小模型完全够用。
我的做法是分层。路由层用小模型判断用户意图属于哪个大类，顺便抽取关键实体；规划层用强模型，负责决定下一步动作；执行层用小模型把工具返回的原始 JSON 转成人类可读的句子。这套组合下来，成本能压到全程强模型的三到四成，而任务完成率下降不到五个百分点。
分层的代价是链路变长、调试变复杂。如果你的日调用量还在几百次这个量级，别折腾，全程强模型，把精力放在工具和评测上。等成本真的成为瓶颈了再分。
3.2 上下文工程：比提示词技巧重要十倍
提示词工程这个词被用滥了，我更愿意叫它上下文工程。区别在于，前者关注"怎么把一句话说得更漂亮"，后者关注"模型在这一步看到的全部信息里，哪些该留、哪些该删、哪些该换一种格式呈现"。
具体三条实践。第一，系统提示词里只放全局规则和工具使用总则，具体业务约束放进工具描述里，就近生效。我见过把所有规则堆在系统提示里的写法，两千多字，模型执行时该忘还是忘，因为它在调用工具那一刻看到的最近信息是工具 schema，不是开头那段话。第二，工具要按场景裁剪。一个客服 Agent 注册三十个工具，模型的选择准确率会明显下降。我的做法是按意图先缩小候选集，每次只暴露五到八个工具，准确率立刻上去。第三，状态用结构化数据表达，别用自然语言复述。同样的信息，"已确认订单 A123，状态为运输中，预计明天送达"和{"order":"A123","status":"shipping","eta":"tomorrow"}，后者占的 token 更少、歧义更小，模型读取时也不容易漏。
3.3 框架还是裸写：我踩过的三个坑
我的结论是：第一版一定裸写，接口稳定之后再考虑上框架。
坑一，框架的抽象层会吃掉你对上下文的控制权。你以为是"添加一条消息"，实际它可能顺手加了模板前缀、做了自动摘要，导致你排查半天都不知道模型为什么看到了一个不该看到的东西。坑二，不同框架对工具调用的错误处理策略不一样，有的直接抛异常中断循环，有的静默吞掉，等你发现 Agent 莫名停下来，已经浪费两天。坑三，框架升级带来的行为变化很难追溯，尤其是 prompt 模板的微调，线上表现可能一夜之间变化。
裸写的好处是每一步你都看得见。等流程跑通、接口定型，再把稳定部分抽成模块，这时候上框架是为了减少重复代码，不是为了"看起来更专业"。
3.4 成本与时延：把账算到每一次调用上
我给一个真实量级的估算。假设一个工单处理平均走四步，每步输入上下文约 3000 token，输出约 300 token，那么单次任务约 1.2 万输入 token 加 1200 输出 token。按中等价位模型算，单次成本大致在几分钱这个量级。一天处理一万单，就是几百块的量级。
看起来不多，但这里面有两个隐藏成本。一是失败重试，如果任务成功率只有七成，剩下三成要重跑或转人工，实际成本要乘 1.4 左右。二是延迟，四步串行，每步两到三秒，用户等十秒以上就会明显不耐烦。优化延迟的手段有两个：把可以并行的工具调用合并（比如同时查订单和查物流），以及把非关键的摘要、格式化步骤挪到流式输出之后异步做。
我个人的判断线是：如果单次任务超过十秒还没给出可见反馈，就必须做流式或者分阶段提示，告诉用户"正在查订单""正在核实退款"，否则完成率再高，体验也是崩的。
4. 评测与可观测性：Agent 最难也最容易被跳过的一环
这一节是我认为最该被强调、但在各种资料里最薄弱的部分。原因很简单：传统软件测试建立在确定性上，同样的输入必然得到同样的输出。Agent 天生不满足这个前提，你不能写assert agent.run(x) == y。
4.1 为什么传统单测在这个场景下失效
同一句用户输入，模型这次调了订单接口，下次可能先问一句"请提供订单号"，再下次可能直接调了手机号查询接口。三种路径都可能是对的，也都可能产出正确结果。你没法用一条断言卡死。
我早期的做法是把温度调到零，然后写固定断言。结果是测试通过了，线上照样出问题——因为线上用户输入千奇百怪，而测试集只有那么几十条。后来我改成两层：确定性的部分（工具本身、参数校验、错误分支）用传统单测死磕；不确定性的部分（路径选择、最终答案）用统计化评测，看通过率而不是看单例。
4.2 三层评测体系：单步、轨迹、终局
我现在的评测分三层，每层关注不同的东西。
第一层是单步评测，看模型在给定上下文下选对工具、填对参数的比例。这层最容易做，也最能快速定位问题。做法是准备一批"上下文 + 期望工具调用"的样本，跑完之后算准确率。如果这层准确率低于八成，别往下测了，先把工具描述改好。
第二层是轨迹评测，看整个执行路径是否合理。判断标准不是"和标准答案完全一致"，而是"没有多余步骤、没有危险操作、没有信息遗漏"。比如一个任务本该三步完成，模型走了七步，其中三次重复查询，这就该标红。这层我一般用规则加人工抽检，因为自动判定路径合理性很容易误伤。
第三层是终局评测，只看最终结果对不对。这一层用模型判加人工复核结合，模型判负责大批量初筛，人工只看模型判为失败和有争议的样本。
下面这张表是我现在用的评测分工，可以直接参考。
| 层级 | 关注点 | 判定方式 | 通过线参考 | 出问题先查哪里 |
|---|---|---|---|---|
| 单步 | 工具选择、参数正确性 | 规则匹配 | 工具选择 90%，参数 85% | 工具名与描述、枚举值是否写全 |
| 轨迹 | 步数、重复调用、危险操作 | 规则 + 抽检 | 平均步数不超基准 1.5 倍 | 循环终止条件、状态快照是否及时更新 |
| 终局 | 最终答案正确性 | 模型判 + 人工复核 | 核心场景 85% 以上 | 上下文是否丢失关键信息、兜底话术是否误导 |
这些通过线不是行业标准，是我自己项目里跑出来的经验值，不同业务容忍度不一样。金融类的参数正确性我要求到 95% 以上，内容类的东西 80% 就能接受。
4.3 日志要记什么，才不至于出事时两眼一抹黑
Agent 出问题时最痛苦的不是它错了，是你不知道为什么错。我要求日志必须包含这几项：每次调用一个全局 trace id，能串起整条链路；每一步的完整输入上下文（压缩后存，别存全量原文，否则存储成本受不了）；模型原始输出，包括思考部分；工具调用的名称、参数、耗时、返回状态；以及本步的 token 计数。
还有一项容易被漏掉：版本号。系统提示词版本、工具集合版本、模型版本，三个都要记。有一次线上表现突然下滑，查了半天以为是下游接口变了，最后发现是提示词被人改了一句话。有了版本号，五分钟就能定位。
另外强烈建议做一个"回放"能力：拿日志里的一次真实 trace，原样重跑一遍。不一定能复现完全相同的路径，但能验证你对问题的判断对不对。这个功能开发成本不高，排查效率提升非常明显。
5. 场景适配与问题排查实录
最后一节讲落地。技术再好，用错场景就是白费。我见过太多项目在一个根本不适合 Agent 的流程上死磕，最后归因为"模型能力不够"，其实是选错了靶子。
5.1 什么样的流程适合交给 Agent
我总结四个条件，同时满足才值得做。第一，流程有明确的可验收结果，比如"退款工单已关闭""数据报表已生成"，而不是"写一份有洞察的分析"这种没法判定的。第二，涉及多个外部系统，需要人工来回切换，这正是 Agent 最能省时间的地方。第三，容错空间存在，错了能回滚或者有人复核，一次性、不可逆的操作（比如直接打款）绝对不能让 Agent 自主完成。第四，有足够的调用量，一天十次的流程，人工做更划算。
反过来，什么不适合？决策链条极长且每步都依赖专业知识判断的，比如复杂的方案设计；需要承担明确责任的，比如涉及合规审核的结论；以及输入极度不规范、大量依赖人类常识补全的。这几种情况下，Agent 更适合做"预填 + 建议"，最后一步交给人。
5.2 常见问题速查
下面这张表覆盖了我实际遇到过的高频问题，按现象查就行。
| 现象 | 可能原因 | 排查动作 | 处理办法 |
|---|---|---|---|
| 反复调用同一个工具 | 工具返回值没提供有效信息 | 看该步的工具返回内容 | 让错误返回带明确建议，加重复调用熔断 |
| 明明有工具却自己去编答案 | 工具描述太模糊，模型没识别出场景 | 检查 description 里的使用时机说明 | 补一句"当用户询问 X 时使用本工具" |
| 参数格式错，接口报错 | 描述里没写格式和示例 | 抽查失败样本的入参 | 补示例值、加枚举、加负向约束 |
| 跑到第五步开始乱来 | 上下文过长，早期信息被稀释 | 统计上下文 token 曲线 | 加状态快照，超阈值触发摘要 |
| 直接答复但内容不完整 | 终止条件太松，模型急着收尾 | 看最后一步的思考内容 | 在系统提示里明确"信息不全时必须追问" |
| 时延忽高忽低 | 某一步的工具本身慢 | 按步骤统计耗时分布 | 拆分慢接口、能并行的并行、加超时 |
| 换模型后表现下降 | 新模型对工具协议支持细节不同 | 对比同一批样本的输出 | 回滚并做小流量灰度 |
5.3 几条不那么书面但很管用的经验
第一条，把"我不确定"当成一个正式输出。很多实现里，模型只有"调工具"和"给答案"两个出口，于是它在不确定时被迫二选一，往往选错。我给它加了第三个出口：输出一句"我需要向用户确认 X"。加上这个之后，误答率明显下降，用户体验反而更好，因为它在该问的时候问了。
第二条，给每个工具加一个"预估耗时"字段写进描述里。这听起来很怪，但确实有用：当模型知道某个工具要五秒、另一个只要两百毫秒时，它会倾向于先调快的拿信息，这不是我们教的，是它自己从描述里推断出来的。这类隐式优化不需要额外代码。
第三条，上线前一定要做一次"坏接口演练"。把所有下游工具手动改成返回超时或者乱码，看 Agent 会怎么反应。我第一版就是这么发现问题的——三个工具同时挂掉时，它开始自己编造订单状态，因为上下文里没有任何提示告诉它"工具挂了要明说"。后来我在系统提示里硬加了一条：工具连续失败时，必须如实告知用户当前无法查询，禁止推测。
第四条，别急着做多智能体。多 Agent 协作听起来很美，分工明确、各司其职。实际做下来，光是让两个 Agent 之间的信息传递不失真就够喝一壶，而且调试难度是单 Agent 的数倍。我的经验是，除非你的任务真的能清晰切成几个互不依赖的子领域，否则单 Agent 加更多工具，稳定性远高于多 Agent。等单 Agent 的上下文实在撑不住了，再考虑拆。
第五条，也就是最后一条，把人工兜底做成默认路径而不是异常路径。系统中应该始终存在一个"转人工"的出口，并且这个出口的触发条件要宽松一点。我见过为了追求自动化率把兜底阈值调得极高的配置，结果是用户在系统里绕了十分钟最后还是要找人，体验比一开始就转人工差得多。自动化率是个好看的指标，但用户真正在意的是问题有没有被解决。
我个人在这个方向上折腾了两年多，最大的体会是：Agent 的难点从来不在模型，而在你愿不愿意把它当成一个有脾气的新同事来对待——你得把话说明白，把工具备齐，把边界划清楚，还得允许它在不确定的时候举手问一句。那些收藏量很高的系统资料，真正值钱的也往往是这些"怎么把话说明白"的细节，而不是什么新范式。
