智能体开发这件事我从去年下半年开始密集地做前后完整落地过三个项目一个内部制度条例学习助手、一个电商客服辅助Agent、还有一个给运维团队做的告警分析助手。踩过的坑比写过的代码还多。这篇文章不讲虚的就围绕“AI智能体Agent实战开发”这个主题把我从零搭建一个可用Agent的完整思路、技术选型逻辑、核心模块拆解、以及那些文档里不会写的坑全部摊开来讲。如果你是大模型方向的学习者、正在做Agent项目的开发者或者单纯想搞清楚“Agent到底怎么从0到1搭起来”的人这篇内容应该能帮你省下不少试错时间。我会尽量用从业者之间的语言把每个关键决策背后的“为什么”讲清楚而不是只丢一堆代码让你自己悟。1. 先想清楚你要的到底是Agent还是Workflow很多人一上来就说“我要做个Agent”但聊十分钟就会发现他真正需要的其实是一个带分支逻辑的工作流。这两者的边界如果不先划清楚后面的架构设计一定跑偏。1.1 一个判断标准决策权在谁手里我通常用一个很简单的问题来区分下一步做什么是由代码逻辑决定的还是由模型自己决定的如果整个流程的步骤是固定的——比如“先提取关键词再查数据库再拼装回复”——那这就是Workflow用LangChain的Chain或者干脆用普通函数编排就够了稳定、可控、好调试。反过来如果系统需要根据用户的输入动态决定“要不要调用工具”“调用哪个工具”“调用几次”“结果不满意要不要重试”决策权在模型手里那才是Agent。我做过一个制度条例学习助手最初的版本就是典型的Workflow用户提问→检索相关条例→模型总结→返回。跑得很稳。但后来需求变成“用户可能问一个跨多个条例的复杂问题需要模型自己判断先查哪个、再查哪个、查不到怎么办”这时候Workflow就撑不住了必须上Agent架构。1.2 为什么这个区分如此重要因为两者的调试方式和成本结构完全不同。Workflow的bug是确定性的你打断点一步步跟就能找到问题。Agent的bug往往是非确定性的——同样的输入模型这次决定调工具下次可能直接编一个答案。你得用完全不同的思路去排查。更现实的是成本。Workflow的token消耗是可预测的Agent因为可能多轮循环调用工具token消耗可能翻好几倍。我那个运维告警分析Agent单次复杂告警的分析成本大约是简单Workflow方案的4到6倍。如果一开始没想清楚就上Agent预算很容易失控。我的建议是先用Workflow把业务跑通确认“动态决策”确实是刚需之后再引入Agent架构。不要为了用Agent而用Agent。2. Agent的核心骨架四个模块缺一不可抛开各种框架的包装一个能跑的Agent本质上就是四个东西的组合大脑LLM、记忆Memory、工具Tools、循环控制Loop。我逐个拆。2.1 大脑选型不是越强越好选模型这件事很多人有个误区——直接上最强的。但实际项目里我更多考虑的是指令遵循能力和结构化输出稳定性而不是纯粹的推理能力。原因很简单Agent的核心动作是“根据当前状态决定下一步”这要求模型能稳定地输出结构化的决策比如JSON格式的工具调用指令。一个推理能力稍弱但指令遵循极好的模型往往比一个推理强但输出格式飘忽的模型更适合做Agent。我目前的常用组合是主决策用DeepSeek系列或Claude系列因为它们在工具调用格式的稳定性上表现很好一些简单的子任务比如结果摘要、格式转换用更轻量的模型控制成本。这里有个实操细节温度参数一定要调低。Agent的决策需要确定性我一般把temperature设在0.1到0.3之间。设太高的话同样的输入模型可能给出完全不同的工具调用决策调试起来非常痛苦。2.2 记忆设计短期和长期要分开处理记忆这块是最容易被低估的。很多人以为把对话历史一股脑塞进context就行了但实际项目里这样做很快就会撞到两个墙context长度限制和信息噪音。我的做法是把记忆分成两层短期记忆就是当前任务的对话历史用滑动窗口管理只保留最近N轮。N的取值取决于任务的复杂度我一般设8到12轮。超出窗口的旧对话用一个轻量模型做摘要压缩把关键信息保留下来。长期记忆是跨会话的比如用户的偏好、历史交互中积累的事实性知识。这部分我通常用向量数据库存检索的时候按相关性召回。但这里有个坑不是所有历史信息都值得存。我早期版本把所有对话都存进向量库结果检索出来的内容噪音极大反而干扰了模型的判断。后来改成只存“经过确认的事实”和“用户明确表达的偏好”效果好了很多。2.3 工具设计粒度比数量重要工具是Agent的手脚。我见过很多项目恨不得给Agent接几十个工具觉得能力越强越好。但实际跑下来工具太多反而会降低Agent的表现因为模型在决策时要在太多选项里选容易选错。我的经验是工具的数量控制在5到8个以内每个工具的职责要单一且清晰。比如“查询数据库”和“格式化输出”应该是两个工具而不是一个工具里塞两种功能。工具的描述description写法极其关键。这不是写给人看的文档是写给模型看的“使用说明书”。我总结了几条描述里必须说清楚什么时候该用而不只是“这个工具能做什么”参数说明要给出具体的格式示例不要指望模型自己猜如果有调用限制比如频率限制、参数范围一定要写进去举个例子我那个制度学习助手里有个“检索条例”工具最初的描述是“根据关键词检索相关条例”。结果模型经常在不需要检索的时候也去调它。后来改成“当用户的问题涉及具体条例内容且你不确定答案时使用此工具检索。如果问题是一般性概念解释不要调用此工具。”调用准确率立刻上去了。2.4 循环控制必须设止损Agent的执行是一个循环思考→行动→观察→再思考。这个循环必须有终止条件否则模型可能陷入死循环反复调用同一个工具。我一般设三重保险最大迭代次数通常设5到8次超过就强制终止并返回当前最优结果重复检测如果连续两次调用了相同的工具且参数相同直接中断超时控制整个Agent执行设一个总超时比如30秒这三条看起来简单但少了任何一条线上都可能出事故。我就遇到过模型反复调用搜索工具十几次的情况token烧了一大把最后返回的结果还不如第一次的。3. 从零搭建一个制度学习助手的完整实现路径光讲理论没意思我拿实际做过的“制度条例学习助手”为例把搭建过程完整走一遍。这个项目的需求是员工用自然语言提问Agent能准确找到相关制度条款并给出解释。3.1 第一步知识库的准备和切分制度类文档有个特点条款之间有强关联。比如“报销标准”和“审批流程”往往分散在不同章节但用户提问时经常需要同时引用。我的切分策略是按条款切分但保留层级上下文。具体做法是每个chunk不仅包含条款正文还带上它所属的章节标题和父级条款编号。这样检索出来的时候模型能看到完整的上下文路径。切分粒度上我试过按固定字数切比如500字一段效果不好因为经常把一条完整的制度切碎。后来改成按语义边界切——以条款编号为天然分隔符一条就是一条太长的再按段落细分。这样每个chunk的语义完整性最好。向量化模型我用的是BGE系列的中文模型在中文制度文本上的检索效果比通用模型好不少。这里有个细节制度文本里的专有名词很多纯向量检索有时候会漏掉关键词精确匹配的结果。所以我在向量检索之外还加了一路BM25关键词检索两路结果做融合排序。这个混合检索的方案召回率比单用向量检索提升了大概20%。3.2 第二步Agent的决策逻辑设计这个Agent的核心决策链是这样的接收用户问题判断问题类型是概念解释、具体条款查询、还是跨条款的综合问题根据类型决定检索策略单次检索、多次检索、还是直接回答拿到检索结果后判断信息是否充分不充分则调整关键词重新检索充分则组织答案这个逻辑我用的是ReAct模式——Reasoning Acting。模型先输出一段思考Thought然后决定动作Action执行后观察结果Observation再进入下一轮思考。实际写prompt的时候我会把决策逻辑用few-shot的方式给模型几个示例。比如用户问出差住宿标准是多少 Thought: 这是一个具体的条款查询需要检索制度库。 Action: 检索条例 Action Input: {query: 出差住宿标准} Observation: [检索结果] Thought: 检索到了相关条款信息充分可以回答。 Action: 最终回答给两三个这样的示例模型就能很好地遵循这个决策模式。比纯文字描述规则有效得多。3.3 第三步工具的具体实现这个项目里我定义了四个工具工具名称功能调用时机检索条例向量关键词混合检索需要查找具体条款时获取条款详情根据条款ID获取完整内容检索结果需要展开时关联条款查询查找与某条款相关的其他条款需要跨条款综合时计算器处理涉及金额、天数的计算问题涉及数值计算时每个工具的实现都不复杂关键是返回结果的格式要统一且对模型友好。我统一用JSON格式返回包含状态码、内容和元信息。这样模型解析起来不容易出错。有个细节值得说检索工具返回的结果要控制数量。我一开始返回top 10结果context被塞满模型反而抓不住重点。后来改成返回top 3到5并且每条结果附带一个相关性分数让模型自己判断哪些真正相关。3.4 第四步Prompt的迭代过程Prompt不是一次写好的是迭代出来的。我记录了这个项目prompt的四个版本V1简单描述任务工具列表。结果模型经常不调工具直接编答案。V2加了“必须基于检索结果回答”的约束。结果模型变得过于保守简单问题也要检索。V3加了问题分类的判断逻辑。结果好了一些但跨条款问题的处理还是不行。V4加入few-shot示例明确的决策树描述。结果基本可用了。这个过程让我深刻体会到Agent的prompt工程和普通对话的prompt工程是两回事。普通对话prompt重点是“说清楚要什么”Agent的prompt重点是“说清楚什么时候做什么”。4. 那些让我熬夜排查的坑这部分是我最想分享的因为这些都是文档里不会写、但实际项目中一定会遇到的问题。4.1 工具调用的“幻觉参数”模型调用工具时参数是它自己生成的。问题在于它有时候会生成看起来合理但实际不存在的参数。比如我的“获取条款详情”工具需要一个条款ID作为参数。模型有时候会编一个ID出来格式看起来完全正确但数据库里根本没有这条记录。更麻烦的是它编造的ID有时候恰好对应另一条不相关的条款导致返回了错误的内容而模型还一本正经地基于错误内容回答。我的解决方案是在工具层面做严格的参数校验。ID不存在就直接返回错误信息并且明确告诉模型“该ID不存在请重新检索获取正确的ID”。这样模型收到错误反馈后会重新走检索流程。加了这层校验之后这类问题基本消失了。4.2 多轮对话中的“上下文污染”这个坑很隐蔽。当用户在一个会话里连续问多个问题时前面问题的检索结果会留在context里。模型在回答新问题时可能会误用前面问题的检索结果。我遇到过一次用户先问了“年假天数”Agent检索到了年假相关条款。然后用户接着问“病假怎么算”模型居然基于年假的条款来回答病假问题。原因就是context里年假的检索结果还在模型偷懒没有重新检索。解决办法是在每轮新问题开始时显式地清理上一轮的检索结果只保留对话历史中的用户问题和最终回答中间的工具调用过程不带入下一轮。这个改动看起来简单但效果立竿见影。4.3 流式输出和工具调用的冲突为了用户体验我一开始用了流式输出。但Agent场景下模型可能在输出到一半的时候决定调用工具这时候流已经发出去了没法收回。我的处理方式是分段流式模型的思考过程Thought不流式输出等它决定动作之后如果是最终回答再流式输出给用户如果是工具调用就静默执行执行完继续下一轮。这样用户看到的是“思考中...→正在查询...→回答”体验反而更清晰。4.4 成本失控的隐形杀手前面提过Agent的token消耗可能很高但具体高在哪里我复盘了一下系统prompt太长工具描述决策规则few-shot示例加起来可能有两三千token每一轮都要带上检索结果太长如果返回的chunk太大每轮都要消耗大量token无效循环模型反复调用工具但不产生有效进展针对这三点我分别做了优化系统prompt精简到必要信息把few-shot示例从5个减到2个检索结果做截断每个chunk控制在300字以内加了循环检测机制。综合下来成本降低了大约60%。5. 多Agent协作什么时候需要怎么拆单Agent能搞定的事情不要上多Agent。这是我踩过坑之后的结论。5.1 多Agent的适用场景我目前只在一种情况下会用多Agent任务可以清晰地拆分成多个独立子任务且子任务之间需要不同的工具集或不同的prompt策略。比如我那个电商客服辅助Agent最终拆成了三个子Agent一个负责理解用户意图和分类一个负责查询订单和物流信息一个负责生成回复话术。拆开的原因是查询订单需要数据库工具生成话术需要风格控制的prompt这两者的工具集和prompt策略完全不同放在一个Agent里会互相干扰。5.2 拆分的代价多Agent不是免费的。每增加一个Agent就增加一次模型调用增加一层通信开销增加一个可能出错的环节。我最初把制度学习助手也拆成了多Agent结果发现拆分之后意图分类Agent经常把问题分错类导致后续Agent拿到错误的输入。而且Agent之间的信息传递需要序列化和反序列化延迟明显增加。后来改回单Agent反而更稳定。所以我的建议是先用单Agent跑遇到明确的瓶颈再拆。拆分的信号通常是工具数量超过10个、prompt里需要处理明显冲突的多种任务类型、或者不同子任务需要不同的模型。5.3 通信机制的设计如果确实需要多Agent通信机制我推荐用共享状态而不是直接消息传递。具体来说就是维护一个全局的state字典每个Agent读写自己负责的字段。这样比Agent之间直接发消息更容易调试也更容易追踪每一步的状态变化。编排方式上我用过两种一种是中心化编排有一个主Agent负责调度子Agent另一种是流水线式子Agent按固定顺序执行。前者更灵活但更难调试后者更简单但灵活性差。实际项目里如果任务流程相对固定流水线式就够了没必要上中心化编排。6. 部署上线的工程化考量Agent在本地跑通和上线稳定运行中间隔着一道巨大的鸿沟。这部分讲讲工程化的事。6.1 可观测性没有日志就是盲人摸象Agent的调试难度远高于普通应用因为它的行为是非确定性的。没有完善的日志你根本不知道它为什么做了某个决策。我的做法是记录每一次模型调用的完整信息输入prompt、输出内容、工具调用决策、工具返回结果、耗时、token消耗。这些日志按会话ID串联起来出问题的时候可以完整回放整个决策链路。我用的方案是结构化日志每条记录是一个JSON包含trace_id、step、action、input、output、latency等字段。查询的时候按trace_id过滤就能看到一次完整执行的所有步骤。6.2 降级策略模型挂了怎么办线上环境什么都会发生模型API超时、限流、返回格式异常。必须有降级方案。我的降级策略分三级重试模型调用失败先重试2次带退避降级模型主模型不可用时切换到备用模型通常是更轻量但更稳定的兜底回复所有模型都不可用时返回预设的兜底话术并记录日志关键是降级要自动触发不能等人工发现。我设了监控告警模型调用失败率超过5%就自动切换。6.3 评测怎么知道Agent变好了还是变差了Agent的迭代很容易出现“修好一个case弄坏另一个case”的情况。所以必须有一套评测机制。我建了一个测试集包含50到100个典型问题覆盖各种场景简单查询、复杂综合、边界情况、对抗性输入。每次修改prompt或工具之后跑一遍测试集看通过率的变化。评测指标我用三个准确率回答是否正确、工具调用准确率该调工具的时候调了不该调的时候没调、平均耗时。这三个指标要一起看不能只看准确率——有时候准确率上去了但耗时翻倍用户体验反而下降。6.4 安全边界Agent不能什么都做Agent有工具调用能力意味着它能执行实际操作。这就必须有安全边界。我的原则是所有写操作都要经过确认。Agent可以查询、可以计算、可以生成内容但如果要执行写数据库、发消息、改配置这类操作必须有一个确认环节。可以是让用户确认也可以是走审批流程。另外工具的参数要做白名单校验。比如“查询订单”工具订单ID的格式必须符合规范不符合的直接拒绝防止注入类攻击。7. 关于学习路径和框架选择的一些实话最后聊聊大家最关心的两个问题学什么、用什么框架。7.1 学习路径别从框架开始我见过太多人一上来就学LangChain学了一堆API但不知道底层在干什么。我的建议是先用原生API手写一个最简Agent——就是前面说的四件套LLM调用、一个工具、一个循环、一个简单的记忆。手写一遍之后你对Agent的理解会完全不一样再去看框架的源码会发现它们只是把这些东西包装了一下。手写Agent大概需要200行左右的代码但这一遍走下来你会真正理解prompt是怎么组织的、工具调用是怎么解析的、循环是怎么控制的。这些理解在调试框架问题的时候至关重要。7.2 框架选择看你的真实需求目前主流的Agent框架我基本都用过简单说说各自的适用场景LangChain/LangGraph生态最全工具集成最多。适合快速原型验证。但抽象层多出问题的时候排查链路长。LangGraph在编排复杂流程上比LangChain更清晰。AutoGen多Agent协作场景下比较成熟对话驱动的编排模式很自然。但单Agent场景下有点重。CrewAI角色扮演式的多Agent框架概念清晰上手快。适合任务能清晰分配给不同角色的场景。原生手写最灵活最可控调试最容易。适合对稳定性和成本有要求的线上项目。我的实际选择是原型阶段用LangChain快速验证线上版本用原生手写。这样既有开发效率又有运行时的可控性。7.3 一个容易被忽略的能力评估和迭代Agent开发中写代码可能只占30%的时间剩下70%的时间都在做评估和迭代。你需要不断地构造测试用例、跑评测、分析bad case、调整prompt或工具、再跑评测。这个过程很枯燥但它是Agent从“能跑”到“好用”的必经之路。我建议在项目一开始就建立评测机制不要等到上线前才想起来。我在实际项目中的体会是Agent开发最难的从来不是技术本身而是对业务场景的深刻理解。你得知道用户会怎么问、哪些问题是高频的、哪些边界情况必须处理。这些不是看文档能学到的得在实际场景里泡出来。