Agent开发实战：工具调用、记忆体系与评测调试的五个核心

做Agent开发快两年，带过几个要上生产的项目，也面过不少觉得自己"懂Agent"的候选人。我越来越觉得，这个领域最不缺的就是玄乎的概念——什么编排、规划、多智能体协作，听着一个比一个高级，实际一梭子打出去，真正决定你的智能体能不能用、能不能扛住业务的，翻来覆去就五件事。这篇文章我把这两年踩过的坑、沉淀下来的方法论一次性说清楚：Agent本质、工具调用、记忆体系、框架选型、评测调试。不管你现在用的是LangGraph、CrewAI，还是自己裸调大模型接口，这五件事都绕不开。而且前两件，基本决定了你的Agent是"玩具"还是"产品"。

1. 看穿Agent的本质：它只是一套"大脑+手脚+笔记"的组合

1.1 大模型本身没有手脚，Agent帮它长了出来

先说一个很多新手会犯的认知错误：以为Agent就是"写一个很长的Prompt然后调用大模型"。我见过有人把几十页业务规则全部塞进系统提示词里，告诉模型"你应该先做A再做B，如果遇到C就做D"，跑出来效果极其不稳定，换一个问法就崩。

实际上，大模型本身是一个无状态的、只做"下一个token预测"的引擎。你给它一段文本，它返回一段文本，仅此而已。它不吃不喝、没有手脚，也不记得五分钟前说过什么。所谓Agent，说白了就是在模型外面包了一圈东西：给模型工具（让它能查数据库、调接口、发邮件）、给模型记忆（让它能记住和用户说过什么）、给模型一个循环（让它能反复"思考-行动-观察"直到任务完成）。

吴恩达总结的那套Agentic Design Patterns，翻译成大白话就是：反思（让模型检查自己的输出）、工具使用（让模型调用外部能力）、规划（把大任务拆成小步骤）、多智能体协作（多个模型角色配合）。名字唬人，本质都是在"模型外面那圈东西"上做文章。所以我在带新人的时候，永远先让ta画一张图：用户的一句话进来之后，经过哪些环节、什么条件下模型会调用什么工具、循环什么时候结束。这张图画不出来，代码写得再花也没用。

1.2 所有Agent的骨架都是一个"想-做-看"的循环

到现在为止，我接触过的生产级Agent，不管宣传得多高大上，核心逻辑抽出来都是同一个循环，就是大家熟知的ReAct：Reason + Act。模型先推理（我现在要解决什么问题，下一步该做什么），然后执行一个动作（调用工具、查资料），再把动作的结果拿回来作为新的观察，继续推理，直到得出最终答案。

while True: thought, action = model.think(context) # 模型输出推理和动作 if action == "finish": return format_answer(thought) # 任务完成，收尾 observation = execute(action) # 执行工具，拿到结果 context.append(observation) # 把观察结果追加进上下文

这个循环里有三个关键点，任何一个做不好，Agent就废了：

• 上下文（context）是这个循环的"白板"，每一步的思考和观察都要写在上面，模型才能接着往下想。很多框架管这一层叫harness，听起来高级，本质就是模型外面那层控制壳，负责把"白板"维护好、把工具调用接好。
• 退出条件必须明确。我见过太多Agent"死循环"，就是因为没给action限定枚举值，模型每次换一种说法说"我还需要再查一下"，token烧到天荒地老。我给动作类型只留三类：调用工具、给出中间结论、结束任务。
• 工具执行结果一定要结构化成文本再喂回给模型，不要直接把原始JSON乱糟糟地拼上去，模型读不懂，会开始瞎编。

只要你能把这个循环跑通，并且把每一步的日志都打出来，你其实就已经掌握了Agent开发至少六成的核心。后面学什么框架，无非是在这个循环外面加调度、加状态管理、加并行，骨架从来没变过。

1.3 规划能力不是越复杂越好，复杂规划会放大错误

很多人一上来就想着做"超级规划器"：让模型把用户需求拆成一个DAG任务图，多个任务并行执行，每个任务再派一个子Agent。这种架构确实性感，但你自己算一笔账：大模型每一步决策都有出错概率，哪怕单步准确率是95%，一个任务被拆成五个步骤，累积准确率就掉到77%，如果再引入并行和子Agent，错误的组合爆炸式增长，最后你根本不知道是哪个环节出了问题。

我现在的原则是：先跑通"单层循环+少量工具"的极简架构，确认主链路稳定以后，再根据业务需要逐步引入状态机（比如LangGraph里的StateGraph）去管理分支和条件。规划的复杂度应该跟着业务走，而不是跟着想象力走。你做一个查快递的Agent，根本不需要规划器；你做一个能自主完成月度经营分析报告的Agent，才需要考虑把"取数-清洗-分析-出图-写结论"拆成阶段。顺序永远是从简单到复杂，而不是反过来。

2. 工具调用：Agent和真实世界之间唯一的桥

2.1 工具定义写得好不好，直接决定Agent的上限

把工具调用做好，是我认为Agent开发里性价比最高的一件事。你给模型的能力全部要通过工具来体现，工具定义的质量直接划定了Agent的能力边界。连Cursor这种IDE都开始把Agent模式做成核心卖点了，可见工具调用这个方向在真实产品里的渗透力有多强。

现在主流大模型都支持结构化工具调用（Function Calling），本质是你在API请求里传一个工具列表，每个工具用JSON Schema描述——包括工具名字、功能描述、参数约束。模型不会真的去执行这个工具，它只负责"决定"要不要调用、传什么参数，然后把结构化的调用请求返回给你，由你的代码去执行。

一个标准的工具定义长这样：

{ "name": "query_order_status", "description": "根据订单号查询订单的当前状态。当用户询问物流、发货、签收等订单进度信息时使用。", "parameters": { "type": "object", "properties": { "order_id": {"type": "string", "description": "用户的订单号，通常是16位纯数字"} }, "required": ["order_id"] } }

看起来简单，但魔鬼在细节里。我踩过的第一个大坑是description写得太敷衍。比如上面这个工具，如果description只写"查订单状态"，模型在用户说"我的快递到哪了"的时候，很可能会犹豫该用它还是别的什么工具。description里一定要写清楚三件事：工具是干什么的、什么时候该用、什么时候不能用。参数同理，要把格式约束写明白，能枚举就枚举，能限定长度就限定长度。

顺便纠正一个高频误解：Claude里所谓的Skills、或者各种平台上的技能包，和Agent不是一回事。Skill是给模型预置的一组指令或工具包，它本身没有自主循环、不会自己做决策；Agent是带着循环、会自己做选择的那一层。你可以把Skill理解成弹药，Agent是开枪的人，两者是配套关系，不是替代关系。

2.2 工具执行层的工程细节，决定稳定性

工具声明只是"协议"，真正翻车的地方在工具的执行层。我总结一下必须做的几件事：

第一，超时和重试必须有。工具调用的是外部接口，外部接口一定会超时。我在生产环境里给每个工具调用都套了超时，默认10秒，超过就返回一个标准化的错误文本喂回给模型，让模型决定是换个工具还是换一种参数重试。不要裸调接口，一旦上游抖动，你的Agent整条链路都会卡住，用户感知就是"这个机器人卡死了"。

第二，工具返回结果要做裁剪和结构化。有一次我做企业知识库问答Agent，工具返回的是全文检索命中片段，一个大文件动辄几万字，全塞进上下文，模型立刻开始胡说八道。后来我在工具层做了处理：只取相关片段、截断到800字以内、加上来源和置信度字段。记住：工具的返回也是要花token的，垃圾输入一定产生垃圾输出，这个道理在Agent开发里体现得淋漓尽致。

第三，能幂等就幂等。凡是带副作用的工具，比如"创建订单""发送通知"，一定要考虑重试造成的重复执行。我的做法是给这类动作加幂等键，同一个请求重复执行时直接返回第一次执行的结果，避免给用户发十条一样的短信这种事故。

2.3 工具设计上最常见的三个坑

• 工具数量不是越多越好。模型每次决策都会把工具列表的schema塞进上下文，工具多了token成本直线上升，而且模型在二三十个工具里选错的可能性也更高。我把同类型操作尽量合并成一个工具，用参数区分，比如一个"query_user_info"工具涵盖查询基本资料、余额、优惠券，而不是拆成三个。
• 工具之间不要有模糊边界。两个工具的description都写得像"能查东西"，模型就会随机乱选。要让每个工具的description边界清晰，甚至可以在description里写明"本工具仅用于查询XXX，查询YYY请用ZZ工具"，用这种交叉引用大幅降低选错概率。
• 敏感操作要有人工确认的闸门。凡是涉及转账、删除、对外发送内容的工具，不要直接执行。让Agent先产出"待确认指令"，你把它结构化展示给用户点确认，再真正执行。这不仅是安全问题，也是Agent在真实业务里能活下来的基本前提。没有这道闸门的Agent，迟早要背锅。

3. 记忆体系：短期、中期、长期到底怎么落地

3.1 别迷信"所有东西都塞进上下文"

很多Agent项目的记忆做得极其粗暴：把历史对话一股脑全部拼进system prompt，一直拼到上下文窗口爆掉。然后用户问一个两周前的问题，模型要么完全失忆，要么把最新那段会话当成全部，答非所问。

记忆这件事，首先要分清三层：短期记忆就是当前会话上下文，中期记忆是与当前用户相关的结构化事实，长期记忆是跨用户、跨会话沉淀下来的知识和画像。短期记忆受上下文窗口限制，中期和长期记忆则要靠外部存储。

短期记忆我常用的做法是"滑动窗口+摘要压缩"：保留最近N轮完整对话，更早的内容在接近上下文阈值时，调用一个便宜的模型把历史压成几百字的摘要，作为背景信息放回上下文。这样既控制了token成本，又不会把早期的关键信息彻底丢掉。这里解释一下token：你可以把它粗略理解成大模型计费和处理文本的最小单位，一个汉字大约消耗一到两个token，上下文窗口满了，模型就会"失忆"，所以压缩和取舍是必须的。

3.2 长期记忆的正确姿势：向量库只是工具，不是目的

一说长期记忆，大家第一反应就是上向量数据库，把对话embedding之后检索召回。我的看法是：向量检索是长期记忆的重要组件，但绝不是全部，而且它解决的是"模糊回忆"，解决不了"精确记录"。

我现在做的是混合式记忆：

• 精确事实类（用户生日、收货地址、订单号、会员等级）用结构化存储，比如一张KV表或MongoDB文档，直接读写，不经过向量检索。
• 偏好和画像类（用户喜欢什么风格、对什么敏感），用向量库存embedding，新信息进来时做相似度检索。
• 事件履历类（用户上次反馈了什么、投诉处理到哪一步），用带时间戳的日志表，按时间线查询。

真正要抠的是两个时机：什么时候写入，什么时候读取。写入不能什么话都记，我的规则是：模型判定为"值得记录"的信息才写，并且做去重和合并；读取不能每轮都把记忆全塞进去，而是根据当前对话主题做检索，只召回与当前意图相关的几条。否则记忆不但没帮上忙，反而引入大量噪音，让模型决策质量断崖式下降。市面上各种记忆框架，说白了都是在帮你管理"写什么、存哪里、读什么"这三件事，原理翻来覆去就这些。

3.3 一个客服Agent的记忆落地方案

拿我做过的客服投诉Agent举例，它的记忆结构大致是这样的：

• 会话态（短期）：最近10轮消息、待处理动作、当前用户在哪个流程节点。
• 用户态（中期）：用户ID、是否会员、历史订单列表、近期投诉记录。
• 知识态（长期）：答案库索引、高频问题top表、模型针对特定品类的回答偏好。

每个会话开始时，先根据用户ID把中期记忆拉出来放到上下文开头；对话过程中，凡是"用户明确表达了偏好、承诺了动作、我们承诺了反馈时限"这类信息，实时写入结构化存储；每天凌晨跑一批任务，把当天的向量记忆汇总、合并、去重，淘汰超过90天没有被召回过的旧记忆。这套东西不复杂，但比那些"把所有历史对话embedding丢进向量库"的方案实用得多，而且可观测、可修正，出了问题你能直接看库里到底存了啥，而不是面对一坨向量发懵。

4. 框架选型与架构设计：别让框架绑架你

4.1 主流Agent框架横向对比

这可能是新人最纠结的问题。我直接给一张表，是我实际用下来的体感，不是转发别人的评测：

我的选型逻辑是：如果核心需求是"把业务流程跑稳"，用LangGraph这类状态图强的框架，它把Agent生命周期显式化了——每个节点做什么、边怎么跳、条件是什么，全部看得见，出了问题能在图上定位。如果需求只是"快速做一个带工具调用的助手"，直接手写循环或者用轻量SDK就够了，别上重框架。

4.2 什么时候别用框架，手写其实更稳

很多人问我要不要手写Agent，我的答案永远是：先看复杂度。我有一个执行原则：能不用框架就不用框架，组织上允许就自己写。

我做过一个生产项目，业务就三件事：根据用户问题选一个工具、调工具、把结果整理成答案。当时团队花了一周调研框架，最后我拍板手写，核心代码不到200行，就是第一章那个ReAct循环，加上日志和重试。上线以后异常稳定，因为根本没有框架层带来的抽象和隐层状态。

框架不是坏东西，但框架会带来三类隐藏成本：一是版本升级可能改API，你的代码要跟着改，升级一次血压高一次；二是框架封装的抽象越深，Debug越难，错误不知道被哪一层吞掉了；三是框架为了通用性会做很多你用不到的事情，这些都会变成性能损耗和认知负担。所以不要因为"大家都在用"就上框架，问自己一句：这个框架帮我解决了哪个具体问题？答不上来，就别用。

4.3 多Agent协作的真相：先问自己三个问题

"多Agent协作"这两年热度极高，但我见过的大部分多Agent项目，本质上只是把一个简单的工具调用拆成了好几个角色各说两句话，效率更低、成本更高。要不要上多Agent架构，先诚实地问自己三个问题：

第一，任务真的能被拆成可独立执行的子任务吗？如果子任务之间强依赖、每一步都要等上一步的结果，那不是并行协作，是一个串行流程，用状态机更合适。

第二，Agent之间通信的信息损耗你承受得起吗？两个Agent之间的每一轮传递，都要把上一段输出塞进上下文，上下文越来越长、token越来越贵，而且信息经过多轮转述必然失真，最后A告诉B的和你本来想表达的已经不是一回事了。

第三，单个Agent配合一套强大的工具，能不能解决？我做过一个数据分析Agent，曾经被建议拆成"数据工程师+分析师+汇报员"三个角色，实际上一个Agent配一组精心设计的工具、加一套清晰的流程提示词，就已经能完成全部工作。

多Agent不是银弹，它是在复杂度足够高时才会划算的架构。从单Agent起步，把单Agent逼到极限，再谈拆分。面试里如果有人一上来就要上多Agent，我基本会追问一句"单Agent哪里不够用了"，十个里有八个答不上来。

5. 评测、调试和安全：让Agent从"能跑"到"能扛"

5.1 先造评测集，别再用"我感觉还行"

Agent开发和传统后端开发最大的不一样是：它没有明确的"对了/错了"边界，同样的输入，模型可能第一次答得好、第二次答崩。所以评测不能靠感觉，要有数据集、有指标、有回归。

我的做法是，项目启动第一周就建立评测集，至少50条典型任务，覆盖主链路场景、边界场景和故意刁难的场景。每条样例标注好：期望行为是什么、期望调用哪个工具、期望的最终答案要点是什么。

评测方式分两种：规则评测（比如"是否成功调用了订单接口""最终答案是否包含订单号"）和"让大模型当裁判"（把Agent的输出和标准答案一起丢给模型打分）。实际体验是规则评测稳定、可解释，但把所有场景都写成规则会累死；模型裁判泛化能力强，但偶尔会误判，需要定期人工抽检。我的做法是规则为主、模型裁判为辅，上线前人工过一遍高危case。这个评测集要持续扩充，每出一个事故case就往里加一条，让它成为团队的"Agent考题库"。

5.2 调试Agent的独家招数

Agent出问题最难的是定位：到底是模型想错了、工具选错了、工具执行失败了，还是上下文被污染了。排查手段总结下来就是三板斧：

第一，把每一步都打日志。一个完整的Agent日志要包含：本轮思考内容（thought）、选择了什么工具和参数（action）、工具返回的原始结果（observation）、当前上下文长度和token消耗。有了这四行，绝大多数问题一眼就能看出来。我做过最痛苦的一个case，查了两天才发现是某个工具返回里带了一个特殊字符，把上下文搞乱了。

第二，用便宜的模型做快速迭代。开发期不需要每次都调最贵的模型来验证逻辑，先用性价比模型把流程跑通，最后上线前再用强模型做全量验证。这样调试成本能降一个数量级，而且能更快地把流程问题暴露出来。

第三，做失败重放。把出问题的case完整保存下来，包括当时的输入、上下文、每一步的日志，修复后作为回归用例重新跑一遍。这比"改个prompt再试试"靠谱得多，因为你改完到底有没有用、有没有把别的case改坏，一跑就知道。

5.3 安全与成本：上线前必须过的两道坎

最后聊落地逃不掉的现实问题。安全方面，Agent因为能调用工具，风险比普通对话应用高得多，重点防三件事：

一是Prompt注入，用户故意在输入里夹带指令让Agent去执行危险操作。解决方案是工具权限最小化、所有敏感操作都走人工确认，别让Agent有权直接干"大事"。

二是信息泄露，Agent在回答时可能把不该披露的内部数据带出来。需要在工具层做一次输出过滤，敏感字段要在工具层就脱敏，而不是等模型生成完再拦。

三是滥用风险，比如被用来批量查询大量数据，要做频控和配额。成本方面，一个Agent会话往往要跑多轮模型调用，成本是普通对话的好几倍甚至上十倍。我的习惯是：全程记录token消耗，按"每完成任务平均成本"来监控，而不是看单次调用；对高频固定查询做缓存；给循环设置最大步数，比如最多10次，超过就收尾兜底；能用小模型的任务绝不用大模型，摘要压缩、意图判断这类子任务用性价比模型就够了。

做了近两年Agent开发，我最大的体会是：这行没有那么多花活。真正能把一个Agent从"我试过，能跑"带到"生产环境用了半年没出大事"，靠的是把工具调用、记忆、评测这些基本功抠到极致，而不是整天折腾新框架。如果你正在学Agent，我的建议很直接：先手写一个最简单的ReAct循环，跑通一个真实场景，再回头看框架和架构模式，你会发现自己已经能看懂那些框架到底是在帮你忙还是给你添乱。先跑通，再优化，这句话在Agent领域比什么都值钱。