做了近两年的Agent开发，坦白讲，踩过的坑比我写过的代码多得多。从最早拿着OpenAI Function Calling做玩具，到后来在真实业务里折腾多Agent协作、记忆持久化、生产级评估，走了大半年弯路才慢慢想明白一件事：Agent开发的门槛，根本不在“会不会调大模型API”，也不在于你熟悉多少框架，而是你是否真正理解Agent运行的几个核心机制。今天这篇不列学习清单，不贴官方文档，只讲我自己摸爬滚打总结出来的五件事，算是给这两年一个交代。

先说一句得罪人的话：现在市面上的Agent教程，八成教的是“术”，教你怎么pip install、怎么配Key、怎么跑通一个Demo。但真正到了复杂业务场景，Demo越流畅，死得越快。因为Agent的难点从来不在“跑通”，而在“稳定跑通”“可控地跑通”“出了错还能自己缓过来地跑通”。这些能力，归纳下来就是五个方向：搞清楚Agent的本质、设计好记忆体系、吃透工具调用、选对一个框架深入理解、最后把多Agent协作和生产级落地这件事想明白。

1. 第一件事：先破“Agent是什么”的认知迷障

1.1 Agent不是“高级聊天机器人”，而是一个循环系统

我见过太多人把Agent当成“能调用函数的LLM”，这个理解不能说错，但过于片面。它导致的结果是：你一上来就研究怎么把Prompt写复杂、怎么让模型调用工具，却忽略了一个Agent真正的骨架——它要跑在一个循环里。

什么样的循环？用大白话说：Agent拿到一个目标，先观察现状，再规划下一步，然后调用某个工具或生成一段内容，拿到结果后再观察、再规划，直到目标完成或主动放弃。这不是一个线性的API调用，而是LLM驱动的“感知-决策-行动”闭环。这个闭环才是Agent和普通程序的根本区别：普通程序的控制流是开发者写死的，Agent的控制流是模型根据当前状态动态决策的。

这里最推荐新手做的一件事：亲手用代码写一个极简React循环，别用任何框架。核心就几十行，一个while循环，内部两步：把历史消息、可用工具列表、当前任务拼进Prompt，发给模型；解析返回结果，如果是tool_call就执行对应函数并把结果追加回消息列表，继续循环。跑通了这个最原始的循环，你对Agent的理解会超过看十篇框架文档。

1.2 两类主控模式，决定Agent的下限

真正动手之后，你会发现“循环”只是地基，上面盖什么楼才是关键。目前工程界主流的Agent主控模式就两类：一类是ReAct式的“边想边做”，每一步都由模型决定下一步；另一类是Plan-and-Execute式的“先规划后执行”，让模型先把任务拆成分步计划，再按计划一步步执行，执行完再统一校准。

ReAct的优点是有弹性、适合探索类任务，缺点是token消耗大、行为不可预测。Plan-and-Execute的优点是省token、整体可控，缺点是遇到计划外情况容易翻车。我自己在业务里的取舍是：任务边界清楚、步骤能枚举的，用Plan-and-Execute；任务开放式、要频繁试错的，老老实实上ReAct或者它变体。别迷信任何一种，两种都亲手各实现一遍简单版本，你就有体感了。

2. 第二件事：把Agent的“记忆”体系设计明白

2.1 短期、长期、永久——记忆的三层架构

热词里有人问“中短期、长期、永久记忆如何实现”，这是Agent落地绕不开的问题。我的经验是：先别急着选数据库和框架，先把记忆分层这件事想清楚，后边一切技术选型都是水到渠成。

第一层，短期工作记忆，本质就是上下文窗口内的信息，模型在这一轮对话里能直接看到的内容。它的问题是窗口有限，装不下长对话和大量检索结果，所以要做管理，而不是一味往里塞。

第二层，长期记忆，通常指跨会话可召回的信息，比如用户的历史偏好、项目中积累的知识片段。实现上主流方案是“向量检索+RAG”：把信息切片、Embedding、存入向量库，需要时把用户当前问题也Embedding，做相似度召回。注意，召回不是查完就完事，工程上要加一个重排环节，否则向量相似度高的结果不一定是有用的结果。

第三层，永久记忆或者说核心记忆，是Agent最稳定、最不该丢的那部分信息，比如用户的身份画像、实名信息、业务硬约束。这类信息不能靠向量召回碰运气，必须结构化存储，比如存进数据库，每次对话开始时强制注入系统Prompt。这一点很多人会忽略，结果就是用户明明昨天刚告诉Agent自己叫某某，今天Agent又问了。

2.2 记忆框架怎么选：标配、三方还是自研？

市面上现在有Mem0、Zep这类专门做Agent记忆的开源框架，也有LangChain的LangMem，以及各家云平台自带的记忆能力。我的建议是分阶段看：如果只是做Demo，用Mem0或Zep足够，它们把提取、存储、检索封装好了，能帮你快速验证记忆这个功能有没有价值。但真要上生产，通常要自研或深度定制，原因有三个：

第一，三方框架对“什么信息该写入记忆”的判定，往往依赖LLM抽取，这会带来额外的延迟和成本，而且抽取质量不稳定。第二，记忆的权限管理是个大坑，谁的记忆、谁能读、谁能改，三方框架给不了答案。第三，记忆的召回时机、注入策略必须和你的业务Prompt深度耦合，封装好的框架很难调出理想效果。

我目前的经验是：短期记忆自己管理消息列表和摘要，长期记忆用向量库+重排，永久记忆用结构化表，记忆框架只用来做信息抽取和摘要，不完全照搬。

2.3 记忆实战中的三个深坑

坑一：记忆污染。检索回来的不相关内容混进上下文，反而把模型带偏。对策是设置召回相似度阈值，宁缺毋滥；同时做一个“记忆相关性校验”步骤，让模型判断召回内容是否与当前任务相关。

坑二：上下文爆炸。不管什么信息都往上下文里塞，很快窗口就满了，费用也飞涨。对策是分层压缩，旧对话先抽取摘要，再保留关键条目，最后才考虑向量召回原文。

坑三：记忆和时效的冲突。用户昨天改了偏好，今天Agent还按旧偏好推荐。对策是给记忆条目加时间戳和置信度，读取时按时间衰减排序；关键场景下要主动向用户确认“你之前设置的是A，今天是否要改”。

3. 第三件事：把工具调用和Skill机制吃透

3.1 Function Calling是Agent的“手”，但大多数人只学会握手

Agent没有工具就像残疾人，有了工具调用能力，它才能真正对世界产生影响。我说“大多数人只学会握手”是因为：很多教程教了怎么定义Function、怎么让模型返回结构化参数，但没教怎么把工具这套机制设计成一套可靠的基础设施。

首先是工具的描述，这是决定模型能不能正确选择工具的关键。我见过大量工具写得不合格：“search(query: str)”这种描述，模型根本不知道什么时候该用、参数范围是什么。合格的工具描述应该像一个给实习生写的任务说明书，包含：这个工具是干什么的、什么时候用、什么时候绝对不要用、每个参数的含义、格式要求、典型的输入示例。别嫌长，模型就是靠这个选工具，写得糊弄，选错是必然的。

其次是工具的返回错误处理。一个让我痛定思痛的经验：工具执行失败后，别只返回“Error”，要把错误信息转换成“对模型友好的语言”，比如“数据库连接超时，请3秒后重试”或者“输入的日期格式错误，应为YYYY-MM-DD”。因为Agent会依据这个结果做下一步决策，你给它一堆堆栈，它根本没法用，只会死循环或瞎编。

3.2 Skill和Agent的关系，千万别搞反

热词里有人问“skill和agent的区别”。我自己的理解是：Skill是能力包，Agent是决策主体。Agent决定什么时候用什么Skill、怎么组合Skill达成目标；Skill本身就是封装好的一个特定能力，比如“搜索信息”“解析PDF”“调起日历”。两者的关系就像“员工”和“技能证书”，员工决定是否使用以及如何使用证书，证书本身不决策。

实操中，Skill设计的关键在于粒度。粒度过小，比如“计算字符串长度”这类原子操作，Agent用起来累，组合也复杂；粒度过大，比如“完成一份市场调研报告”，Agent调一次就完事，失去可组合性。经验是控制在“一个明确子任务”的粒度，比如“搜索指定关键词并返回排名前10结果”“把给定文本转成结构化表格”，既能独立完成，又可以被更高层任务复用。

3.3 工具编排的进阶玩法：路由、校验与动态注册

当工具数量超过10个时，把所有工具一股脑发给模型的做法就不太奏效了：Token消耗大，模型选择精度下降。我试过几种改善方案，最有效的还是分类路由。把工具按领域分组，比如“搜索类”“数据库类”“办公类”，先让模型决定走哪个类别，再在类别内选择具体工具。这有点类似业务系统里的服务发现——先定位服务，再调用接口。

另一个被低估的点是参数校验。模型生成参数偶尔会产生幻觉，比如日期不存在、数字越界。在工具入口处做一层严格的参数校验，不合法就返回标准错误信息让模型重新生成，比把脏数据传给下游业务再排查高效得多。这块用Pydantic这类库很顺手，定义好工具入参模型，校验自动完成。

最后是动态注册。有些工具是否可用取决于上下文，比如“查本月业绩”依赖当前登录用户身份，没登录就不要注册这个工具。动态控制工具列表，既省Token又减少误调用，这个优化在工具多的时候效果特别明显。

4. 第四件事：读透一个主流Agent框架，而不是集邮

4.1 框架和Agent的关系：Harness和Agent的本质区别

关于“harness和agent区别”，我自己的理解：Harness是那个“壳子”，它负责模型的调用循环、工具调度、消息管理和流式输出控制；Agent则是跑在壳子里那个有目标、能决策的“脑子”。框架给的是Harness，造的Agent内核仍然要你自己设计。所以选框架的本质，是选一个你认可的“壳子协议”，而不是买一个现成的“脑子”。

市面上主流框架各有偏爱：LangGraph主打印发式状态图，适合复杂流程控制；CrewAI主打角色分工，适合多角色协作原型；AutoGen偏多智能体对话，适合研究探索；OpenAI Agents SDK延续了官方Function Calling的优雅，代码轻；而Dify、Coze这类偏低代码平台，适合快速交付业务Demo。没有全能的框架，各有各的脾气。

4.2 我的选型逻辑和深度使用心得

我现在的建议是：如果你有定制化需求，优先考虑LangGraph或OpenAI Agents SDK这类的代码优先方案；如果你要快速给业务方演示效果，Dify这类低代码平台很香；如果你要在生产环境折腾多Agent，CrewAI和AutoGen都要先做压测再决定。

我个人的主力框架是LangGraph。理由有三：它的状态管理非常显式，适合我这种喜欢把流程“看得见”的人；它的节点机制让我能无缝插入自定义校验、人工审批、条件分支；它和LangChain生态打通，工具、记忆、模型切换的成本低。但这不代表它没毛病——上手曲线陡，概念多，刚用时会被State、Node、Edge这些抽象绕晕。我的经验是：先用它复刻你已经手写过的那个ReAct循环，跑通了再逐步加分支和状态，不要一上来就画复杂图。

4.3 面试时的Agent框架问题，其实是在问理解深度

热词里有“agent面试题”，我之前也面了不少人，发现普遍的问题在于只背概念、没写过代码。面试官问“LangGraph和AutoGen的区别”，本质是想知道你有没有对比过它们的状态管理方式和执行模型；问“如果工具调用陷入死循环怎么办”，十有八九是在考察你有没有真正处理过这类问题。所以学框架时，别只看文档例子，强迫自己回答几个问题：这个框架的循环在哪里？状态存在哪？节点异常如何处理？框架偏好的记忆和工具管理方式是什么？答得出这些，才叫理解。

5. 第五件事：多Agent协作和生产级落地，从跑通Demo到能上线

5.1 多Agent协作的三种模式，先学会分辨

多Agent协作听起来很牛，但真正落地时，八成以上的场景用不上复杂协商。我把常见的协作模式归纳为三种：管道式、路由式和黑板式。

管道式最简单：Agent A的输出作为Agent B的输入，像流水线。适合步骤固定的任务，比如先调研再写方案再审核。路由式是一个“调度Agent”把子任务分发给不同的专用Agent，像客服主管派单。黑板式是多个Agent共享一个可读写的信息空间，各自取自己需要的部分，适合问题高度开放、需要集思广益的场景。设计多Agent系统前，先问自己到底需要哪一种，能单Agent完成的坚决不用多Agent——多一个Agent就多一份不稳定和费用。

5.2 评估即上线前的安检：没有评测，别谈稳定

生产级落地的第一步不是部署，而是评估。给Agent建一套评测集，里面放三类用例：标准流程用例、边界异常用例、用户恶意输入用例。标准流程确保主路径不挂，边界异常测试工具失败、模型超时、信息缺失等场景下的恢复能力，恶意输入测试安全性。

评测指标上，我用比较多的是：任务成功率、工具调用准确率（选对了工具并且参数正确）、步数效率（完成任务消耗的模型调用次数）、Token成本、端到端时延。别只看最后成功与否，中间哪一步多绕了弯，一眼就能看出主控策略是否有问题。

5.3 Agent安全与权限，生产环境的底线

Agent安全不是有没有，而是做成什么样。我把安全等级分成三层：第一层，工具权限最小化，Agent能调用的工具和API都要按“最小够用”原则配置，不能让它有任意读库删库的能力；第二层，Prompt注入防护，外部输入可能夹带恶意指令，要在工具结果回传前做过滤，对Agent输出也做敏感词和权限域校验；第三层，审计追踪，所有Agent的决策历史、工具调用记录、输入输出都要留痕。这层虽然不直接提升能力，但出问题排查时能救命。

5.4 部署阶段的几个实战问题

最后说部署。我是从FastAPI包一个Web服务起步的，后来因为并发和任务时长才转向独立Worker。这个过程中最值得记住的几个经验：第一，一定用异步任务队列，别直接把Agent丢在HTTP请求处理里，一个长任务卡住十分钟，你的线程池就被堵死了。第二，重试机制必须有且必须有上限，LLM偶尔抽风是常态，工具超时也要设置阈值。第三，日志和追踪要从第一天就规划，每次模型调用、每步工具执行都留下结构化日志，配合LangSmith这类工具做过程复盘，否则出问题只能面对满屏Prompt干瞪眼。

我个人这两年下来，最大的心得体会是：做Agent开发，真正重要的不是什么“提示词工程”的玄学，而是你能不能弄清楚这个模型驱动的循环，在每个环节会如何失控，以及你准备了多少手段能让它回到正轨。把循环写出来，把记忆分层，把工具描述到实习生能看懂的程度，选一个框架深挖，再给Agent配齐评估和安全护栏——这五件事全做扎实了，市面上大部分Agent应用的核心架构你已经能看懂，也能动手搭出真正能扛业务的东西。

最后再分享一个小技巧：不管用什么框架，你都要能在“不用框架”的情况下，徒手写出一个能完成单工具调用和记忆注入的最小Agent。这个东西平时用不上，但在框架出问题、或者面试需要现场推演的时候，它就是你最靠得住的底牌。Agent开发这条路上，模型底座会换、框架会换代，这套循环、记忆、工具、评估的安全心智，才是你真正能带走的东西。