做Agent开发一段时间下来我最大的感受是大模型本身不是瓶颈怎么把一个“只会聊天”的大模型变成能规划任务、调用工具、记住上下文、最后自己把活干完的Agent才是真正考验工程能力的地方。这篇大模型Agent开发全指南不画饼直接从概念、架构、框架选型、完整实操到高频踩坑一层层拆开讲。内容覆盖从基础原理到生产级落地适合三类人看刚入门想搞清楚Agent到底是什么的新手写过Prompt但没做过完整Agent项目的开发者以及已经踩了不少坑、想系统化梳理经验的老手。文里的代码和步骤都来自我实际跑过的项目主案例是一个电商客服Agent后面统一叫它AgentX你可以直接照抄再按自己的场景去改。1. 先把概念揉碎了Agent到底解决了什么问题1.1 大模型和Agent之间差的不止一个提示词先把一个误区拆掉把大模型接进对话框加一段“你是一个智能助手”的System Prompt这不叫Agent。大模型本质是概率语言模型能力边界是“生成下一个词”。你跟它说“帮我订一张明天去上海的机票”它能给你写出一段像模像样的回复但它没法真的查航班、比价、下单。因为它的训练数据里没有实时航班信息也没有操作外部系统的接口。换句话说大模型是“知道怎么说”不是“知道怎么做”。Agent的本质是在大模型的“大脑”外面接上规划、记忆、工具、行动四个模块让模型从“会说话”进化成“会办事”。我常打一个比方大模型是刚毕业的高材生聪明、知识面广但没有工位、没有电脑、没有工作流程Agent是给这个高材生配了工位、发了电脑、定了KPI还配了个秘书记忆系统的完整组织。这个差异直接决定了开发复杂度。做纯大模型应用你只管Prompt和输出解析做Agent你得管任务分解、上下文管理、工具调用失败恢复、死循环兜底、多轮记忆持久化。这也是为什么Agent项目普遍比Chatbot项目难做坑也多得多。1.2 Agent的四种核心能力缺一不可我把Agent的能力拆成四块每一块都要独立设计、独立测试规划能力面对复杂目标能拆成子任务并决定先后顺序和依赖关系。比如“帮我策划一场线下读书会”不能上来就写方案得先拆成定主题、选场地、定时间、邀嘉宾、做物料、安排流程。记忆能力能记住当前对话的上下文短期记忆也能从历史交互中提取长期偏好和事实长期记忆。没有记忆的Agent每轮对话都是“第一次见面”体验非常割裂。工具能力能识别何时需要调用外部能力通过函数调用、API、代码执行等方式完成操作比如查天气、查数据库、发邮件、调内部服务。行动能力能把规划变成实际动作并根据动作结果决定继续执行、调整方案还是终止。这是Agent闭环的关键也是工程上最容易出问题的地方。这四个能力不是四选一而是层层叠加。最简Agent可能只有“工具能力”复杂的企业级Agent则四者全要而且每一块背后都是一堆工程细节。1.3 先判断清楚你的场景真的需要Agent吗不是所有需求都值得上Agent这个判断做错了后面全是白干。适合Agent的场景有几个共性任务需要多步推理必须调用外部系统或实时数据输入是开放式的没法用固定规则穷举用户需要多轮交互且上下文会影响后续决策。典型例子是智能客服、个人助理、数据分析助手、自动化运维、知识库问答加自动处理。不适合的场景也很明显单轮问答传统检索加Prompt就够流程完全固定用状态机或工作流引擎更稳对响应延迟极敏感Agent每轮要多次调用模型延迟天然偏高容错率极低比如直接操作支付、删除数据这类动作让模型自主决定风险很大。实操心得判断标准就一句话——如果你的业务能用一张状态图画清楚就别用Agent只有当分支路径多到状态图画不完或者用户输入无法预判时Agent的“自主决策”才有价值。2. Agent架构拆解四大模块逐个讲透2.1 规划模块让模型学会“先想后做”规划是整个Agent的龙头。现在工业界最主流的规划模式有三种我按实际落地频率排序。第一种是ReAct模式让模型交替输出思考Thought和动作Action。它的好处是简单直接一个循环就能实现模型每走一步都能看到工具返回结果再决定下一步。缺点则是长任务容易走偏需要外部兜底。第二种是Plan-and-Execute模式先让模型产出一份完整计划再按计划逐步执行。它的优点是全局视角更好任务分解清晰尤其适合步骤明确的流程。缺点是环境一旦变化原计划可能失效所以要加“重新规划”的触发机制。第三种是更复杂的树状或图状规划模型同时探索多条路径再择优。效果上限高但实现成本也高目前在多数生产项目里用得还不算多更多出现在研究原型里。规划模块的工程核心是给模型足够明确的“思考脚手架”。我见过很多失败案例不是模型能力不行而是Prompt里只写了一句“请帮我完成任务”模型根本不知道该怎么思考。正确做法是在System Prompt里把规划规则写死任务拆解粒度、步骤上限、什么时候该用工具、什么时候该放弃、输出格式是什么。2.2 记忆模块短期、长期、工作记忆三层联动记忆是Agent区别于普通对话模型的核心之一。我习惯把记忆分成三层。短期记忆就是当前对话的上下文直接塞进模型输入对应的是模型上下文窗口。它的管理重点是控制长度后面实操部分我会重点讲。长期记忆是跨会话的持久化信息比如用户的收货地址、之前的订单偏好、项目背景资料。常规做法是把这些信息结构化存储或者切块后做向量化在需要时检索相关片段拼进上下文。工作记忆则是Agent在单次任务执行过程中产生的中间结果比如工具返回的数据、已完成的子任务结论、待办清单。工作记忆通常放在Agent运行时的状态对象里不进向量库任务结束就清理。三层记忆的分工我总结成一句话短期记忆管“当前话题”工作记忆管“执行进度”长期记忆管“用户是谁、背景是什么”。很多Agent做出来像个“健忘患者”就是因为只做了短期记忆而后两层完全没设计。注意长期记忆不是越多越好。检索出来的信息如果和当前任务无关反而会干扰模型决策。检索阶段一定要做相关性过滤和去重宁可少给不要给脏。2.3 工具模块Function Calling的机制与Schema设计工具是Agent的“手脚”。现在主流大模型都支持函数调用模型根据用户问题和工具定义输出一个结构化的调用请求应用层解析后执行真实函数再把结果返回给模型。核心机制可以理解成工具定义是一份“说明书”模型在说明书里挑一个合适的函数填好参数然后你的代码负责执行。模型不直接操作任何系统所有权限和控制都在你这边。工具定义Schema怎么写直接决定调用成功率。我踩过不少坑总结出几个关键点。函数名和参数名要语义清晰一个叫get_order_info的函数比叫query_xxx的调用成功率高得多。参数描述要写清楚边界比如status参数要说明“仅支持pending、paid、shipped、cancelled四种取值其他值返回错误”。描述含糊会导致模型乱填参数。同一时间暴露给模型的工具数量要控制一屏超过20个工具模型选择准确率会明显下降。能合并的合并不常用的工具要分页或分层暴露。工具返回结果也要讲究。返回给模型的内容应当结构清晰、精简不要把整个数据库原始记录都怼回去。一般做法是用自己的代码把原始结果清洗成摘要再交给模型做下一步决策。2.4 行动模块循环控制与终止条件行动模块是承接规划和工具的“发动机”核心是一个循环模型产出决策系统执行工具结果回填再让模型继续决策直到满足终止条件。这个循环至少要有四道保险。最大迭代次数防止模型陷入无限循环一般单任务设10到20轮超过就强制终止并提示用户。终止条件判定即当模型认为任务已完成的信号出现时必须能准确识别并退出不能继续没话找话。异常回退工具调用报错时要把错误信息结构化成模型能理解的文本让它决定重试、换方案还是向用户求助。权限拦截凡是涉及支付、删除、修改等敏感操作必须走人工确认不能由模型直接执行。行动模块最常见的失败模式是“模型自嗨”它以为自己调了某个工具实际上你的代码根本没收到调用请求它只是在文本里编造了调用结果。这个问题的排查方法很朴素——在日志里把每一次模型输出、工具调用、返回结果全部打点一眼就能看出模型是不是在编。3. 框架选型的思路别被“全家桶”绑架3.1 先看清框架的四个层次Agent开发工具链现在非常热闹但归纳起来是四个层次很多人选型混乱就是因为没分清自己在哪一层。第一层是模型接入层只负责把大模型API包一层提供对话和流式输出。第二层是Prompt编排层提供模板管理、链式调用、输出解析适合做固定流程应用。第三层是Agent运行时层内置了规划循环、工具调用、记忆管理、多轮对话状态机这是我现在做生产项目最常待的一层。第四层是可视化多Agent平台拖拽节点就能编排多个Agent协作适合快速验证但深度定制时会碰壁。选型最大的误区是拿第四层的预期去选第二层的工具然后发现大量底层逻辑要自己补。我建议反过来先用第三层的框架把业务跑通跑通之后再决定要不要换。3.2 不同规模项目的选型参考我用一个表格把选型思路整理出来这个表是按我真实项目的经验总结的不是官方指标项目类型推荐路径原因快速验证Demo可视化多Agent平台零代码拖拽一天出原型先验证业务价值内部工具类AgentPrompt编排层轻量框架流程相对固定链式调用够用维护成本低生产级单AgentAgent运行时层框架内置循环、记忆、工具管理工程底座完整复杂多Agent协作自研编排 成熟模型接入通用框架的多Agent调度和状态管理通常不够灵活我自己的偏好是能不用框架就不急着用框架先用原生代码跑通一个最小Agent循环再去选框架。因为只有亲手写过循环你才知道框架帮你省了什么、又替你藏了什么出问题时才不会抓瞎。3.3 模型选择的几个关键指标选模型比选框架更影响最终效果。我重点看五个指标。函数调用能力是第一位的直接决定工具模块靠不靠谱这个必须用你自己的工具集做评测不能只看榜单。上下文长度决定了短期记忆窗口的上限但别迷信长上下文越长越贵越长越慢优先考虑压缩而不是无限加长。指令遵循能力影响Agent能否严格按你的规划规则执行这个和函数调用一起测。推理成本和延迟是经济账高频场景下成本和延迟往往比效果更先卡脖子。最后是稳定性同一个模型在线上反复调用的输出一致性决定了你要不要加大量重试逻辑。关于小模型我的观点是开源小模型做Agent不是不行但要非常克制。简单工具调用、单轮任务可以胜任复杂规划、长链路推理目前还是大模型更稳。先用商用大模型把业务跑通再把高频子任务切给更小更便宜的模型是很多团队实际在走的降本路径。4. 完整实操从零搭一个电商客服Agent4.1 需求拆解与AgentX的整体设计AgentX要处理的场景非常典型用户咨询订单状态、申请退货、咨询优惠券、投诉物流。这些任务看起来是FAQ但背后要查真实数据而且不同意图的处理路径完全不同。我把需求拆成三块。意图识别与路由判断用户是想查订单、退货还是投诉这决定后续走哪条工具链。信息查询根据用户提供的订单号去订单系统里查状态和物流。业务动作退货申请要校验条件、写工单、给用户回执。整体设计上AgentX采用ReAct循环记忆用短期上下文加长期用户画像两层工具侧暴露三个函数查订单、查物流、申请退货。系统提示词里写死了两条铁律涉及金额和地址修改时必须二次确认查不到真实数据时绝不能编造物流状态。4.2 系统提示词与工具Schema示例系统提示词我习惯拆成四段角色与目标、可用工具清单、处理规则、输出格式约束。核心代码如下这是简化版但结构可以复用你是某电商平台的客服AgentX。 你的目标解决用户在订单、物流、退货方面的真实问题。 可用工具查询订单信息、查询物流轨迹、提交退货申请。 处理规则 1. 用户没有提供订单号时先询问不要猜测。 2. 所有工具返回的数据必须如实转述查不到就明确说查不到。 3. 退货申请必须核对订单状态和退货原因条件不符时拒绝并说明原因。 4. 涉及地址、金额变更的操作必须向用户二次确认后再执行。 输出格式采用Thought/Action/Action Input/Observation格式执行最终答案必须是对用户友好的自然语言。工具Schema长这样注意每个字段的描述都写清了取值边界[ { name: get_order_info, description: 根据订单号查询订单基本信息包括订单状态、商品、金额、收货地址。, parameters: { type: object, properties: { order_id: { type: string, description: 用户提供的完整订单号形如ORD-2025-001234必须是有效格式 } }, required: [order_id] } }, { name: get_logistics_track, description: 查询订单的物流轨迹返回揽收、转运、派送等节点信息。, parameters: { type: object, properties: { order_id: { type: string, description: 关联的订单号 } }, required: [order_id] } }, { name: apply_return, description: 提交退货申请仅当订单状态为已签收且未超过七天时可用。, parameters: { type: object, properties: { order_id: { type: string, description: 订单号 }, reason: { type: string, description: 退货原因限填质量问题/七天无理由/发错货 } }, required: [order_id, reason] } } ]实操心得函数描述里那句“形如ORD-2025-001234”不是废话。模型对格式的理解完全依赖描述里的例子你给什么样的示例它就按什么样去解析这是提升工具调用成功率成本最低的一招。4.3 ReAct主循环实现主循环是所有Agent的发动机我用的简化实现如下。这段代码不依赖任何第三方框架目的是让你看清循环的本质import json import time MAX_STEPS 10 def run_agent(user_message, memory, tool_executor): messages [{role: system, content: SYSTEM_PROMPT}] messages.extend(memory) # 历史上下文 messages.append({role: user, content: user_message}) for step in range(MAX_STEPS): # 调用模型要求它输出Thought/Action格式 response model_chat(messages) content response[content] print(f[Step {step}] {content}) # 解析模型的Action字段 action extract_action(content) # 模型认为任务已结束 if action is None: final_answer extract_final_answer(content) return final_answer # 模型想调用工具 if action[name] in tool_executor: result tool_executor[action[name]](**action[arguments]) observation {observation: result} else: observation {observation: tool_not_found} # 把模型这轮的输出和工具结果都追加到消息序列 messages.append({role: assistant, content: content}) messages.append({role: tool, content: json.dumps(observation, ensure_asciiFalse)}) return 抱歉这个问题比较复杂已经转人工处理。model_chat是统一封装的模型接口tool_executor是工具注册表extract_action负责从模型文本里解析结构化动作。这里最关键的细节是消息序列的累积方式模型的每一轮输出和每一次工具返回都要按顺序追加模型才能看到完整的思考链路。丢一环后面的决策就断了。4.4 记忆与上下文压缩ReAct循环跑几轮之后上下文会快速增长。长对话里用户的问题可能很简单但前面的思考过程、工具返回日志全都在输入很快就臃肿了。AgentX上线第一周就遇到上下文超限我当时的处理方案是“摘要压缩”。每经过N轮就把之前的对话交给模型生成一段摘要用摘要替换掉原文只保留最近两轮完整对话。代码如下def compress_history(messages, keep_last2): # 找出可以压缩的历史部分从system之后到倒数keep_last轮之前 history messages[1: -keep_last * 2] if len(messages) keep_last * 2 else [] if len(history) 4: return messages # 让模型把history压成一段摘要 summary_prompt 请把以下Agent运行日志压缩成一段摘要保留用户诉求、已执行的动作、关键结论不超过200字\n json.dumps(history, ensure_asciiFalse)[:6000] summary model_chat([{role: user, content: summary_prompt}])[content] # 用摘要替换历史部分 new_messages [messages[0], {role: system, content: f对话历史摘要{summary}}] new_messages.extend(messages[-keep_last * 2:]) return new_messages长期记忆我另建了一张简单的用户画像表当用户在对话里提到偏好比如“我一般用顺丰”会抽出来写进用户画像后续会话开始前自动注入。这里要注意抽取偏好也要走模型但触发条件必须严格控制不能在每轮对话都做抽取否则成本会失控。4.5 部署与监控一个被很多人忽略的环节AgentX上线前我把很大精力花在监控上。Agent的输入输出不是固定结构的传统接口监控根本不够。我给整个系统加了三层日志。第一层是完整链路日志记录每一次模型请求的输入、输出、工具调用、返回结果、耗时和Token数一条都不能漏。第二层是运行时状态快照每轮循环结束后记录当前的消息长度、累计Token、步数用于事后复盘。第三层是用户反馈埋点在对话结束时让用户点“满意/不满意”不满意的话自动保存全链路日志供人工分析。监控数据积累一周后你会非常直观地看到哪类问题导致Agent频繁重试哪些工具调用失败率最高哪些Prompt场景下模型输出格式经常解析失败。没有这套数据后续优化全部靠猜这是Agent项目里最要命的事。5. 实战中高频踩坑与排查技巧实录5.1 模型幻觉与编造工具结果Agent开发里最可怕的问题不是工具调用失败而是模型“假装调用成功”。它可能在文本里输出“已完成退货申请”但实际上你的代码根本没收到apply_return的调用请求。解决思路有三层。第一层是输出约束要求模型严格按照结构化格式输出动作凡是解析不到合法动作的一律视为“未执行”不给用户承诺。第二层是结果校验工具执行函数返回时必须带状态码异常状态要原样反馈给模型禁止模型自己脑补成功。第三层是话术兜底在System Prompt里写明“只有收到工具执行成功回执才能告知用户操作完成否则必须说‘系统正在处理请稍后’”。5.2 上下文爆炸与Token成本失控单个会话在长任务中轻松消耗几万甚至几十万Token这在Agent项目里非常普遍。成本失控通常不是模型的错而是工程没做好。我常用的三板斧压缩按前面说的摘要策略定期压缩历史检索长期记忆和资料不要全量塞而是向量化后只召回Top K分流低频子任务用便宜的小模型执行只有需要复杂推理时才上大模型。另外工具返回结果也要做裁剪按接口只把当前决策需要的字段返回给模型能省下大量重复Token。注意千万别用“截断”代替“压缩”。简单地把上下文从末尾砍掉等于让Agent失忆前面的任务信息全丢了后面它就会开始胡言乱语。截断只用于兜底压缩才是常规手段。5.3 Agent死循环与任务漂移Agent死循环有两种一种是字面意义的无限循环模型反复调用同一个工具或重复同一个动作另一种是任务漂移模型做着做着把最初的目标忘了开始回应与任务无关的内容。字面循环用最大迭代次数兜底就能解决问题不大。任务漂移要靠两件事一是把初始任务目标固化在System Prompt里并且每一轮都让模型自行核对“当前动作是否与目标一致”不一致就拉回二是在压缩摘要时必须保留“原始任务目标”这一项不能摘要一压就把任务初衷压没了。我在AgentX里就在压缩模板里强制加了“原始用户诉求”字段实测下来任务漂移率降了不少。5.4 没有评测体系上线就是裸奔这是我最想强调的一点。很多团队把Agent做完就上线觉得“反正有AI兜底”结果线上事故频出。Agent的自主性意味着不可预测不可预测的系统的唯一防线就是评测。我从第一天起就建了一个评测用例集目前有几百条覆盖正常路径、异常路径、边界输入和对抗输入四类。每次改Prompt或换模型都在这个集上跑回归对比输出质量和工具调用准确率。选模型时的函数调用能力测试也用的是这同一套用例。线上还要设两个指标任务完成率和人工介入率。任务完成率是“Agent在无人工干预下成功解决用户问题的比例”人工介入率是“用户在对话中主动要求转人工的比例”。这两个指标一升一降就是Agent质量最真实的体检表。下面是我整理的高频问题速查表基本覆盖了Agent项目最常见的故障现象可能原因排查方式模型输出格式解析失败Prompt约束太弱或模型版本切换先看原始输出日志强化格式约束并增加重试工具调用参数总是错误Schema描述不清晰缺少取值边界给参数加示例值和枚举约束同一问题反复询问短期记忆被截断检查消息序列是否完整压缩策略是否过激进用户问A答B任务目标在历史中被冲淡在摘要中强制保留原始任务目标Token消耗暴增工具返回结果全量回填裁剪工具返回只保留决策所需字段Agent输出与业务口径不一致缺少规则校验层加一层规则引擎对关键输出做二次校验6. 进阶多Agent协作和复杂任务编排6.1 多Agent的三种协作模式单Agent能解决的业务终究有限复杂一点的场景就要上多Agent。基于我的项目经验多Agent协作有三种常见模式。第一种是路由模式一个入口Agent负责理解用户意图把请求分发给下游专业Agent比如订单Agent、售后Agent、优惠券Agent各管一段。好处是每个Agent的上下文很干净互不污染缺点是路由判断一旦出错整个链路就歪了。第二种是编排模式一个主Agent当“项目经理”拆解任务并调度多个执行Agent。执行Agent各自完成子任务把结果汇总给主Agent做最终输出。这种模式适合跨系统协同但主Agent本身可能成为瓶颈。第三种是群体协作模式多个Agent带着各自的视角互相讨论、评审最后达成共识。适合方案生成、代码评审这类需要多视角的场景但成本高、延迟高生产环境慎用。6.2 状态管理与数据流转多Agent最核心的工程问题是状态和数据怎么在多个Agent之间流转。我见过最乱的做法是把一个Agent的全部消息历史直接塞给另一个Agent美其名曰“交接上下文”结果下游Agent收到一堆无头无尾的日志效果一塌糊涂。正确做法是定义清晰的任务上下文对象。每个Agent只接收结构化输入和产出结构化输出中间数据放在共享状态容器里。比如入口Agent产出{user_intent: return, order_id: ORD-...}售后Agent只消费这个对象不关心入口Agent之前的内心戏。这样既隔离了上下文也方便每个环节单独测试和替换。另外多Agent之间的通信格式必须提前定好。JSON Schema是基本操作字段命名要全组统一最好再有版本号不然以后字段一变所有下游全部崩掉。6.3 成本与延迟多Agent的代价多Agent不是银弹它的代价非常具体。每多一个Agent就多一轮甚至多轮模型调用延迟和成本线性上升。一个四Agent协作的场景用户等一个答案可能要几十秒这在客服场景里几乎不可接受。我的优化思路是把多Agent用在“后台异步任务”上而不是用户实时交互链路上。比如用户提交申请后后台由一个几个Agent组成的流程去处理处理完再通过消息推送结果用户不需要一直干等。实时对话链路能单Agent解决就单Agent这是我从成本和体验两个维度反复权衡后的结论。7. 落地过程中的几个原则性体会写到最后我不打算做什么宏大总结就说几条在项目一线反复验证过的原则。第一Agent的可靠性不是靠模型“变聪明”堆出来的而是靠工程结构控制的。规划规则、工具Schema、日志、评测、兜底循环每一环都值得花时间打磨这些比换更强的模型更能提升整体表现。第二先跑通最小闭环再叠加记忆和多Agent。我见过太多项目一上来就设计六个Agent结果连单Agent的循环都没跑顺。一个稳定、可控、能部署的单Agent远比一个华丽但随时失控的多Agent体系有价值。第三不要把用户当测试者。Agent上了线每一句话都是对真实用户的承诺。宁可多转人工也不能把幻觉和错误结果直接甩给用户。给所有关键动作加权限校验层这是Agent工程里没有妥协空间的底线。最后分享一个小经验把每一条失败的线上案例都倒回你的评测集里。每遇到一次翻车就把它沉淀成一条回归用例再修Prompt、修逻辑直到这条用例通过。这样做的结果是你的评测集越跑越厚Agent的可靠性越修越稳——比起任何理论框架这一套笨办法才是最值得长期坚持的。