大模型Agent开发实战：真正要学的五个核心能力

做了近两年的Agent开发，真正要学的就是这五件事。我是大模型开发工程师，这两年密集做了智能客服、浏览器自动化、代码生成类的Agent项目。很多人问我入行学什么，市面上流行的答案是LangChain、Prompt、RAG。但回头看，真正绊住我的从来不是某个框架的API，而是下面这五件事。这五件事解决了，Agent才叫"能用的系统"；没解决，再花哨的Demo也扛不住真实场景。这篇文章写给正在做Agent应用开发、准备做Agent岗位面试、以及想在真实业务里落地Agent的同学，我尽量把两年里踩过的坑和验证过的方案一次讲透。

1. 第一件事：把模型当成推理引擎，而不是万能数据库

1.1 大多数Agent失败的根源：你让模型做了它不擅长的事

我做过的第一个Agent项目是给一个电商客服做自动答疑。当时的产品思路很简单：把商品信息、退换货规则、物流政策全部写进System Prompt，然后让模型"自由发挥"回答用户问题。 demo阶段效果惊艳，什么问题都能答。一上线就崩——用户问"这款手机支持5G吗"，而手机参数在几百个SKU里，模型记不住就编了一个"支持"，导致大量投诉。

这个问题的本质不是模型不够聪明，而是我们把模型当成了数据库。大模型是语言模型，它的训练目标决定了它擅长的是语言理解和逻辑推理，不是精确记忆海量琐碎事实。上下文窗口再大，塞进去的商品数据只要超出注意力范围，模型就会为了"继续对话"而开始编造。这是认知层面的错误定位，改Prompt治标不治本。

1.2 我踩过的具体坑：让模型"背表"的翻车现场

后来我不只在一个项目上犯过这个错。做数据分析Agent的时候，我把一个MySQL表结构定义了几十条字段，全部塞进Prompt，期望模型能精准写SQL。结果是模型经常记错字段名，把order_amount写成amount，把user_id当成字符串处理。SQL编译报错倒是小事，更可怕的是有些错误能跑通但结果完全错误——比如把COUNT(id)当成了COUNT(DISTINCT id)，然后一本正经地告诉我"去重用户数是10万"。

还有一次做文档理解Agent，为了省掉向量检索的工程成本，我直接把几十页的合同文本一次性塞进上下文。结果模型对前面条款的记忆还算准确，到了第30页以后就开始张冠李戴，把甲方的付款义务安到了乙方头上。这些案例让我明白一个道理：模型对上下文的"使用"方式和人看文档是不一样的，它更像是"理解大意"，而不是"逐字背诵"。

1.3 正确的调用姿势：模型只做判定和生成，精确数据交给工具

现在我设计的Agent架构都遵循一个原则：凡是能被代码、数据库、API精确计算或查询的数据，绝对不进Prompt。模型在链路里的角色是"大脑"，负责解读意图、制定计划、组织语言；但真正读取订单金额、查询用户积分、计算运费，全部通过Function Calling交给后端服务。

具体落地是两步。第一步，让模型输出结构化意图，比如用户问"我上个月买了多少东西"，模型只负责识别这是"订单查询"意图，并抽取user_id和时间范围。第二步，代码拿着这些参数去查数据库，拿到精确结果再拼装成自然语言。模型永远只面对"已经查回来的结果"，而不是"原始数据库"。

这个改动之后，客服Agent的准确率从82%提升到96%以上，关键是没有再出现过编造订单数据的严重事故。后来我每次评审新Agent方案，第一个问题就是："哪些信息是模型必须精确记住的？"如果答案是"大量事实性数据"，这个方案就先不通过。模型不是硬盘，它是CPU——这是我给所有新人的第一课。

2. 第二件事：工具调用（Function Calling）才是Agent开发真正的分水岭

2.1 工具是Agent的手和脚，schema设计决定成败

模型本身只能"说"，不能"做"。工具调用就是给模型装上手脚。但很多人以为工具调用就是把Python函数名和描述丢给模型，模型自己就会调用。这个理解太天真了。 Function Calling是一个完整的接口协议，工具的名称、描述、参数的schema、返回值的结构，每一个细节都在影响模型调用的成功率和准确度。

我在一个项目里定义了一个工具叫send_message，描述是"发送消息"。这个工具参数里有个channel字段，枚举值有 email、sms、wechat。上线后发现模型经常在这个工具上犯错——用户说"给我发个短信提醒我明天开会"，模型正确识别channel=sms；但如果是"用微信通知家里人"，模型有时会犹豫不决，甚至把channel填成 email。

原因很简单：我是一个中国人，工作场景默认沟通是微信；但模型训练数据里可能更习惯 email。所以我认为工具描述太短太模糊，模型只能靠猜。"发送消息"这个描述没有说清微信是什么、sms跟短信的关系、以及区分维度。后来我把描述改成详细版本："向用户发送一条消息。channel必填，可选值包括email（电子邮件）、sms（手机短信）、wechat（微信，国内用户常用，GDPR不适用）"。同时给每个枚举值补充了使用场景示例，模型调用准确率立刻从71%升到了93%。

2.2 工具Schema设计的细节：命名、参数约束、幂等性

工具命名是另一个关键点。我给一个跨境电商Agent定义了get_shipping_cost，同时还有get_shipping_time。名字相似度太高，模型经常混。后来我统一了命名前缀规范：查询类工具叫query_xxx、操作类工具叫action_xxx、计算类工具叫calc_xxx，比如query_shipping_info合并了运费和时效，直接消灭了一类混淆错误。

参数约束里最容易忽略的是必填与可选。工具的参数如果没写required，模型可能漏填关键参数；但如果把太多参数设为必填，模型又会乱填来迎合。我的经验是：让模型先调用一个"空参数"的工具去做意图澄清，再根据返回结果填第二个工具。比如下单Agent，第一步先调get_user_info（参数为空），拿到默认用户信息后再调confirm_order，避免模型一上来就瞎填地址。

还有一个极其重要但经常被忽略的点：幂等性。我做过一个支付回调Agent，action_charge工具如果因为网络超时被调用两次，用户就被扣了两次款。后来所有写操作工具我都加上了request_id参数，后端用这个ID做去重，并且文档里明确告诉模型"如果上次调用无返回或报错，不要盲目重试同一个操作"。这个对Agent可靠性影响巨大，尤其涉及资金、库存、工单状态变更时，幂等设计不是加分项，而是保命题。

2.3 工具返回值的结构化与容错

工具调用成功与否不仅取决于模型，还取决于工具返回给模型的内容。早期我做的一个工具返回的是自然语言："抱歉，您的订单还在审核中，请稍后再试。"模型拿到这个结果后会继续生成一段安慰用户的话，但其实用户问的是"订单能不能今天发货"。问题出在返回值给模型的信息量太低了。

现在我要求工具返回值一律用结构化JSON，至少包含三个字段：

{ "status": "success", "data": {"order_id": "20241201", "status": "审核中", "estimated_delivery": "2024-12-05"}, "suggestion": "请告知用户预计明天可发货，无需进一步操作" }

关键不是给模型看原始业务数据，而是让后端在返回前就把"模型下一步该说什么、该做什么"算好。模型只负责用自然语言重述这个结构化的决策，而不是自己重新推理一遍业务状态。这样做的好处极其明显：错误分支可控，模型不会在业务状态上自由发挥。

此外，工具的容错要做在返回结构里。工具内部出异常时不要抛给模型一个Error对象让它猜，而是返回{"status": "failed", "reason": "库存不足，仅剩SKU-102可售", "suggestion": "建议推荐替代商品SKU-102"}。这样模型可以无缝衔接地给用户一个建设性回复。关于工具安全，我也多说一句：给Agent暴露的工具权限要遵循最小化原则，读操作可以放开，写操作尽量加入二次确认或操作审计。Agent的自主性越强，工具被误调用的后果越严重，这一步省不得。

3. 第三件事：记忆与上下文管理：Agent不是金鱼，但也不是大象

3.1 上下文窗口不是记忆，是临时工作台

很多人把大模型的上下文窗口理解成"记忆容量"，然后拼命往里塞历史对话。这是一个会长期折磨你的误解。上下文窗口本质上更像一张工作台——上面能摆的东西有上限，摆得太多，模型反而找不到重点。我观察到的规律是：上下文占满70%以上时，模型开始忽略中间部分的信息，这在学术上叫"Lost in the Middle"，实际体验就是用户问上周说的事，Agent一脸茫然。

我做过一个企业知识库Agent，为了"让模型记得住所有会议纪要和项目文档"，我把几千条历史记录全放进上下文。结果模型不仅回答质量下降，每次请求的Token消耗和延迟也暴增，单次问答成本翻了五倍。关键是没有换回任何准确度提升。我把上下文缩减到最近的10轮对话后，FAQ准确率反而从78%升到了84%。这告诉我：上下文要敢做减法，记忆要放外面。

3.2 短期记忆、长期记忆、工作记忆：三类记忆的取舍

我现在设计Agent记忆体系时，会分成三层。

短期记忆就是当轮对话本身，放上下文里，用于保持多轮对话的连贯。这块我们通常只保留最近N轮，N一般在10到20之间。如果任务是一步步推进的（比如"帮我写方案再翻译成英文再润色"），需要保留的轮数就多些；如果是问答型任务，保留5轮就够。

长期记忆放在外部存储。这里要区分"事实性记忆"和"知识性记忆"：事实性记忆是用户的偏好、订单状态、历史购买记录，存结构化数据库；知识性记忆是文档资料的语义内容，存向量数据库或倒排索引。很多项目只做向量库不做结构化存储，结果用户问"我上周是不是问过退货的事"，Agent无法精确回答，因为向量召回的是"相似语义"而不是"精确事实"。用一句话总结：向量库适合"模糊找相关内容"，数据库适合"精确找某个事实"，两者配合使用才叫完整记忆。

工作记忆是任务进行中的中间状态。比如一个多步骤任务，"正在写论文"进行到第3章，Agent需要记住当前进度。这个状态如果只靠对话历史推断，一旦上下文被截断就丢了。正确做法是定义一个任务状态对象，每完成一步就更新状态字段，这一步由代码负责，不依赖模型记性。这类状态机设计在带流程的Agent里几乎是必需品。

3.3 上下文管理实操：截断、摘要与关键字段抽取

上下文管理三个常用手段：滑动窗口、摘要压缩、关键字段抽取。

滑动窗口最简单，就是只留最近N轮，超出部分丢弃或归档到日志。适合轮次短、关联弱的场景。缺点是一旦用户问"我们三小时前讨论的方案你优化一下"，Agent已经完全忘记了。

摘要压缩是把旧对话丢给模型总结成一段文摘，塞回上下文开头。我用过一段时间，发现它有两个副作用：一是摘要本身会丢失大量细节，比如具体的数字、时间、姓名；二是摘要会引入预测性信息，模型在总结时会把不属于原对话的内容"脑补"进去，而这个脑补内容会污染后续判断。目前我的策略是：摘要只用于"背景铺陈"，关键事实仍然必须通过结构化工具去外部拉取，绝不让模型靠摘要做精确决策。

关键字段抽取是我目前最推荐的方式。每轮对话结束后，用一个专门的抽取模型（或者同一个模型的一次额外调用）把会话里的实体和槽位抽出来，比如用户ID=12345、意向产品=A款、退款金额=200元，存入结构化状态表。下一轮Agent只要先从状态表读数据，再把数据拼进上下文就能精准回答。这条方案同时解决了长对话记忆和Token开销，也是LangChain里memory模块的底层思路——但难点在于抽取规则要设计得足够细，否则抽出来的字段不准，后面全部白搭。

4. 第四件事：别把"规划"神话，可控的任务拆解才是Agent落地的关键

4.1 ReAct不是银弹，真实的Agent需要"预设流程+模型填空"

刚入行的时候，我被ReAct模式吸引——让模型自己推理、行动、观察、再推理，循环往复直到完成任务。听起来很智能，实际一跑问题频出。

我在一个自动生成UI测试脚本的Agent项目里试过纯ReAct。目标很简单：读取测试用例文件，根据用例步骤自动生成Playwright脚本。模型第一步读文件、第二步理解用例、第三步写代码、第四步试运行，看起来规划得很合理。但实际执行到第三、四步就频繁出问题：模型发现自己写的脚本报错时，会反复编辑同一行代码却不重新读取页面元素的真实结构，陷入"自我感觉良好但一直修不好"的死循环。最后我限制了最大迭代次数为5，结果模型在5次内没有做任何有帮助的调整。

这个经历让我改变了对规划的看法。现在的Agent架构里，我把"规划"拆成了两层。第一层是预设流程——如果某个任务类型在我们的业务里已经出现过100次，那就直接写死步骤：意图识别、参数抽取、状态检查、执行动作、结果确认。流程是确定性的，由代码驱动，模型只在每个步骤里做具体的判定和内容生成。第二层是动态扩展——只有在预设流程没有覆盖的情况下（比如用户提了全新需求），才让模型自己拆步骤，并且拆完先输出一个"计划"给用户确认，确认后才执行。

结果就是：确定性任务的失败率大幅下降，新任务的执行也不会失控。这个对比很明显，我对访客型Agent跑过一组数：纯ReAct模式下任务整体完成率只有66%，而"预设流程+模型填空"模式下常见任务的完成率升到了91%，平均耗时从42秒降到19秒。要明白一个道理——模型的规划能力是"看起来合理"的能力，不是"过程可靠"的能力。让它做决策之前，你已经把路修好了，这样反而走得更稳。

4.2 "知难而退"：Agent必须学会承认自己做不到

很多人做Agent时默认模型什么都能干。实际业务里，模型应该具备"我知道我不知道"的能力。电商客服里经常有用户问"为什么我的优惠券叠加不了"——这个问题如果无法从当前系统的数据中确认原因，我让Agent直接说"我需要查一下，稍后回复您"，而不是硬编一个理由。

实现"知难而退"有两个机制。一个是信息充分性检查：在模型生成最终答案前，先校验所有关键信息是否都有数据支撑，如果缺关键参数，则调用澄清工具而不是直接回答。另一个是置信度阈值：模型内部往往自带概率分布，我们在服务层可以设置一个阈值，当模型对意图判定的置信度低于0.7时，主动转人工或给出兜底话术，而不是猜测式回答。做Agent开发，重要的是知道很多幻觉不是模型故意骗你，而是它在强行"维护对话的流畅"。我们要做的是在各个关卡设卡，不让它硬答。

4.3 反射与自我验证：Agent也得分步检查

这两年还有一个对我帮助很大的方法：让Agent在关键步骤上做自我验证。简单说，就是在计划里插入"检查点"。比如生成SQL前先让模型列出"我要查询的表、字段、条件"，执行后把结果与实际表结构对比，不一致就重新生成。

我在一个数据分析Agent上实践过"先写验证条件再执行"的套路。让模型在调用query_sql之前，先生成一个qa_expected_range参数，填写它认为结果应该满足的合理范围（比如用户数是1000到2000之间）。SQL执行后如果结果超出这个范围，代码层主动触发告警，让模型重新确认。这个机制看着简单，但确实能拦下不少因字段错用导致的荒谬结果。成本也就增加了一个小模型的调用，却买到一份可靠的"理智检查"。

5. 第五件事：没有评估体系，Agent开发就是盲人摸象

5.1 为什么Agent比传统软件更难调试：一切都在变化

传统软件开发里，代码是确定的，测试用例写好就能回归。Agent开发完全不同：底层模型是黑盒，同一段Prompt换一天可能结果就变；模型厂商还会定期升级，今天跑得好好的流程，下个月可能因为模型行为漂移而崩掉。如果手里没有一套能随时跑起来的评估集，你根本无法判断到底是"我做错了"还是"模型变了"。

我有一次印象很深：某天凌晨客服Agent的"人工接管率"突然从2%涨到18%。查了半天，不是我的代码问题，而是模型厂商夜里发了一个新版本，导致模型在识别用户情绪时偏向保守，动不动就转人工。如果没有那套监控指标，我可能要等用户投诉一周才发现异常。这让我下定决心：Agent开发必须自带"仪表盘"，否则就是拿着地图在黑夜里开车。

5.2 搭一个最小可行评测集：从"感觉变好了"到"指标变好了"

搭建评估体系听起来大工程，但没有想象的那么重。我的做法是先做一个小而准的评测集，50到100条就够。每条包含：用户输入、期望意图、期望工具调用序列、期望最终答案的关键点。然后写一个回归脚本，每次改动Prompt或工具定义后，跑一遍所有用例，统计几个核心指标。

我在Agent上常用的四个指标是：

有了这套评估集，我再也不靠"我试了一下感觉不错"来做决策。任何Prompt改动、工具重构，先跑评测，看指标再说话。省下的争吵和返工时间，远超当时搭建评测集投入的成本。

5.3 可观测性：日志、Trace与逐步回放

评估集是"离线验证"，监控是"线上兜底"。Agent开发里最难受的事情是用户报了一个问题，你完全不知道模型当时调用了哪些工具、看了哪些上下文、输出了什么中间结果。没有Trace，排查就只能靠猜。

我现在所有的Agent项目都会在关键节点输出结构化日志：每一次LLM调用（记录模型名、输入Token数、输出内容、耗时）、每一个工具调用（记录工具名、参数、返回状态、耗时）、以及完整的事件轨迹。数据存到日志系统里，用TraceID串联。用户出问题时，直接把TraceID拉出来，一步步回放：模型看到了什么、做了什么决策、在哪一步跑偏了、是不是工具返回了错误数据。这种逐步回放的能力，是把Agent当作正经系统运维的基础。

顺便提一句，现在市面上的企业级Agent平台，很多都自带可观测性功能，比如LangSmith、Langfuse，以及一些面向2026年企业级数据Agent的平台。选型时可以重点对比它们的Trace是否覆盖完整的工具调用链、是否支持按会话维度检索、是否包含Token成本和耗时统计。这些看着不起眼，真到线上排查时全是救命功能。

最后分享一点体会

两年下来我最大的变化是不再迷信"多智能体""自主规划"这些词。Agent开发越到后面越像传统软件开发——要的是稳定性、可观测、可评测。五件事里前四件都是在"约束"和"驯服"模型，第五件事是安装仪表。一个Agent从Demo到产品化，其实就是一个从"让模型自由发挥"到"给模型戴上安全绳"的过程。如果你想入行，我的建议是从第三件事和第五件事开始补，这两件是大家最少关注、但实战里最容易让你脱颖而出的能力。