这些年聊大模型大家从最早的“能聊天”逐渐过渡到了“能不能帮我干点正事”。而“让大模型自己干活”这件事最直接的落地形态就是Agent。这个标题“大模型Agent开发入门”看起来很直白但真正接触过的朋友都知道从概念到能跑通一个像样的Agent中间隔着不少弯弯绕绕。我就结合自己折腾过的项目把大模型Agent开发这条路上的核心思路、框架选型、实操代码和踩坑经验一次说清楚希望能帮正准备入门的朋友少走几步弯路。这篇内容适合谁刚接触大模型开发、想做一个真正能执行任务的AI流程或者已经用过Prompt但总觉得“不太智能”的开发者。AI Agent能解决的问题是让大模型从“回答问题”变成“拆解任务、调用工具、执行动作、观察结果、修正路径”的完整闭环。如果你也想搭一个能查资料、能算数据、能调用业务系统接口的助手可以直接参考这里的思路。1. 为什么Agent成了大模型落地的主流形态1.1 大模型本身的局限会说话不等于会办事先聊一个基础问题大模型到底解决了什么简而言之它把“自然语言理解和生成”这件事的门槛拉到了极低。你扔给它一段话它能续写、总结、翻译、抽取信息甚至根据指令写代码。但这个能力本质上仍然是“概率化文本生成”它不负责执行动作也不感知外部世界的变化。举个例子你让大模型帮你查一下今天某地的天气。模型就算把“今天北京天气晴朗气温25度”这句回答写得天花乱坠它也不知道北京今天到底下没下雨。它只是根据训练数据里的统计规律生成了一段看起来合理的文本。如果你问它“帮我订一张明天去上海的机票”它最多给你写一个订票攻略但它没法真的打开航司系统完成下单。这就是大模型的边界知识有截止日期、无法感知实时状态、无法主动调用外部API、也不能自主完成多步操作。Agent的定位恰恰就是在大模型外面包一层“手”和“眼”让它能调用工具、获取反馈、动态调整计划最终真正完成一个目标。1.2 Agent的核心理念从“生成文本”到“完成任务”Agent这个词在AI圈有好几个含义但在大模型语境下它基本上指代一套“以大模型为决策大脑通过规划、调用工具、记忆和反思来完成复杂任务”的系统。你可以把它想象成聘请了一个实习生它能听懂你的指令但如果只让它“看着办”它就会抓瞎。你要给它工具电话、电脑、报销系统它才能去执行任务执行完还要汇报结果你反馈问题它再修正。Agent就是把这一套过程程序化。一个完整的Agent工作循环通常包含这么几个环节任务拆解把大目标拆成步骤、工具选择判断当前步骤该调用什么接口、动作执行真正发起API请求或运行代码、结果观察把返回结果喂回给模型、下一步决策继续执行还是结束。这个循环有个常见叫法是ReActReason Act核心思想就是让模型一边思考一边行动而不是一口气编完所有内容。1.3 Agent的典型应用场景有哪些从我接触到的项目和社区讨论来看Agent最常用的场景有这几种信息检索与整合比如让Agent先搜索资料、再读取网页、最终整理成报告。代码辅助开发根据需求自动写代码、执行测试、查看报错、修复后再运行。自动化办公读取邮件或文档按照规则填写表单、生成周报、发送通知。业务系统助手接入企业内部的订单、库存、CRM接口用户用自然语言完成查询和操作。数据分析根据问题自动写SQL查询数据库拿到结果再做结论。这些场景的共同点是任务本身有明确目标中间需要多步操作每步需要外部反馈反馈结果又会影响下一步动作。如果只是“一问一答”式对话用普通Prompt就能搞定不需要Agent。一旦你发现需要循环处理多步、动态决定下一步那就该考虑引入Agent架构了。2. Agent的核心架构大模型、记忆与工具三板斧2.1 大模型Agent的决策大脑想开发Agent第一步要有一个可调用的大模型。这个模型可以是GPT系列、Claude、国产的Qwen、DeepSeek也可以是你自己部署的开源模型。选择模型时除了关注对话质量还有几个对Agent特别重要的点第一是上下文长度。Agent运行过程会把历史步骤、工具返回结果、系统提示词都塞进上下文所以模型上下文窗口不能太小否则跑几步就塞满了。第二是函数调用能力。现在主流模型都支持Function Calling也就是说模型能输出一个结构化的调用请求告诉我们“我要调哪个函数、参数填什么”这是Agent能正确调用工具的关键能力。第三是推理能力复杂任务拆解和纠错非常依赖模型的基础智能模型本身太弱Agent再搭也撑不起来。以我常用的大模型为例像GLM-4系列、Qwen系列在Function Calling上已经比较成熟DeepSeek的推理能力也不错。选型没有绝对标准我的经验是优先选上下文窗口大至少16K以上、且确认自带Tool Call支持的开源或商用模型能省掉不少麻烦。2.2 记忆模块短期上下文与长期知识Agent的记忆分为两层。短期记忆就是当前对话上下文存了最近几轮的用户指令、Agent的动作、工具返回结果。这层记忆的实现很简单本质上就是维护一个消息列表每轮往里面追加内容然后整体发给大模型。长期记忆则面向跨会话的场景。比如今天用户告诉Agent“我负责华东区的销售”明天它再见到用户应该还记得这个信息。常见做法是把重要信息抽取出来存入向量数据库比如Chroma、Milvus、FAISS等等需要时做相似度检索把相关记忆片段塞回上下文里。很多入门朋友会忽略记忆模块其实它决定了Agent是“有连续的助手”还是“永远失忆的工具人”。我的建议是第一版先做好短期记忆保证单次任务能流畅跑通有余力再上VectorStore做长期记忆不要一开始就铺太大。2.3 工具调用Agent的“手”与“眼”工具是Agent体现价值的核心载体。一个Agent如果只会“想”不会“做”那就还是一个高级聊天机器人。工具的本质是函数Agent通过大模型的Function Calling机制生成调用参数然后由程序真正执行这个函数再把结果返回给模型。常见的工具包括搜索API比如Tavily、Bing搜索或者自己爬搜索引擎、计算器或代码执行器、数据库查询接口、内部业务API、文件读写模块等。工具的设计原则只有一条边界清晰、参数明确、错误信息友好。一个好的工具函数入参要尽量结构化返回结果要简洁且包含关键信息出错时要返回可读的错误描述这样模型才能真正“用得好”。这里必须说一个我在实操中的体会很多人以为Agent复杂在于框架代码其实复杂在于工具本身。如果工具的质量参差不齐Agent会反复调错、理解偏差最后看起来像个“人工智障”。先把工具设计好Agent的智能程度能直接上一个台阶。3. Agent开发框架选型与对比3.1 主流框架盘点LangChain、AutoGen、Dify与自研现在说起AI Agent开发绕不开几个框架。第一个是LangChain它的生态最丰富提供了Chain、Agent、Tool、Memory等完整组件社区案例多、教程多但灵活性相对较差抽象层次比较多有时候出了问题反而难排查。同团队出品的LangGraph则更像一个底层编排工具用图结构定义Agent的状态流转控制力更强。微软开源的AutoGen则选择了另一个思路它把Agent定义成可以交流的多个角色比如“用户代理”“助理代理”“代码执行代理”通过多Agent对话协同完成任务。在复杂编程任务和多人协作模拟方面AutoGen表现不错但学习曲线略陡。Dify这类产品则属于“低代码平台化”方向它把Agent搭建做成了可视化流程编排支持接入各类模型和工具非常适合快速验证业务场景或交付给非技术团队使用。如果只是企业内部想做POC概念验证Dify的性价比很高基本不需要写太多代码。还有一批朋友会选择“裸写”自研Agent也就是不用LangChain等框架直接调用大模型API Function Calling 手写循环逻辑。这种方式代码量不大但对核心逻辑理解最清楚也最容易排查问题。我个人建议如果你追求稳定落地且想深入掌握原理自研小框架或者基于LangGraph做底层编排都是不错的选择。3.2 框架选型的决策思路到底选哪个框架我见过很多团队在这个问题上反复横跳。我的建议是先问自己三个问题第一你的团队是偏研发还是偏业务如果偏业务、要快速出Demo选Dify这类平台化工具最稳妥如果偏技术沉淀想深度控制流程自己写或基于LangGraph。第二你的任务复杂度有多高简单单工具调用比如只查个天气、查个资料根本不需要框架裸写不到100行代码复杂多步任务、需要人工介入、需要条件分支这时候上LangGraph或者自研状态机更有优势。第三你是否需要深度调试和多Agent协作如果需要多个角色相互配合AutoGen值得尝试如果只是单Agent单流程LangChain就够用。坦白讲框架本身不是核心竞争力理解Agent的运行机制才是。你就算用LangChain封装的AgentExecutor如果不知道它内部每一步做了什么出了问题还是两眼一抹黑。所以我更倾向于带着框架跑几个调试样例把整个数据流摸清楚再决定是在框架上做定制还是完全自研。4. 从零搭建一个可运行的Agent实操记录4.1 环境准备与模型接入为了不依赖某个具体云厂商我用OpenAI兼容接口的方式接入大模型。目前国内的智谱、阿里云百炼、DeepSeek等都提供了OpenAI兼容的API格式换一个BaseURL和API Key就能切换模型非常方便。你只需要准备一个可用的API Key和对应的BaseURL即可。Python环境建议3.10及以上核心依赖只需要openai库和dotenv。先把环境装好pip install openai python-dotenv然后在项目根目录建一个.env文件把API信息放进去OPENAI_API_KEY你的_API_KEY OPENAI_BASE_URL你的_BaseURL MODEL_NAME你的_模型名这里有个非常基础但容易踩坑的点许多人会把BaseURL漏填导致请求一直打到OpenAI官方地址然后超时或报错。只要使用国内兼容接口务必检查环境变量里的BaseURL和模型名是否与实际服务商一致。4.2 最小Agent核心代码实现工具调用循环下面这一段是我认为“最少必要代码”的Agent骨架。它做的事情是定义两个工具函数一个是假想的查询订单接口一个是计算器让模型根据用户问题决定调用哪个工具然后把工具结果拿回来再让模型生成最终回答。import json import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL) ) MODEL os.getenv(MODEL_NAME) # 定义两个工具函数 def get_order_status(order_id: str) - str: 模拟查询订单状态 data { A001: 已发货预计3天内送达, A002: 正在出库, A003: 已签收 } return data.get(order_id, 订单号不存在请核对后重试) def calculate(expression: str) - str: 模拟计算器只支持四则运算 try: result eval(expression, {__builtins__: {}}, {}) return f计算结果: {result} except Exception as e: return f计算错误: {str(e)} # 工具描述列表这部分会被发给模型 tools [ { type: function, function: { name: get_order_status, description: 查询订单的物流状态, parameters: { type: object, properties: { order_id: {type: string, description: 订单号} }, required: [order_id] } } }, { type: function, function: { name: calculate, description: 执行四则运算表达式, parameters: { type: object, properties: { expression: {type: string, description: 数学表达式} }, required: [expression] } } } ] def run_agent(user_input: str, max_steps: int 5): messages [{role: user, content: user_input}] for step in range(max_steps): response client.chat.completions.create( modelMODEL, messagesmessages, toolstools, tool_choiceauto ) message response.choices[0].message messages.append(message) # 判断是否需要调用工具 if message.tool_calls: for tool_call in message.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) print(fStep {step1}: 调用工具 {fn_name}参数 {fn_args}) if fn_name get_order_status: result get_order_status(fn_args[order_id]) elif fn_name calculate: result calculate(fn_args[expression]) else: result 未知工具 # 将工具结果作为一条消息追加到对话上下文 messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse) }) else: # 没有工具调用说明模型已经给出最终回答 return message.content return 达到最大步骤数任务可能未完成。 if __name__ __main__: print(run_agent(帮我查一下订单A001的状态然后再算一下 (2345)*2 的结果))这段代码跑起来的流程是这样的用户提问后模型会解析意图发现需要调用两个工具于是输出两个tool_call。主程序逐个执行工具把结果以tool消息回填给模型模型结合结果生成最终自然语言回复。整个过程完全模拟了“规划-执行-观察-再回答”的Agent循环。4.3 关键参数与实际运行效果运行上面代码控制台会输出类似这样的工具调用记录Step 1: 调用工具 get_order_status参数 {order_id: A001} Step 2: 调用工具 calculate参数 {expression: (2345)*2}最终模型返回的文本大致是“订单A001已发货预计3天内送达计算(2345)*2的结果为136。”这就是一个最简单但完整的Agent工作流。实际开发中有几点值得特别注意第一max_steps需要根据任务复杂度设置。简单任务设置3步就够了复杂任务或需要多轮纠错的任务建议设置到8到10步。但步数越多消耗的Token也越多运行时间越长需要做个平衡。第二工具描述写得好不好直接影响模型能不能正确调用。描述要写清楚这个工具是干什么的、参数含义是什么最好附带业务约束比如“如果订单号不存在请返回错误提示”。模型是靠描述来“理解”工具的描述写得敷衍调用正确率就会明显下降。第三函数内部一定要有异常处理。工具抛异常会破坏整个Agent的对话流模型拿不到结果就会瞎猜最后给出错误回答。所以工具函数应做到“无论如何都返回一个可读字符串”。4.4 把最小实现扩展到多轮任务和状态管理上面的写法应付单轮简单任务没问题但真实的Agent还要处理多轮对话和动态分支。比如用户中途改需求“等一下我不查A001了改成查A003。”这时候如果还是每次把全部历史消息发给模型模型会同时看到旧订单和新订单容易混淆。我的做法是引入一个“任务状态层”用一个字典保存当前活跃的子任务、已完成的步骤、待执行的计划。每一轮先让模型基于当前状态做决策再决定是否调用工具或回复用户。这个状态层可以自己写也可以用LangGraph的StateGraph来管理。LangGraph的好处是它把每个节点Node和边Edge定义得很清晰适合复杂流程的显式控制但代价是需要理解它的图执行机制。如果你希望少写代码、快速验证推荐在Dify里搭一个类似的Agent流程添加模型、添加工具节点、连接开始和结束节点即可。平台会自动帮你处理消息历史和工具回调适合业务同学先跑通流程、再交给开发做深度定制。5. 常见问题与调试避坑实录5.1 并发与性能压力如何让Agent扛得住线上请求很多朋友入门时在本地写个循环调用模型感觉一切正常但一上线就发现各种超时。原因是Agent不是一次请求就结束一个复杂任务可能包含多次模型调用和工具调用单次任务耗时就可能达到十几秒甚至几分钟。如果业务方要求接口500毫秒返回那原生Agent根本扛不住。我常用的缓解策略是异步化和任务化。对于面向C端的Agent可以把耗时任务丢到消息队列里用户先收到“正在处理中”的响应结果好了再通过WebSocket或轮询推给前端。如果必须同步返回那就只能降低任务复杂度、限制工具调用次数、选用响应更快的模型并且考虑用流式输出来提升用户体验。另一个常见性能瓶颈是工具本身。比如Agent调用的查询接口很慢Agent就会卡在那里等结果整体链路被拖慢。优化工具响应时间比优化模型参数更简单、有效建议优先排查工具接口是否符合性能要求。5.2 上下文塞满怎么办记忆管理与窗口截断上下文窗口是Agent开发中最容易碰到的硬约束。即使模型支持128K上下文Agent跑几轮工具调用之后消息列表也会快速增长。尤其是工具返回的JSON如果又长又乱几轮下来窗口就满了后面的关键信息反而没地方放。我的处理方式有三招一是精简工具返回。让工具只返回必要字段比如查询订单只返回状态和预计时间不要返回整个数据库行的所有字段。二是做历史摘要。当消息列表超过一定长度时启动一个“摘要Agent”把前面的对话历史压缩成几句话再作为历史记录继续后续对话。三是滑动窗口。只保留最近N轮重要的交互更早的内容直接丢弃适用于对历史不敏感的任务。这里有个取舍摘要会丢失细节滑动窗口会丢失早期信息。实际项目里我通常是先用滑动窗口保底再加上面向关键信息的持久化存储比如把订单号、用户偏好存进Long-term Memory需要时检索回来。5.3 工具调用失败与模型“胡说八道”的排查思路工具调用不是你定义好了就一定能正确执行。常见的失败模式有几种模型生成了不存在的函数名。多半是工具描述与函数定义不一致或模型版本不支持复杂的Function Calling。参数格式错误。比如要求integer类型模型传了字符串。建议在工具层做防御性校验统一用JSON字符串接收参数再解析。模型循环调用同一个工具反复出错不退出。这是典型的“死循环”解决方法是设置max_steps上限并观察循环中的报错信息通常是工具返回的错误信息不够清晰模型不知道如何修正。遇到这些问题我的排查顺序是先看原始请求报文确认模型输出的tool_call长什么样再看工具返回值确认是否可读、是否有误导信息最后再看上下文确认历史消息是否干净比如错误结果重复堆积。大多数问题出在工具返回内容太混乱、模型“看不出错在哪”。5.4 安全边界与权限控制别让Agent乱调接口Agent引入工具以后安全问题的面会急剧扩大。核心风险是Prompt注入如果用户输入或者工具返回内容里藏了恶意指令模型可能被诱导去调用不该调用的接口或者泄露敏感信息。我给Agent接入业务工具时强制做几件事工具函数内部做参数白名单校验不做危险操作比如删除、批量导出API Key和内部系统地址不出现在系统提示词里对Agent可以调用的工具名单做严格管理不用“万能工具”所有关键操作都加审计日志记录谁在什么时候让Agent做了什么。另外别让Agent拥有“完全自主”的权限。涉及资金操作、数据删除、外部发送消息这类高影响动作应该设计人工确认环节也就是“Human-in-the-loop”。Agent先给出操作内容等用户确认后再真正执行能在很大程度上避免模型误操作引起的线上事故。5.5 低代码平台与自研代码如何结合最后聊聊Dify这类低代码平台。很多团队会觉得“用了Dify就不用写代码了”实际上Dify擅长的场景是POC验证、流程可视化、非技术人员快速搭建。一旦涉及复杂的业务逻辑、私有化部署、性能调优和对底层模型的深度定制Dify反而会变成约束——因为你在平台里能做的操作是有边界的。我实际项目里的思路是“两条腿走路”业务探索阶段用Dify快速搭建Agent原型验证产品逻辑确认方向后再用代码把核心流程复刻一遍接入公司内部系统和性能优化方案。这样既保证了迭代速度也保住了最终的技术掌控力。写在最后的经验之谈个人感觉Agent开发入门最大的障碍不是框架不是API而是思维的转变。以前写程序流程是确定的现在写Agent流程是模型根据输入动态生成的变成了“设计一套让模型自己决策的规则”。你设计的不是代码路径而是决策边界、工具质量和异常兜底。多跑几个失败的案例想想模型为什么选了这个工具、为什么参数填错了你对Agent的理解会快速超过只刷教程的人。再分享一个小技巧无论用什么框架先把你自己的Agent画成一张图——用户进来后模型需要几步、每步可能调哪些工具、失败之后怎么回转。这张图不用画得漂亮哪怕写在草稿纸上都行。等你把这张图跑通了再往里面加记忆、加权限、加并发Agent就会越来越像一个真正能交付业务价值的系统而不是一个Demo。
这些年聊大模型大家从最早的“能聊天”逐渐过渡到了“能不能帮我干点正事”。而“让大模型自己干活”这件事最直接的落地形态就是Agent。这个标题“大模型Agent开发入门”看起来很直白但真正接触过的朋友都知道从概念到能跑通一个像样的Agent中间隔着不少弯弯绕绕。我就结合自己折腾过的项目把大模型Agent开发这条路上的核心思路、框架选型、实操代码和踩坑经验一次说清楚希望能帮正准备入门的朋友少走几步弯路。这篇内容适合谁刚接触大模型开发、想做一个真正能执行任务的AI流程或者已经用过Prompt但总觉得“不太智能”的开发者。AI Agent能解决的问题是让大模型从“回答问题”变成“拆解任务、调用工具、执行动作、观察结果、修正路径”的完整闭环。如果你也想搭一个能查资料、能算数据、能调用业务系统接口的助手可以直接参考这里的思路。1. 为什么Agent成了大模型落地的主流形态1.1 大模型本身的局限会说话不等于会办事先聊一个基础问题大模型到底解决了什么简而言之它把“自然语言理解和生成”这件事的门槛拉到了极低。你扔给它一段话它能续写、总结、翻译、抽取信息甚至根据指令写代码。但这个能力本质上仍然是“概率化文本生成”它不负责执行动作也不感知外部世界的变化。举个例子你让大模型帮你查一下今天某地的天气。模型就算把“今天北京天气晴朗气温25度”这句回答写得天花乱坠它也不知道北京今天到底下没下雨。它只是根据训练数据里的统计规律生成了一段看起来合理的文本。如果你问它“帮我订一张明天去上海的机票”它最多给你写一个订票攻略但它没法真的打开航司系统完成下单。这就是大模型的边界知识有截止日期、无法感知实时状态、无法主动调用外部API、也不能自主完成多步操作。Agent的定位恰恰就是在大模型外面包一层“手”和“眼”让它能调用工具、获取反馈、动态调整计划最终真正完成一个目标。1.2 Agent的核心理念从“生成文本”到“完成任务”Agent这个词在AI圈有好几个含义但在大模型语境下它基本上指代一套“以大模型为决策大脑通过规划、调用工具、记忆和反思来完成复杂任务”的系统。你可以把它想象成聘请了一个实习生它能听懂你的指令但如果只让它“看着办”它就会抓瞎。你要给它工具电话、电脑、报销系统它才能去执行任务执行完还要汇报结果你反馈问题它再修正。Agent就是把这一套过程程序化。一个完整的Agent工作循环通常包含这么几个环节任务拆解把大目标拆成步骤、工具选择判断当前步骤该调用什么接口、动作执行真正发起API请求或运行代码、结果观察把返回结果喂回给模型、下一步决策继续执行还是结束。这个循环有个常见叫法是ReActReason Act核心思想就是让模型一边思考一边行动而不是一口气编完所有内容。1.3 Agent的典型应用场景有哪些从我接触到的项目和社区讨论来看Agent最常用的场景有这几种信息检索与整合比如让Agent先搜索资料、再读取网页、最终整理成报告。代码辅助开发根据需求自动写代码、执行测试、查看报错、修复后再运行。自动化办公读取邮件或文档按照规则填写表单、生成周报、发送通知。业务系统助手接入企业内部的订单、库存、CRM接口用户用自然语言完成查询和操作。数据分析根据问题自动写SQL查询数据库拿到结果再做结论。这些场景的共同点是任务本身有明确目标中间需要多步操作每步需要外部反馈反馈结果又会影响下一步动作。如果只是“一问一答”式对话用普通Prompt就能搞定不需要Agent。一旦你发现需要循环处理多步、动态决定下一步那就该考虑引入Agent架构了。2. Agent的核心架构大模型、记忆与工具三板斧2.1 大模型Agent的决策大脑想开发Agent第一步要有一个可调用的大模型。这个模型可以是GPT系列、Claude、国产的Qwen、DeepSeek也可以是你自己部署的开源模型。选择模型时除了关注对话质量还有几个对Agent特别重要的点第一是上下文长度。Agent运行过程会把历史步骤、工具返回结果、系统提示词都塞进上下文所以模型上下文窗口不能太小否则跑几步就塞满了。第二是函数调用能力。现在主流模型都支持Function Calling也就是说模型能输出一个结构化的调用请求告诉我们“我要调哪个函数、参数填什么”这是Agent能正确调用工具的关键能力。第三是推理能力复杂任务拆解和纠错非常依赖模型的基础智能模型本身太弱Agent再搭也撑不起来。以我常用的大模型为例像GLM-4系列、Qwen系列在Function Calling上已经比较成熟DeepSeek的推理能力也不错。选型没有绝对标准我的经验是优先选上下文窗口大至少16K以上、且确认自带Tool Call支持的开源或商用模型能省掉不少麻烦。2.2 记忆模块短期上下文与长期知识Agent的记忆分为两层。短期记忆就是当前对话上下文存了最近几轮的用户指令、Agent的动作、工具返回结果。这层记忆的实现很简单本质上就是维护一个消息列表每轮往里面追加内容然后整体发给大模型。长期记忆则面向跨会话的场景。比如今天用户告诉Agent“我负责华东区的销售”明天它再见到用户应该还记得这个信息。常见做法是把重要信息抽取出来存入向量数据库比如Chroma、Milvus、FAISS等等需要时做相似度检索把相关记忆片段塞回上下文里。很多入门朋友会忽略记忆模块其实它决定了Agent是“有连续的助手”还是“永远失忆的工具人”。我的建议是第一版先做好短期记忆保证单次任务能流畅跑通有余力再上VectorStore做长期记忆不要一开始就铺太大。2.3 工具调用Agent的“手”与“眼”工具是Agent体现价值的核心载体。一个Agent如果只会“想”不会“做”那就还是一个高级聊天机器人。工具的本质是函数Agent通过大模型的Function Calling机制生成调用参数然后由程序真正执行这个函数再把结果返回给模型。常见的工具包括搜索API比如Tavily、Bing搜索或者自己爬搜索引擎、计算器或代码执行器、数据库查询接口、内部业务API、文件读写模块等。工具的设计原则只有一条边界清晰、参数明确、错误信息友好。一个好的工具函数入参要尽量结构化返回结果要简洁且包含关键信息出错时要返回可读的错误描述这样模型才能真正“用得好”。这里必须说一个我在实操中的体会很多人以为Agent复杂在于框架代码其实复杂在于工具本身。如果工具的质量参差不齐Agent会反复调错、理解偏差最后看起来像个“人工智障”。先把工具设计好Agent的智能程度能直接上一个台阶。3. Agent开发框架选型与对比3.1 主流框架盘点LangChain、AutoGen、Dify与自研现在说起AI Agent开发绕不开几个框架。第一个是LangChain它的生态最丰富提供了Chain、Agent、Tool、Memory等完整组件社区案例多、教程多但灵活性相对较差抽象层次比较多有时候出了问题反而难排查。同团队出品的LangGraph则更像一个底层编排工具用图结构定义Agent的状态流转控制力更强。微软开源的AutoGen则选择了另一个思路它把Agent定义成可以交流的多个角色比如“用户代理”“助理代理”“代码执行代理”通过多Agent对话协同完成任务。在复杂编程任务和多人协作模拟方面AutoGen表现不错但学习曲线略陡。Dify这类产品则属于“低代码平台化”方向它把Agent搭建做成了可视化流程编排支持接入各类模型和工具非常适合快速验证业务场景或交付给非技术团队使用。如果只是企业内部想做POC概念验证Dify的性价比很高基本不需要写太多代码。还有一批朋友会选择“裸写”自研Agent也就是不用LangChain等框架直接调用大模型API Function Calling 手写循环逻辑。这种方式代码量不大但对核心逻辑理解最清楚也最容易排查问题。我个人建议如果你追求稳定落地且想深入掌握原理自研小框架或者基于LangGraph做底层编排都是不错的选择。3.2 框架选型的决策思路到底选哪个框架我见过很多团队在这个问题上反复横跳。我的建议是先问自己三个问题第一你的团队是偏研发还是偏业务如果偏业务、要快速出Demo选Dify这类平台化工具最稳妥如果偏技术沉淀想深度控制流程自己写或基于LangGraph。第二你的任务复杂度有多高简单单工具调用比如只查个天气、查个资料根本不需要框架裸写不到100行代码复杂多步任务、需要人工介入、需要条件分支这时候上LangGraph或者自研状态机更有优势。第三你是否需要深度调试和多Agent协作如果需要多个角色相互配合AutoGen值得尝试如果只是单Agent单流程LangChain就够用。坦白讲框架本身不是核心竞争力理解Agent的运行机制才是。你就算用LangChain封装的AgentExecutor如果不知道它内部每一步做了什么出了问题还是两眼一抹黑。所以我更倾向于带着框架跑几个调试样例把整个数据流摸清楚再决定是在框架上做定制还是完全自研。4. 从零搭建一个可运行的Agent实操记录4.1 环境准备与模型接入为了不依赖某个具体云厂商我用OpenAI兼容接口的方式接入大模型。目前国内的智谱、阿里云百炼、DeepSeek等都提供了OpenAI兼容的API格式换一个BaseURL和API Key就能切换模型非常方便。你只需要准备一个可用的API Key和对应的BaseURL即可。Python环境建议3.10及以上核心依赖只需要openai库和dotenv。先把环境装好pip install openai python-dotenv然后在项目根目录建一个.env文件把API信息放进去OPENAI_API_KEY你的_API_KEY OPENAI_BASE_URL你的_BaseURL MODEL_NAME你的_模型名这里有个非常基础但容易踩坑的点许多人会把BaseURL漏填导致请求一直打到OpenAI官方地址然后超时或报错。只要使用国内兼容接口务必检查环境变量里的BaseURL和模型名是否与实际服务商一致。4.2 最小Agent核心代码实现工具调用循环下面这一段是我认为“最少必要代码”的Agent骨架。它做的事情是定义两个工具函数一个是假想的查询订单接口一个是计算器让模型根据用户问题决定调用哪个工具然后把工具结果拿回来再让模型生成最终回答。import json import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL) ) MODEL os.getenv(MODEL_NAME) # 定义两个工具函数 def get_order_status(order_id: str) - str: 模拟查询订单状态 data { A001: 已发货预计3天内送达, A002: 正在出库, A003: 已签收 } return data.get(order_id, 订单号不存在请核对后重试) def calculate(expression: str) - str: 模拟计算器只支持四则运算 try: result eval(expression, {__builtins__: {}}, {}) return f计算结果: {result} except Exception as e: return f计算错误: {str(e)} # 工具描述列表这部分会被发给模型 tools [ { type: function, function: { name: get_order_status, description: 查询订单的物流状态, parameters: { type: object, properties: { order_id: {type: string, description: 订单号} }, required: [order_id] } } }, { type: function, function: { name: calculate, description: 执行四则运算表达式, parameters: { type: object, properties: { expression: {type: string, description: 数学表达式} }, required: [expression] } } } ] def run_agent(user_input: str, max_steps: int 5): messages [{role: user, content: user_input}] for step in range(max_steps): response client.chat.completions.create( modelMODEL, messagesmessages, toolstools, tool_choiceauto ) message response.choices[0].message messages.append(message) # 判断是否需要调用工具 if message.tool_calls: for tool_call in message.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) print(fStep {step1}: 调用工具 {fn_name}参数 {fn_args}) if fn_name get_order_status: result get_order_status(fn_args[order_id]) elif fn_name calculate: result calculate(fn_args[expression]) else: result 未知工具 # 将工具结果作为一条消息追加到对话上下文 messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse) }) else: # 没有工具调用说明模型已经给出最终回答 return message.content return 达到最大步骤数任务可能未完成。 if __name__ __main__: print(run_agent(帮我查一下订单A001的状态然后再算一下 (2345)*2 的结果))这段代码跑起来的流程是这样的用户提问后模型会解析意图发现需要调用两个工具于是输出两个tool_call。主程序逐个执行工具把结果以tool消息回填给模型模型结合结果生成最终自然语言回复。整个过程完全模拟了“规划-执行-观察-再回答”的Agent循环。4.3 关键参数与实际运行效果运行上面代码控制台会输出类似这样的工具调用记录Step 1: 调用工具 get_order_status参数 {order_id: A001} Step 2: 调用工具 calculate参数 {expression: (2345)*2}最终模型返回的文本大致是“订单A001已发货预计3天内送达计算(2345)*2的结果为136。”这就是一个最简单但完整的Agent工作流。实际开发中有几点值得特别注意第一max_steps需要根据任务复杂度设置。简单任务设置3步就够了复杂任务或需要多轮纠错的任务建议设置到8到10步。但步数越多消耗的Token也越多运行时间越长需要做个平衡。第二工具描述写得好不好直接影响模型能不能正确调用。描述要写清楚这个工具是干什么的、参数含义是什么最好附带业务约束比如“如果订单号不存在请返回错误提示”。模型是靠描述来“理解”工具的描述写得敷衍调用正确率就会明显下降。第三函数内部一定要有异常处理。工具抛异常会破坏整个Agent的对话流模型拿不到结果就会瞎猜最后给出错误回答。所以工具函数应做到“无论如何都返回一个可读字符串”。4.4 把最小实现扩展到多轮任务和状态管理上面的写法应付单轮简单任务没问题但真实的Agent还要处理多轮对话和动态分支。比如用户中途改需求“等一下我不查A001了改成查A003。”这时候如果还是每次把全部历史消息发给模型模型会同时看到旧订单和新订单容易混淆。我的做法是引入一个“任务状态层”用一个字典保存当前活跃的子任务、已完成的步骤、待执行的计划。每一轮先让模型基于当前状态做决策再决定是否调用工具或回复用户。这个状态层可以自己写也可以用LangGraph的StateGraph来管理。LangGraph的好处是它把每个节点Node和边Edge定义得很清晰适合复杂流程的显式控制但代价是需要理解它的图执行机制。如果你希望少写代码、快速验证推荐在Dify里搭一个类似的Agent流程添加模型、添加工具节点、连接开始和结束节点即可。平台会自动帮你处理消息历史和工具回调适合业务同学先跑通流程、再交给开发做深度定制。5. 常见问题与调试避坑实录5.1 并发与性能压力如何让Agent扛得住线上请求很多朋友入门时在本地写个循环调用模型感觉一切正常但一上线就发现各种超时。原因是Agent不是一次请求就结束一个复杂任务可能包含多次模型调用和工具调用单次任务耗时就可能达到十几秒甚至几分钟。如果业务方要求接口500毫秒返回那原生Agent根本扛不住。我常用的缓解策略是异步化和任务化。对于面向C端的Agent可以把耗时任务丢到消息队列里用户先收到“正在处理中”的响应结果好了再通过WebSocket或轮询推给前端。如果必须同步返回那就只能降低任务复杂度、限制工具调用次数、选用响应更快的模型并且考虑用流式输出来提升用户体验。另一个常见性能瓶颈是工具本身。比如Agent调用的查询接口很慢Agent就会卡在那里等结果整体链路被拖慢。优化工具响应时间比优化模型参数更简单、有效建议优先排查工具接口是否符合性能要求。5.2 上下文塞满怎么办记忆管理与窗口截断上下文窗口是Agent开发中最容易碰到的硬约束。即使模型支持128K上下文Agent跑几轮工具调用之后消息列表也会快速增长。尤其是工具返回的JSON如果又长又乱几轮下来窗口就满了后面的关键信息反而没地方放。我的处理方式有三招一是精简工具返回。让工具只返回必要字段比如查询订单只返回状态和预计时间不要返回整个数据库行的所有字段。二是做历史摘要。当消息列表超过一定长度时启动一个“摘要Agent”把前面的对话历史压缩成几句话再作为历史记录继续后续对话。三是滑动窗口。只保留最近N轮重要的交互更早的内容直接丢弃适用于对历史不敏感的任务。这里有个取舍摘要会丢失细节滑动窗口会丢失早期信息。实际项目里我通常是先用滑动窗口保底再加上面向关键信息的持久化存储比如把订单号、用户偏好存进Long-term Memory需要时检索回来。5.3 工具调用失败与模型“胡说八道”的排查思路工具调用不是你定义好了就一定能正确执行。常见的失败模式有几种模型生成了不存在的函数名。多半是工具描述与函数定义不一致或模型版本不支持复杂的Function Calling。参数格式错误。比如要求integer类型模型传了字符串。建议在工具层做防御性校验统一用JSON字符串接收参数再解析。模型循环调用同一个工具反复出错不退出。这是典型的“死循环”解决方法是设置max_steps上限并观察循环中的报错信息通常是工具返回的错误信息不够清晰模型不知道如何修正。遇到这些问题我的排查顺序是先看原始请求报文确认模型输出的tool_call长什么样再看工具返回值确认是否可读、是否有误导信息最后再看上下文确认历史消息是否干净比如错误结果重复堆积。大多数问题出在工具返回内容太混乱、模型“看不出错在哪”。5.4 安全边界与权限控制别让Agent乱调接口Agent引入工具以后安全问题的面会急剧扩大。核心风险是Prompt注入如果用户输入或者工具返回内容里藏了恶意指令模型可能被诱导去调用不该调用的接口或者泄露敏感信息。我给Agent接入业务工具时强制做几件事工具函数内部做参数白名单校验不做危险操作比如删除、批量导出API Key和内部系统地址不出现在系统提示词里对Agent可以调用的工具名单做严格管理不用“万能工具”所有关键操作都加审计日志记录谁在什么时候让Agent做了什么。另外别让Agent拥有“完全自主”的权限。涉及资金操作、数据删除、外部发送消息这类高影响动作应该设计人工确认环节也就是“Human-in-the-loop”。Agent先给出操作内容等用户确认后再真正执行能在很大程度上避免模型误操作引起的线上事故。5.5 低代码平台与自研代码如何结合最后聊聊Dify这类低代码平台。很多团队会觉得“用了Dify就不用写代码了”实际上Dify擅长的场景是POC验证、流程可视化、非技术人员快速搭建。一旦涉及复杂的业务逻辑、私有化部署、性能调优和对底层模型的深度定制Dify反而会变成约束——因为你在平台里能做的操作是有边界的。我实际项目里的思路是“两条腿走路”业务探索阶段用Dify快速搭建Agent原型验证产品逻辑确认方向后再用代码把核心流程复刻一遍接入公司内部系统和性能优化方案。这样既保证了迭代速度也保住了最终的技术掌控力。写在最后的经验之谈个人感觉Agent开发入门最大的障碍不是框架不是API而是思维的转变。以前写程序流程是确定的现在写Agent流程是模型根据输入动态生成的变成了“设计一套让模型自己决策的规则”。你设计的不是代码路径而是决策边界、工具质量和异常兜底。多跑几个失败的案例想想模型为什么选了这个工具、为什么参数填错了你对Agent的理解会快速超过只刷教程的人。再分享一个小技巧无论用什么框架先把你自己的Agent画成一张图——用户进来后模型需要几步、每步可能调哪些工具、失败之后怎么回转。这张图不用画得漂亮哪怕写在草稿纸上都行。等你把这张图跑通了再往里面加记忆、加权限、加并发Agent就会越来越像一个真正能交付业务价值的系统而不是一个Demo。
