最近这半年我基本都在跟 AI Agent 较劲。从一个只会单问单答的聊天机器人一路改造成能自己拆任务、调工具、处理异常的智能体系统中间踩过的坑和沉淀的经验我觉得值得写一篇完整的 AI Agent 开发流程出来给准备上手或者已经在用框架但总感觉不受控的团队做个参考。先说清楚这是什么AI Agent 是一种能自主完成感知-决策-行动-反馈闭环的 AI 系统。跟传统的大模型接口调用不同Agent 不是问一句答一句而是给它一个目标它自己去拆解步骤、调用外部工具、根据中间结果修正下一步直到把目标真正完成。这篇内容围绕 Agent 开发的核心流程展开覆盖架构选型、模块拆解、代码实现、坑点排查适合从零搭建 Agent 的开发者以及想从写接口升级到写系统的技术同学。1. 先想清楚Agent 跟普通接口调用到底差在哪很多团队一开始都会把 Agent 理解成大模型加几个工具函数但真正动手以后才发现这两者的思维模式完全是两回事。如果你只是想让模型能够调个接口那确实不需要 Agent但如果你要的是让系统自己判断下一步该做什么那就必须从接口思维切换到流程编排思维。1.1 从单次问答到自主决策的跨越传统的大模型应用本质上是一个请求-响应模型用户输入一段话模型返回一段文本整个过程一次结束。哪怕你把它封装成了聊天机器人也只是把多轮对话存进历史记录里再一起发给模型而已。Agent 的核心差异在于引入了循环Loop。它不再是一次性输出答案而是不断重复思考 → 调用工具 → 观察结果 → 继续思考这个过程直到任务完成或达到上限。举个例子如果你让普通聊天机器人帮我查一下本周某个产品的销量并生成一份分析报告它大概率会告诉你我没办法访问数据库。但如果你给 Agent 配了数据库查询工具和文档生成工具它会自己规划先查销量数据再分析趋势最后生成报告文档甚至可以打开某个内部系统把数据导出来。这个循环看起来简单但设计起来有不少讲究。核心要解决三个问题第一模型怎么知道现在该调用哪个工具第二调用结果返回后模型怎么理解这些结果并决定下一步第三循环什么时候该停。这三个问题直接决定了你的 Agent 是靠谱的执行者还是失控的乱撞者。1.2 三种主流控制模式怎么选Agent 的内部决策模式目前业内基本可以归成三类ReAct 模式、Plan-and-Execute 模式先规划再执行、以及纯工具调用的瀑布模式。每一种都有适用场景没有绝对的好坏。模式核心逻辑优点缺点适合场景瀑布模式模型一次性生成完整的工具调用序列按顺序执行结构简单、延迟低、成本可控无法根据中间结果调整后续计划流程固定、步骤明确的场景ReAct 模式每走一步都让模型思考当前状态下一步行动灵活、能应对动态变化Token 消耗大、延迟高、容易跑偏开放性强、需要动态决策的任务Plan-and-Execute先让模型生成完整计划再逐步骤执行执行完回看校正效率高、可解释性强计划一旦出错执行阶段很难自救任务复杂、可预先规划的流程我自己的实际体会是不要一开始就迷信 ReAct。很多刚接触 Agent 的人会觉得 ReAct 最万能因为它最接近人类的思维方式。但 ReAct 模式每一步都要把完整的思考链和上下文发给模型成本会随着执行步数线性上升而且一旦模型在中间某一步产生幻觉后面就会越走越歪。对于业务场景相对固定的任务我更推荐Plan-and-Execute 关键节点检查的组合——先让模型生成计划执行到关键节点时做一次校验如果结果不符合预期再重新规划。这样既能保证灵活性又能把成本控制在合理范围。提示判断用哪种模式最简单的标准是看你的任务是否可预演。如果任务流程基本固定瀑布模式就够用如果任务中间会出现大量分支再用 ReAct如果任务整体可规划但细节需要动态调整那就是 Plan-and-Execute 的主场。2. 搭建 Agent 的四个核心模块确定好控制模式之后就要开始搭建 Agent 的各个组成部分了。一个完整的 Agent 系统至少包含四个模块模型层、工具层、记忆层和规划层。这四个模块不是简单拼在一起就行它们之间的协作机制决定了最终的稳定性。2.1 模型层不是所有模型都适合当 Agent 底座模型层是 Agent 的大脑选型直接决定了整个系统的天花板。做 Agent 用的模型跟做普通问答用的模型侧重点完全不同。第一是工具调用能力。普通问答模型只需要会写文本就行但 Agent 的模型必须能按照约定的格式输出我要调用哪个函数、参数是什么。现在主流的大模型服务商基本都提供了函数调用Function Calling接口模型会返回一个结构化的 JSON 对象里面包含函数名和参数。选型时必须实测模型在多工具、多参数场景下的准确率因为很多模型在只有一个工具时表现很好一旦工具列表超过十个就开始频繁选错工具或者漏传参数。第二是长上下文能力。Agent 执行任务的过程中每走一步都会积累新的观察结果。如果模型的上下文窗口不够大执行到中途就会出现前面说了什么已经不记得了的情况。我见过不少团队在选型时只看模型的问答分数忽略了上下文长度结果 Agent 跑到第五步就开始胡言乱语。实测下来上下文窗口至少要能容纳执行步数 × 每步的Token开销 × 2的余量否则就要在记忆层做截断策略。第三是推理连贯性。Agent 需要模型具备多步推理能力也就是能从数据 A 和 数据 B 对比得出结论 C然后决定执行 D。这个能力很难用单轮问答的测试集衡量建议自己构建一个包含多步骤依赖的测试集专门验证模型的推理链条是否会中断或跳步。2.2 工具层定义好 Agent 的手脚工具层是 Agent 与外部世界交互的接口它的设计质量直接决定了 Agent 的实用性。这里有个容易被忽视的关键点工具的描述信息比工具的实现逻辑更重要。模型的工具调用本质上是一个语义匹配过程——模型会根据自然语言描述来判断什么时候该用哪个工具。如果你的工具描述写得含糊模型就会在关键时刻选错。比如你有两个工具一个叫获取用户订单详情一个叫查询用户基本信息如果两个描述都有用户和订单字样模型就会搞混。我的建议是每个工具的描述里要明确写出这个工具做什么、什么时候用、参数分别代表什么含义、可能返回什么格式甚至给出一个具体的使用示例。下面是一个工具定义的示例这个结构已经是当前比较通用的标准{ name: query_order, description: 根据订单编号查询订单的详细信息包括商品列表、金额、物流状态。适用于用户咨询订单进度、发起售后等场景。, parameters: { type: object, properties: { order_id: { type: string, description: 订单编号通常是纯数字字符串例如 202501012345 } }, required: [order_id] } }注意几个细节参数描述里最好带上示例值因为模型对数字字符串的理解不够精确同时要把什么时候不该用这个工具也写进去比如如果用户还没有下单请先引导下单不要调用此工具。这类负向描述能显著降低误调用率。工具层还需要考虑幂等性。如果 Agent 因为超时或者网络抖动重复调用了某个工具会不会造成重复扣款或重复提交这些业务侧的兜底逻辑在设计工具接口时就要想清楚不能指望模型自己判断上一次是不是已经调用过了。2.3 记忆层让 Agent 不失忆记忆层又是一个容易被低估的模块。Agent 执行复杂任务时需要同时处理这轮对话讲了什么已经执行过哪些步骤之前查到的数据是什么这三类信息。我一般把记忆分成两层工作记忆和长期记忆。工作记忆就是当前任务的上下文包含用户的原始需求、已经执行过的步骤、以及每一步产出的中间结果。工作记忆通常以列表形式维护每次给模型的 prompt 里都会带上。长期记忆则是跨任务的信息比如用户的历史偏好、过去对话中提到的个人信息这些可以存在向量数据库里需要时通过语义检索把相关内容拉出来。这里有一个很关键的机制工作记忆的整理和压缩。模型每执行一步历史的原始信息都要重新发送一遍Token 消耗会越来越大。如果不做整理执行到后面光历史记录就能把上下文窗口塞满。我的做法是每轮循环结束后让模型产出一个当前状态摘要把已经完成的事情、当前掌握的数据、剩余未解决的问题压缩成一段简洁描述下一轮就只发送摘要加最新的观察结果。这一步看起来简单但对成本和稳定性都有质的影响。2.4 规划层任务拆解的核心逻辑规划层负责把一个大目标拆成可执行的小步骤。这个模块的设计取决于你选的控制模式但无论是哪种模式都需要定义清楚什么算完成。一个常见的错误是让模型无限自由地规划结果它给自己规划了二十步实际走到十步就失控了。我建议在规划阶段就设定约束最多个步骤数、每个步骤必须产出什么类型的中间产物、遇到哪些情况必须停下来向用户确认。规划层的自我校验也值得做。在 Plan-and-Execute 模式下模型执行完计划后我会额外让模型做一次复盘对比计划中的目标与实际产出看看是否存在遗漏或偏差。这个执行后校验环节能把很多跑偏的任务在早期拉回来而不是等到用户投诉才发现结果完全不对。3. 完整实操从零实现一个可用的 Agent理论拆解完接下来进入实战环节。我会按照实际开发的顺序一步一步把 Agent 系统的实现逻辑讲清楚。这一部分比较长但每段代码我都会解释关键设计的意图照着写基本能搭出一个可用的雏形。3.1 技术选型与环境准备搭建 Agent 的第一步是决定要不要用框架。目前开源的 Agent 编排框架确实不少有的提供了完整的 Agent 循环、记忆管理和工具接入方案开箱即用有的则只是一个模型调用封装灵活性更高。我的建议是如果你是第一次做 Agent可以用框架快速验证可行性但一旦业务场景复杂起来就要考虑自己掌控核心循环。原因是框架为了通用性做了大量的抽象当你的业务需要特殊处理时这些抽象反而会成为限制。我目前的做法是用框架管理基础的模型调用和工具注册但 Agent 的核心循环思考、调用、观察、再思考自己实现。这个思路既能享受框架的便利又不会被框架的默认行为绑架。环境准备方面Python 是目前 Agent 开发的主流语言基础依赖包括模型服务商的 SDK用于调用大模型接口、向量数据库客户端用于长期记忆、以及基础的 HTTP 客户端。如果你要把 Agent 封装成服务还需要考虑消息队列和任务存储这里不展开先聚焦核心逻辑。3.2 核心循环代码实现Agent 的灵魂是循环。下面这个代码示例展示的是一个最小可用的 ReAct 风格循环它虽然简洁但包含了 Agent 运行的所有关键节点class Agent: def __init__(self, model, tools, max_steps10): self.model model # 大模型客户端需实现 chat 方法 self.tools tools # 工具注册表dict: 名称 - 执行函数 self.max_steps max_steps self.messages [] def run(self, task): self.messages.append({role: user, content: task}) for step in range(self.max_steps): response self.model.chat(self.messages, toolslist(self.tools.keys())) messages.append({role: assistant, content: response}) # 判断模型是否要求调用工具 tool_calls response.get(tool_calls, []) if not tool_calls: return response.get(content) # 没有工具调用认为任务完成 # 执行工具调用并把结果作为新的观察回填到上下文 for call in tool_calls: tool_name call[name] tool_args call[arguments] observation self.tools[tool_name](**tool_args) self.messages.append({ role: tool, tool_name: tool_name, content: observation }) # 超过最大步数还没有返回结果主动结束 return 任务未在限定步数内完成请检查日志或调整规划。这段代码虽然只有二十多行但几个设计点很值得说道。第一max_steps是必须有的没有这个上限模型可能在一个任务里无限循环既浪费 Token 又卡死服务。第二工具的调用结果以tool角色回填到消息列表这是为了让模型在下一次推理时看到刚才发生了什么。第三当模型回复中没有工具调用时就认为任务完成并返回内容——这个判断逻辑简单但实际使用中要小心模型有时会偷懒没完成任务就假装结束所以后面还要加校验。3.3 工具调用与错误恢复的实现细节上面的核心循环把过程串起来了但真实的工程实现远没有这么顺滑。最大的问题出在模型输出的工具参数不总是合法的 JSON。模型有时会多给一个逗号、漏掉一个括号直接解析肯定会报错。我处理这个问题的方法分三层第一层解析前先做轻量清洗比如去除 markdown 代码块标记第二层如果 JSON 解析失败把错误信息反馈给模型让模型重新生成参数最多重试两次第三层如果重试仍然失败就把这个工具调用标记为异常继续让模型尝试其他路径而不是整个任务崩溃。import json def parse_tool_call(raw_content): 解析模型输出的工具调用带重试和清洗逻辑。 # 去掉可能的 markdown 包裹 cleaned raw_content.strip().removeprefix(json).removesuffix() try: return json.loads(cleaned) except json.JSONDecodeError: # 反馈给模型重新生成 return None另一个必须处理的场景是工具执行本身报错。比如查询数据库超时、下游接口返回 500这些错误信息要原样返回给模型。有一个心得体会不要替模型做判断直接把原始错误信息传回去让模型自己决定是重试还是换一种方式。如果你把错误美化成一句查询失败模型就无法理解失败的原因自然也无法做出正确的下一步决策。工具调用的超时控制也极其重要。有些工具执行一次要几十秒Agent 等不了那么久所以我的做法是每个工具调用都套一层超时和并发限制。工具执行时间超过设定阈值就直接返回超时错误让模型决定要不要继续等待或者换方案。这能避免某个慢接口拖垮整个 Agent 服务的吞吐。3.4 上线前的测试与评估Agent 的测试跟传统软件的测试有很大差别。传统软件的输入输出是确定的但 Agent 的行为有随机性——同一个任务跑十次结果可能十次都不一样。所以测试策略也要跟着变。我的测试体系分三层第一层是工具单元测试每个工具函数独立测试确保输入输出符合定义第二层是单步决策测试给定一个固定的上下文和状态验证模型是否会调用预期的工具、参数是否正确第三层是端到端任务测试构造一组覆盖主流程和边界场景的任务跑完整流程后人工评估结果质量。评估指标方面除了任务完成率我强烈建议记录这几个数字平均执行步数、单任务平均 Token 消耗、工具调用准确率、首次有效响应时间。这些指标能直接反映 Agent 的成本和效率。很多团队只盯着任务完成率忽略了完成这个任务花了多少步、烧了多少 Token等到上线才发现成本根本压不住。这里也分享一个提升评估效率的方法给每个测试任务标注预期路径。比如查销量并生成报告这个任务预期路径是调用查询接口 → 调用生成接口如果 Agent 走了别的路径但结果依然正确要人工看一遍确认是合理的替代路径还是偶然的巧合。这样既能保证质量也能逐步积累出模型行为的画像。4. 实战中踩过的坑与排查思路Agent 开发最大的特点就是看起来能跑但总是莫名其妙地出问题。这一节我把自己实际踩过的坑整理成一份问题速查表并附上排查思路希望能帮你少走弯路。4.1 上下文爆炸Token 开销失控这是新手做 Agent 时遇到最多的坑。任务执行到第五六步上下文已经塞进了大量工具返回结果Token 消耗急剧上升响应也开始变慢。本质原因是工具返回的完整原始内容全都被塞进了上下文。排查思路把每轮执行后的消息列表长度和 Token 用量打印出来找出占用最大的部分。通常会发现是工具返回的长文本比如数据库查询结果或者网页摘要。解决方案有两个方向一是做返回内容截断工具返回前先做摘要或者只保留前 N 条关键信息这一点在工具设计阶段就要考虑二是做历史摘要压缩如前面提到的每轮执行后让模型产出状态摘要替代完整的历史消息。我实测下来后者能把 Token 消耗降低一半左右但会增加一次额外的模型调用需要权衡。4.2 工具调用卡死无限循环与异常返回模型不是每次都能按你的预设逻辑执行。常见的问题是模型在两步之间反复调用同一个工具每次都得到相同结果却还在继续循环或者模型调用了一个不存在的工具名框架直接崩溃。针对无限循环除了设置最大步数之外我还加了一个检测机制如果同一个工具连续被调用三次且参数完全一样直接给模型注入一条提示你已经重复调用该工具多次请尝试其他方式或告知用户当前无法继续。这个机制看起来很简单但在实际业务中救了我很多次。针对不存在的工具名排查方向有两个。第一检查工具注册表的名称是否和传入模型列表的名称一致很多时候是名字大小写不匹配第二模型有时会自由发挥创建一个工具名这说明要么工具描述不够清晰要么模型的工具调用能力不足。如果频繁出现这种情况建议换一个工具调用能力更强的模型而不是在代码里打补丁。4.3 输出格式不稳定JSON 解析的连锁失败模型输出的 JSON 不稳定可以说是 Agent 开发者的老朋友了。除了前面提到的语法问题还有一种是语义正确但结构错误模型生成了合法的 JSON但字段名和你的预期不一致比如把order_id写成了orderId。排查和应对思路是在工具调用层做一层严格的参数校验器校验每个字段是否存在、类型是否正确而不是直接把原始参数透传给业务函数。如果校验不通过把缺了哪个字段、应是什么类型清晰地反馈给模型让它重新生成。这个反馈信息越明确重试的成功率越高。我见过很多团队只反馈参数错误模型完全不知道哪里错了就会陷入反复尝试的死循环。4.4 成本与延迟的平衡Agent 跑起来之后成本问题会逐渐暴露。每次循环都是一次模型调用任务一复杂成本就按倍数膨胀。这里我的经验是做模型分级不是所有环节都需要最强的大模型。我把规划阶段和最终结果汇总阶段用能力最强的模型中间的简单工具调用和结果判断用轻量模型。比如从查询结果里提取一个数字这种简单任务完全不需要大模型用轻量模型就能完成成本能降到原来的十分之一。延迟同理简单判断用快速模型复杂推理用慢但强的模型整体体验会好很多。成本还有一个隐藏的坑是重试机制带来的放大效应。如果你的 Agent 每次失败都会重试而且重试是整段循环重新来一遍成本就是成倍增加的。我建议重试粒度尽量缩小参数解析失败就只重发参数修正请求而不是把整个 Agent 循环重新跑一遍。关于 Agent 开发流程最后再啰嗦两句。我自己做完几个 Agent 项目后最大的体会是Agent 的难点不在调用模型而在设计和兜底你需要把它当成一个没有经验的实习生来对待——目标要拆清楚工具要给到位出错要能自己纠正实在不行要懂得停下来问人。先从一个最简单的循环跑通再逐步加工具、加记忆、加规划这个思路比一上来就堆一堆复杂模块要靠谱得多。另外日志记录一定要做充分Agent 的每一步输入输出都值得留痕因为它的行为是概率性的没有日志根本没法排查线上问题。希望这篇流程拆解能给你的 Agent 项目提供一些参考。