Agent开发真正要学的五件事：边界、控制流、记忆、工具与评测

做了近两年Agent开发我有一个很反直觉的体会真正卡住人的从来不是模型能力也不是某个框架的新特性而是那些看起来特别基础、特别容易一带而过的事。两年前我刚接触Agent时以为核心是写提示词后来以为是搞懂LangChain的源码再后来以为是追各种新框架。等到自己从零搭过、上线过、也给线上事故背过锅之后才慢慢收敛出一个结论——Agent开发真正要学的其实就五件事。这篇文章不是框架教程也不是某个项目的复盘而是把我这两年里反复踩、反复琢磨的东西重新梳理了一遍。如果你正在学Agent或者已经开始搭自己的智能体但总觉得学了一堆东西还是串不起来那这篇文章大概率对你有用。我会尽量用当时我怎么想的、后来为什么改的方式来写少一点概念堆砌多一点可以拿去用的东西。1. 定义边界很多人做了半年Agent做的其实还是假Agent先把一个最容易忽略的问题摆在最前面你做的到底是不是Agent我见过太多项目号称是Agent实际只是给模型套了一层角色设定然后循环调几次API。也见过反过来的情况——明明就是个多轮对话机器人非要在PPT里叫Agent。边界不搞清楚后续所有设计都会跑偏。所以第一件事不是学框架而是把Agent到底是什么、和之前的东西差在哪想明白。1.1 Agent和普通LLM应用真正的分水岭普通LLM应用比如最常见的ChatBot核心是输入Prompt输出回答整个控制流掌握在用户手里。用户问一句模型答一句。模型不主动调用任何东西也不决定下一步该做什么。RAG应用稍微进了一步但本质仍是检索—拼接—生成这条固定管线用户问题进来系统去向量库捞相关文档把文档塞进上下文让模型据此回答。检索是检索回答是回答先后顺序写死在代码里。Agent不一样分水岭在于模型要自己决定下一步做什么。这个决策权从人手里转交给模型是整个开发思维的转折点。Agent拿到一个目标后可以自己判断要不要检索资料、要不要调计算器、要不要问用户澄清、先用哪个工具、失败之后重试还是换一条路。它是一个带控制权的循环而不只是一次性的生成。我用一个朴素的标准判断手头项目是不是Agent**如果把模型换成随机回答控制流还能不能显著影响最终结果。**如果能说明系统里Agent味很重如果整个流程就是一问一答那无论怎么宣传还是普通应用。1.2 Workflow、RAG和Agent的边界其实就一句话很多人把Workflow和Agent混在一起是因为它们都有多条处理步骤。区别只在步骤的确定性和模型决策权。Workflow是蓝图提前画好的步骤A做意图识别步骤B用工具查天气步骤C做结果整理。每一步做什么工程师在开发期就拍板了。Agent是蓝图边跑边画的模型拿到目标之后动态拆解、动态决定调用哪个工具同一个任务今天可能走三步明天可能走五步路径不完全固定。所以我的结论是Workflow适合流程稳定、容错要求高的场景比如电商退款、工单流转。RAG适合知识密度高、但答案基本确定的场景比如企业知识库问答。Agent适合路径不固定、需要临场组合能力、步骤可能动态变化的场景比如个人助理、复杂编排、代码辅助。这三者不是先进和落后的关系是成本和可控性的取舍。Agent在正确率、延迟、可解释性上都要付出代价换来的是灵活性。你如果场景用固定流程就能覆盖硬上Agent反而给自己挖坑。1.3 伪Agent的三个典型症状判断完概念再对照一下实际项目常见的三种伪Agent**第一个症状只有Prompt没有状态。**模型始终在无状态地猜下一步每次调用都是孤立的输入输出没有中间记忆没有任务上下文。这种即使套了Agent框架也只是换个姿势调API。**第二个症状循环写死了。**外面一个for循环里面固定三步生成、调工具、给结果。没有反思机制没有步骤记忆失败就break。这种更像是自动化脚本不是Agent。**第三个症状模型决定但没有兜底。**让模型自主决策却完全没有异常处理、超时控制、用户确认机制。一旦步骤错了一路错下去最终给用户一个莫名其妙的结果。这个我后面专门讲属于运行边界问题。先把这个边界立住后面谈控制流、记忆、工具、评测才有共同语言。你永远没法优化一个说不清楚是什么的系统。2. 控制流是Agent的骨架先手写一遍再谈框架选型第二件事是控制流。我直接给一个可能有点冒犯的建议**先别急着上LangChain、CrewAI这类框架先手写一遍最简单的ReAct循环。**手写过之后你对框架里那些抽象概念的理解会完全不同。因为Agent框架做的事情本质就是帮你管理模型决策循环这件事你不理解循环就用不好框架。2.1 ReAct循环最朴素的自主决策闭环ReAct这个名字来自论文《ReAct: Synergizing Reasoning and Acting in Language Models》核心思想是让模型在推理和行动之间交替。翻译成代码逻辑就是下面这个循环def run_agent(task): messages [{role: system, content: SYSTEM_PROMPT}] messages.append({role: user, content: task}) for step in range(MAX_STEPS): response llm.chat(messages) action parse_action(response) # 期望模型输出指定格式Thought/Action/Action Input if action is None: # 模型认为任务完成 return response.final_answer result execute_tool(action) # 调用对应工具 messages.append(response_message) messages.append({role: tool, content: result}) raise TimeoutError(超过最大步数)就这么一个循环所有Agent框架的底层都逃不出它的变体。你不用框架也能实现无非是自己定义模型输出的解析格式、管理消息队列、写工具注册表。这个过程能帮你搞清楚几个关键问题模型输出什么格式才能可靠地被解析JSON常有格式问题带转义的Markdown也常翻车自己做一遍就懂了。工具执行结果如何回填到上下文循环什么时候停模型说done就真done吗我实际写下来的经验解析格式别用太复杂的自由文本尽量让模型输出结构化JSON并且在Prompt里给一个严格的JSON示例。另外一个容易踩的坑是工具返回结果可能很长直接塞进上下文会爆窗口后面记忆章节会讲怎么处理。2.2 Plan-and-Execute和Reflection当单轮循环不够用ReAct适合步骤在10步以内的任务。任务一旦复杂单轮ReAct会暴露出一个问题**每一步都重新短视决策容易迷失全局方向。**比如一个调研竞品并输出报告的任务模型可能在第10步还在调搜索API不知道第1步搜索的结果已经足够支撑结论了。所以有了Plan-and-Execute模式先让模型一次性产出一份Plan然后按照Plan去执行每一步执行完再根据结果决定是继续还是修订Plan。它和ReAct的差别是ReAct是边想边干Plan-and-Execute是先规划再分步干干的过程中允许改计划。Reflection反思模式是我后来才体会到好处的每一步执行完之后额外问一轮模型上一步结果符合预期吗有没有遗漏然后在下一轮决策时把反思结论拼进去。代价是额外的时间和Token收益是能纠正模型自己跑偏的趋势。在容错要求高的流程里这个代价值得花。我的用法是分场景场景推荐控制流理由单工具调用、问题明确单个LLM调用工具不需要循环多步骤、步骤动态ReAct循环灵活路径不固定多步骤、要全局规划Plan-and-Execute防止短视结果可靠性优先ReActReflection多一轮纠偏代价高一些2.3 Harness不是Agent本体但决定了运行的边界热词里有个「harness和agent区别」很多初学者确实搞混。Agent和Harness不是一回事。Agent通常指模型、Prompt、工具集合、记忆这些智能体内在的东西。Harness指承载Agent运行的那层执行环境包括循环调度、工具权限管理、限流、缓存、日志、超时终止、错误恢复、人工介入接口。你可以把Agent理解成人Harness理解成职场规则和基础设施。人再能干没有办公系统、审批流程、出差报销这些基础设施也没法高效工作。这个问题在开发中很容易被忽略因为框架默认给你一套Harness你几乎不感知它的存在。但到线上就麻烦了Agent陷入死循环时Harness能不能及时终止工具调用进入未处理异常时Harness会不会吞掉错误导致用户拿到一个看似正常其实出错的答案某个工具连续失败时Harness有没有熔断机制这就能解释为什么会有「agent execution terminated due to error.」这种报错成为搜索热词——Agent在执行过程中出错被终止恰恰是Harness机制在起作用。真正合格的做法是把超时、重试、熔断、终止条件当成一等公民来设计而不是事后补丁。2.4 多Agent协作不是人越多越能干最后说多Agent。我看到太多人一上来就设计三个角色规划Agent、执行Agent、审查Agent。结果Token烧得飞快流程复杂到无法调试效果还不如单个Agent。原因很简单每一次多Agent交互都是一次信息在模型之间的传递传递必然伴随损失和延迟。我的建议是单Agent能干的绝不拆成多Agent。必须拆的场景通常是角色技能差异明显或者有天然并行需求。比如一个Agent检索资料、一个Agent做数据分析最后汇总。多Agent之间的通信协议要设计得极其简单能传结构化消息就不要传自然语言长文。我自己做多Agent时最大的教训是Agent之间的聊天看起来很像人实际是最大的效率黑洞。每轮消息都是Token每轮都可能理解偏必须加一个协调者去收敛结果而不是任由几个Agent自由讨论。3. 记忆不能一招吃遍天把读写成本拆开看就清楚了第三件事是记忆体系。这是热词里「agent记忆框架以及选型」「记忆中短期、长期、永久记忆如何实现」的高频来源。说实话记忆是个需求非常多、但网上教程普遍碎片化的方向。我刚开始做Agent时想的很简单Agent不记得之前聊过什么那就把聊天记录全部存起来每次全塞进上下文。等对话长了Token超了我开始做截断截断后质量下降了我开始做摘要摘要也长了我开始做向量检索。到最后才发现记忆不是存下来就完了它本质上是一套带读写成本的分层存储系统。3.1 短期记忆在上下文窗口里做工程短期记忆最直观就是把最近几轮对话直接放进上下文。实现简单但问题是有人贪多把几十轮历史全塞进去又费Token又稀释当前指令的注意力。工程上可以做两件事滑动窗口只保留最近N轮完整的消息。N的选择要看你的模型窗口和任务复杂度通常对话类任务10~20轮够用。关键信息抽取每轮对话后用一个小模型把用户偏好、未完成任务、关键数据抽成结构化字段放进系统Prompt的固定区域。我最常用的做法是滑窗状态变量滑窗负责保留最近上下文状态变量负责携带用户核心信息。比如用户说我住杭州预算5000就把user_profile更新一次之后所有轮次都能看到。3.2 中期记忆摘要和结构化存储当对话超过窗口上限或者任务跨多天需要压缩历史时摘要就登场了。但摘要要小心无脑让模型总结一下之前的对话会把细节全磨平尤其是数值、偏好、术语这类关键信息。我的做法是分级摘要保留原始关键消息的引用ID摘要里不写原文但存指针。需要细节时去原始记录里捞。摘要Prompt要强制输出固定结构任务背景、已确认信息、待办事项、用户偏好、风险点。结构化摘要比自由文本摘要的可用性高一个量级。中期记忆还有一个常被忽略的痛点什么时候触发摘要。不能等Token快爆才摘要要提前设置阈值。比如窗口上限8K4K时就触发一次压缩留出余量给后续工具返回。3.3 长期记忆向量检索只是入口不是全部长期记忆通常指跨会话、长期沉淀的用户画像、历史偏好、知识偏好。最流行的实现是把历史记忆embedding化存入向量库每次任务开始时做相似度检索。这套方案能跑但我用下来有两个坑第一个坑是检索结果不可控。向量检索按相似度返回片段片段之间可能重复、矛盾、或者缺少必要的上下文。检索结果直接塞进上下文会让模型被不相关内容带偏。解决方法是做一层重排序或者干脆用LLM对检索结果做相关性过滤。第二个坑是记忆的一致性。同样一条用户偏好可能在三个月前被记录为喜欢简洁风上个月又变成喜欢详细解释。如果向量库里两条都存着模型可能选错。这件事没有完美解法但可以缓解给长期记忆条目加时间戳检索时按时间加权。选型上大多数项目从Postgrespgvector起步就够没必要一上来就上独立的向量数据库。等到数据量上了千万级再考虑专用的向量库。3.4 记忆写入和遗忘最容易被忽略的一环记忆不只有读还有写和遗忘。我见过太多项目只做了存的设计没有为什么要存这条的过滤逻辑。结果向量库里塞满了垃圾检索质量直线下降。我的经验是写一条记忆时预设几个问题去过滤这条信息是否会在未来任务中被复用它是事实还是临时状态如果存了下次检索时会不会造成误导这条信息有效期多久有效期尤其关键。我现在实现记忆时每条记忆都带expires_at到期了就归档或删除。比如用户下周出差去上海这种临时信息过期后还躺在长期记忆里就会干扰后续判断。遗忘和写入一样都是系统主动设计出来的不是等着自然失效。4. 工具调用与SkillAgent的能力上限由工具边界决定第四件事也是我认为最接近实战核心的一件事工具调用。Agent模型本身不能执行任何操作它所有影响真实世界的能力全部通过工具来实现。你把工具边界划到哪Agent的能力就到哪。所以工具层的设计质量直接决定Agent的可用性。4.1 工具调用不是调个API是给模型造可控的外接大脑很多新手以为工具调用就是把Function列表传给模型。这是API层面的理解不是工程层面的理解。工程层面要处理的事至少包括工具描述质量。**同一个函数描述是获取天气还是根据城市名获取实时天气支持5天预报模型调用准确率完全不同。**工具描述是给模型看的说明书要用模型能理解的、包含边界条件和返回结构的语言去写而不是程序员脑中的注释。参数校验。模型生成的参数经常缺字段、格式错、超出枚举范围。工具层必须有一套严格校验不接受任何模型以为对了的参数。返回结果的大小控制。工具返回一个超大JSON一下塞爆上下文是整个工具层最常见的翻车原因。解决办法是工具返回前先做裁剪、截断或摘要只回传必要字段。我做工具调用的心得是先给工具做一层适配器。上层统一接JSON格式下层适配不同的API、SQL查询、文件操作。模型不直接面对底层系统的复杂性只面对适配器暴露的简洁界面。这样调试时也能快速定位是模型选错工具还是工具执行出错。4.2 Skill到底跟工具、Prompt有什么区别「skill和agent的区别」这个关键词热度很高说明很多人把Skill当成另一个神秘概念。我的理解比较朴素工具Tool是单一可执行动作。比如搜索网页发送邮件。技能Skill是一组可复用的动作编排通常包含几个步骤的调用序列、前置条件、后处理逻辑。比如调研一个行业趋势这个Skill内部包含搜索行业报告、抓取重点数据、生成摘要、整理成结构化笔记四个动作。区别在于粒度工具是原子的Skill是流程化的。Skill的价值在于把Agent高频使用的动作模式固化下来避免每次让模型临场现想、临场组合。它像是给Agent预置的肌肉记忆。在实际开发中我的经验是能用工具解决的不要先上Skill当发现Agent反复用同一套动作组合完成同一类任务再把它抽成Skill。抽早了容易过度抽象抽晚了浪费Token。什么时候抽观察日志里工具调用序列的重复度重复三次以上就值得固化成Skill。4.3 工具安全权限最小化是底线工具调用也是最容易出安全事故的地方。Agent一旦能调用真实世界的工具——发邮件、下单、写文件、操作数据库——工具的权限边界就必须收敛到一个可控范围内。热词里有「agent安全」这个词这两年Agent安全确实从学术讨论变成了生产刚需。我在框架上建议至少做三层第一层工具注册白名单。Agent只能调用配置里声明过的工具未注册的一律拒绝。第二层操作权限分级。只读类工具查日历、读文档可以放开写操作发邮件、改数据必须加上人工确认。第三层敏感操作熔断。当Agent短时间内连续调用高风险工具或参数里出现危险操作特征直接终止流程并转人工。尤其要注意的是不要让模型自己判断这个操作是否危险。模型判断不可靠安全边界应该放在Harness层用代码控制而不是写进Prompt里让模型自觉。你可以让模型决定做什么但不能让模型决定能不能做——这个决定权是人或系统自己的。5. 评测和可观测性能不能落地被这两件事卡死最后一件也是最容易被砍掉的事评测和可观测性。我见过太多Agent项目有功能Demo、有PRD、有炫酷前端就是没有评测集。这种项目一上线就变成了开盲盒——每次跑同一个任务结果都不太一样而且说不出哪里变了、为什么变。Agent是概率系统这句话听了无数遍但真正接受它的人不多。概率系统的工程化必须有评测和可观测性兜底否则永远在看起来能跑和不知道什么时候会炸之间反复横跳。5.1 没有评测集的Agent项目上线就是赌博先把评测集这件事说透。传统软件开发有单元测试、集成测试Agent开发同样需要一套固定评测集。但Agent的输出没有唯一正确答案评测集要做的是行为级判定而不是字符串级断言。我的评测集一般分三层第一层流程正确性。任务有没有走完预期的主要步骤该调的工具调了吗没该调的调了吗这个可以自动化判定。第二层结果有效性。最终输出里包含必要信息吗格式对吗关键数据存在吗可以用规则LLM-as-judge共同判定。第三层用户满意度。真实用户能不能接受这个结果。这个只能靠人工抽样或者上线后的反馈统计。评测集的构建要贴近真实场景。我知道很多团队懒用几个玩具问题当评测集那等于没测。我自己的做法是把线上用户真实问题脱敏后攒成池子再人工标注每个问题的预期行为路径和可接受答案范围。规模不用太大300~500条就能发现大量问题比跑1000条虚构问题有用得多。5.2 LLM-as-judge怎么用才不会自欺欺人用大模型来给大模型打分是目前最流行的高性价比方案但用不好就是自欺欺人。我踩过的坑有几个评分模型和被测模型同源时偏差方向一致。比如两个都是追求看起来全面的模型评分时可能被流畅度带偏而忽略是否跑题。只打分不给理由等于没评。评分结果需要附带可追溯的判断依据方便人工复核。Prompt里的评分标准写得太抽象比如回答要准确这等于没写。要写必须包含任务要求的三个信息点缺一个扣一分这种可验证标准。我现在的方案是双人制先用评分Prompt做初筛把明显不合格的捞出来然后再由人工审查初筛结果和中间步骤日志。评测不是要100%替代人而是把人力聚焦在最有问题的case上。这套方案在成本和覆盖之间比较平衡。5.3 可观测性把Agent的每次思考过程记录下来评测集是事后考试可观测性是手术台的无影灯——出了问题要能看清现场。传统日志只记录输入输出对Agent来说远远不够。Agent出问题往往出在中间决策点模型哪一步选错了工具哪一步被上下文误导了哪一步工具返回了错误格式这些细节不记录你只能对着最终错误结果猜原因。关键要记录的信息至少包括每一轮大脑的完整输入当时的系统Prompt、历史消息摘要、当前检索到的记忆片段。模型输出行动计划、工具选择、最终答案。工具执行情况参数、返回结果、耗时、错误栈。关键决策点日志为什么在这个节点选择了Plan A而不是Plan B如果有Reflection把反思结果也记录下来。有了这些Trace数据之后评测集里的失败案例才能真正用来定位问题。否则评测发现这个case挂了然后你不知道挂在哪一步评测的价值就少了一大半。我的习惯是每次排查线上问题第一步永远是拉全部Trace先把出问题的决策步骤找到再去看模型和工具层面的事。这一步做扎实之后很多之前觉得玄学的Agent问题都会变成可解释的工程问题。另外还想提醒一句可观测性是逐步加厚的不用一开始就上重型平台。我最早就是在代码里手动打JSON日志用文件按天存储出问题再翻日志。后来量大了才接专项追踪工具。工具不是重点先有记录的习惯才是重点。写在最后这两年做Agent开发我最大的变化是不再把Agent当成一个模型相关的新奇玩具而是当成一个模型驱动的分布式系统来做。控制流是骨架记忆是血液工具是手脚评测和可观测性是眼睛。骨架不正后面全是补丁眼睛不亮上线就是摸黑。如果你还在学Agent我的建议是把顺序反过来。**先学评测和可观测性再学工具和安全再碰记忆和控制流。**这个顺序和多数教程正好相反但更接近真实项目里踩坑的顺序。一套系统跑起来之后真正让你崩溃的从来不是模型不够聪明而是出了问题你根本不知道它为什么出了这个问题。最后再分享一个小技巧所有Agent项目的第一个版本不要追求智能要追求可复现。哪怕能力弱一点只要同一个输入在相同条件下能产生稳定行为路径后面的优化才有参照系。我见过太多团队第一版就追求花哨工具和多Agent协作结果后面每天在夹缝里修Bug。稳比快更容易走到终点。