这两年做AI应用开发最常被朋友问的一句话是“我把GPT接到业务里做了个Agent你帮我看看效果怎么样”点开一看绝大多数其实是套了一层提示词的聊天机器人。这不是咬文嚼字聊天机器人和智能体Agent的架构、故障模式、迭代方式完全不同搞混了后面会吃大亏。这篇文章就用最直白的方式把一个大模型智能体的简易流程讲清楚一个任务进来之后Agent内部到底经历了什么你应该怎么设计工具、怎么选框架、怎么避开最常见的坑。目标是让有基础编程能力或者天天泡在AI工具里的人看完能搭出第一个真正干活的Agent。1. 先泼一盆冷水聊天机器人不等于智能体1.1 用“会不会主动做事”来判断很多人把Agent当作“升级版聊天机器人”接上大模型API写一段系统提示词再套一个好看的网页就对外叫Agent。这种理解最大的问题是把“响应”当成了“行动”。聊天机器人的工作模式是用户输入 → 大模型生成文本 → 展示。整个过程只有一次模型调用模型没有渠道去获取任何外部信息只能依赖自己的内置知识。而Agent的工作模式是循环式的用户给一个目标 → 模型判断需要什么信息 → 调用工具获取信息 → 基于反馈继续推理 → 直到目标达成。所以“会不会根据用户的目标主动调用外部工具”是我判断一个系统到底是不是Agent最直接的试金石。这不是说聊天机器人不好很多客服场景它反而是最合适的选择而是说如果你想解决的是“需要实时数据、需要操作外部系统”的问题那就必须用Agent架构。为了更直观我列个对比对比项聊天机器人智能体Agent核心模式一问一答任务循环模型调用次数通常一次多次直到任务完成外部工具不调用主动调用典型问题知识截止、编造数据循环失控、工具出错1.2 大模型的能力边界决定了Agent的必然性大模型隐含的假设是“知识都在参数里”但这一点在实际业务中会带来三个硬伤。第一知识有截止日期。训练完毕的那一刻它对世界的认知就冻结了最新的事件、行情、政策它都不知道。第二它没有实时交互能力。问“现在几点”“今天上海天气如何”“这个订单发货没”它回答不了因为参数里没有这些状态。第三它会一本正经地编造数据。让它猜一个具体数字它宁可编一个看起来合理的数字也不愿意承认自己不知道。也就是说大模型真正擅长的是“理解意图、拆解步骤、组织表达”不擅长的是“精确地读取和修改现实世界状态”。Agent恰好补上了这块短板把模型当作大脑把工具当作手脚让大脑指挥手脚去获取事实、完成任务。看懂了这个前提你就能明白为什么现在所有主流Agent方案都在围绕“工具调用”做文章——工具是模型和现实世界之间唯一的通道。1.3 一个Agent应该具备的四个特征如果让我给Agent下个定义至少要包含这四件事缺一个都不完整目标驱动。输入是一个“任务”比如“把这份Excel里的低库存商品整理成预警清单并发给我”而不是一句简单的问候。自主规划。由模型决定先做什么、再做什么步骤不是程序员预先写死的。工具调用。能调用至少一个外部函数、API或服务去获取信息或产生影响。反馈修正。拿到工具结果后发现自己原来的计划有问题能调整计划继续执行。这四条是递进的。如果只做到了“任务输入预设工作流”那算半个Agent如果只有对话没有工具那就还停留在聊天机器人阶段。理解了这些基础下面看看Agent内部到底是怎么跑的。2. 一个Agent跑通任务的完整循环从提问到交付中间发生了什么2.1 用一次“出差安排”看懂循环我在给团队讲Agent原理时最喜欢用一个例子让Agent安排明天去上海的出差行程。这个任务够日常又能把整个循环的复杂度体现出来。如果是聊天机器人它会直接生成一篇“建议你去外滩、陆家嘴……”的小作文而Agent的流程完全不同。模型先解析任务地点上海、时间明天、要求交通便利。接着它意识到自己并不知道明天的天气也不知道各地点间的通行时间于是安排第一步行动——调用天气工具查询上海明天天气。拿到“明天下雨”的结果之后它调整计划把原本排在室外的景点砍掉换成室内场馆。然后第二步调用地图时间估算工具计算两个室内地点之间坐地铁要多久。最后把所有信息组织成一份带时间表的行程。这个过程中模型被调用了很多次每一次调用都基于上一次工具返回的新信息。这就是Agent和普通API调用的本质区别——它在循环里工作而不是一锤子买卖。这也是为什么很多人第一次看Agent日志会觉得“啰嗦”因为系统真的像人一样查一次资料思考一会儿再查一次再思考。2.2 循环里的四个阶段感知、推理、行动、观察一个Agent循环可以拆成四段感知、推理、行动、观察。感知Observation把用户输入、工具返回结果、历史消息这些信息整理成模型当前能读到的上下文。推理Reasoning模型根据当前上下文判断“还缺什么信息”“下一步该干什么”。在ReAct风格的实现里这一步通常表现为模型输出Thought想法和Action动作。行动Action执行一次具体动作比如调用天气API、执行一段Python代码、查询数据库。动作的类型由Agent可用的工具集决定。观察Observation把动作的执行结果比如API返回的JSON再放回上下文里。观察结束后模型开始下一轮推理。如果它觉得还缺信息就继续行动如果它觉得信息够了就输出最终答案。这个“推理—行动—观察”的循环会一直重复直到任务完成或到达终止条件。2.3 没有终止条件的循环就是失控循环Agent循环听起来简单但有一个潜在问题模型是概率性的它有可能永远觉得“还不够”。比如让它收集某一年的行业数据它会一次一次去查查完觉得还可以更全于是再查一次直到token耗尽或者预算打爆。所以一个工程上可用的Agent必须有明确的终止信号完成信号。模型决定不再调用工具输出最终回复这是最理想的终点。最大步数。不管完成没有循环到N轮常见3到10轮就强制结束。超时与预算。整个任务达到一定时长或token数就截断避免失控。这三个条件在实际系统里通常同时存在。后面的最小Demo就实现了“完成信号最大步数”两个先让你直观感受一下。3. 不依赖框架手写一个最小可运行的Agent Demo3.1 环境准备一个兼容接口就够了很多人以为写Agent一定要上LangChain这种重框架其实不然。Agent的核心循环用代码实现起来很短几百行以内就能写完。我建议所有想深入的人先手写一遍最小循环把手感建立起来再谈框架。准备条件很简单Python 3.8以上安装openai库因为大多数大模型服务都提供OpenAI兼容接口无论云端还是本地部署都能用一个可用的API Key和base_url。我之所以用OpenAI兼容方式来写是因为这样你后面换模型时只需要改model和base_url核心逻辑完全不用动。这对“不绑定某个供应商”非常重要。3.2 定义工具天气查询函数与它的Schema先做一个最简单的工具函数查询天气。我用内置字典模拟数据真实项目里替换成HTTP调用即可。def get_weather(city: str) - dict: weather_table { 北京: {temperature: 18, condition: 晴, wind: 3级}, 上海: {temperature: 22, condition: 多云, wind: 2级}, } data weather_table.get(city) if not data: return {error: f暂不支持查询城市 {city}} return {city: city, **data}但光有Python函数不够模型并不知道这个函数的存在必须给它一份JSON Schema。这就是Function Calling的“说明书”tools [ { type: function, function: { name: get_weather, description: 查询指定城市当前天气情况包括温度、天气状况和风力。, parameters: { type: object, properties: { city: { type: string, description: 城市名例如 北京、上海 } }, required: [city] } } } ]这里有个容易被忽略的点description写得越清楚模型选错参数的概率越低。很多人随便写一句“查询天气”模型就经常把“北京明天”整个塞进city字段。把参数含义和示例写清楚是工具设计的第一课。3.3 核心循环用代码实现感知—推理—行动—观察工具定义好了接下来实现Agent主循环。流程是把用户问题放入messages调用模型带上tools参数判断返回结果里有没有tool_calls有就解析函数名和参数执行本地函数把结果以roletool的message放回messages继续循环没有说明模型准备直接输出取出content结束。代码如下import json import openai client openai.OpenAI( api_key你的API_KEY, base_urlhttp://你的服务地址/v1, ) def run_agent(user_input: str, max_steps: int 5) - str: messages [{role: user, content: user_input}] for step in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, # 换成你实际用的模型 messagesmessages, toolstools, ) message resp.choices[0].message messages.append(message) if not message.tool_calls: return message.content for tool_call in message.tool_calls: fn_name tool_call.function.name args json.loads(tool_call.function.arguments) print(f[Step {step1}] 调用工具: {fn_name}({args})) if fn_name get_weather: result get_weather(args[city]) else: result {error: f未知工具 {fn_name}} messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) return 已达最大步数任务未完成请调整提示词或工具。这段代码就是一个完整的Agent骨架。整个过程中messages的维护是核心每一步模型的历史消息必须完整保留尤其不能漏掉tool角色返回的那一条。一旦漏掉模型就不知道刚才调用的工具结果是什么然后开始胡编。3.4 跑一个例子看Agent的中间轨迹用“北京明天适合跑步吗”来跑你会看到一个典型轨迹Step 1模型输出tool_calls调用get_weather({city: 北京})工具返回 {city: 北京, temperature: 18, condition: 晴, wind: 3级}Step 2模型不再调用工具输出最终结论“北京明天是晴天温度18度风力3级适合跑步建议穿一件薄外套。”但注意这个Demo有一个明显缺陷它查的是“当前天气”而不是“明天天气”因为工具本身没做时间区分。这就引出一个重要结论工具能力决定了Agent能力的上限。模型再聪明也只能在工具给的数据范围内做判断。真实系统里你的工具必须覆盖任务所需的真实数据源。4. 用现成平台搭建智能体Dify这类工具到底帮你省了什么4.1 为什么已经有手写Demo还要用框架上面的Demo能跑通但它距离“可生产的Agent”还有很长的路。你会立刻遇到几个问题多个用户并发时上下文状态怎么隔离工具调用日志在哪里看运营同事想调整提示词难道要改代码重新部署吗某个模型服务不稳定想一键切换怎么办。这些就是Agent框架和平台存在的价值。它们把对话状态管理、工具注册、模型供应商适配、日志追踪这些公共能力提前做好了。你要做的只是填写业务相关的提示词和工具。所以我的判断是如果你是产品经理或业务方直接用可视化平台搭如果你是开发也建议先用平台快速验证业务再决定要不要自研。先跑通再优化永远比一上来就写框架稳。4.2 在Dify上搭建一个Agent的完整步骤Dify是现在比较主流的开源智能体平台既支持私有化部署也有官方云端版本。在Dify里搭一个Agent完整流程大概是这样的登录后创建“Agent”类型应用这里注意别选成“Chatbot”或“Workflow”类型选错后面的交互逻辑完全不一样。在“模型”配置里选择模型供应商填写API Key选好具体模型。编写系统提示词。这一步最重要建议显式写明你是谁、你能调用哪些工具、什么情况必须调用工具、输出格式是什么。在“工具”区域添加工具。Dify自带了一批内置工具比如搜索、天气、计算器也支持自己导入OpenAPI Schema把你公司的接口暴露给Agent。打开“模型自行调用工具”的开关。这是Agent类型应用和其他应用最大的区别不开这个开关模型就不会主动用工具。在调试界面输入一个任务点运行看每一步的输入输出特别是工具返回的原始内容和模型基于它生成的推理。满意后发布Dify会生成API接口你可以把它接到自己的前端、公众号、企业微信机器人等地方。很多人卡在第4步。自己写的内部接口要以OpenAPI格式导入建议先用一个简单的GET接口试通再上POST和复杂鉴权一次全上很容易排查不出问题。4.3 主流框架怎么选LangGraph、Dify、Coze、AutoGen对比我按自己的理解做了一张对比方便你对号入座。框架/平台形态适合谁核心优势主要成本LangGraphPython代码库开发者为主对状态的精细控制适合复杂图结构Agent学习曲线陡所有事都要写代码Dify可视化平台可私有化产品/运营为主开发配合搭得快日志清晰能对接多种模型高度自定义场景需要写插件Coze云端平台想快速接内容生态的个人/团队插件市场丰富发布渠道多不用运维平台绑定较深扩展受平台限制AutoGenPython代码库研究多智能体协作支持多Agent对话和任务编排生产稳定性需要自己做更多工作这里不做“谁更好”的结论只看匹配度。先想清楚业务逻辑的复杂度、团队里谁会维护、对数据私有化的要求再选型。4.4 关于选型的个人建议如果让我给一个通用建议大多数业务型项目从Dify这类可视化平台起步是最保险的因为它的可观测性天然比代码好。你的运营同事也能直接看到Agent每一步在干什么这在debug阶段价值巨大。当业务长到平台满足不了比如需要非常精细的状态机、复杂的反思循环再迁移到LangGraph这类代码框架。到了最后你会发现自己写核心循环不难难的是周边生态比如监控、评估、权限控制。这些成熟平台已经替你解决了不少。5. 让Agent在真实场景撑得住工具设计、记忆与防呆5.1 工具调用的两种主流实现Function Calling与ReAct很多人以为工具调用只有一种方式其实区别挺大。我分一下Function Calling模型经过专门训练会直接输出一个结构化的JSON包括函数名和参数。代码拿到后直接执行不需要去解析自然语言。好处是稳定、解析成本低坏处是要求模型本身支持这个能力。ReAct模型不输出结构化JSON而是按提示词要求输出Thought、Action、Action Input这样的固定格式代码用正则或字符串匹配去解析。好处是任何模型都能用坏处是格式不稳定一旦模型哪天不按套路出牌解析就崩了。实际项目里我会优先用Function Calling因为它把“意图到参数”的转换变成了模型的原生能力。但如果用的是本地部署的开源模型且该模型不支持Function CallingReAct是可行的兜底方案。对比项Function CallingReAct依赖模型原生支持需要不需要输出稳定性高一般受提示词影响大解析成本低直接JSON解析高需要解析文本格式工具数量多了之后能处理较多工具容易混乱5.2 工具返回格式决定了Agent的下限Agent在做工具调用时最怕的不是失败而是返回结果“没法看”。想象一个场景工具返回了一大段HTML页面或者一个几千行的查询结果。模型需要从中提取有用信息噪声一大推理质量立刻下降token开销也会指数上涨。所以你设计的每一个工具返回时都应该做“面向模型的摘要”。我的习惯是外部API拿到数据后先过滤掉模型用不到的字段只保留必要的、JSON格式干净的字段再返回给模型。如果数据量实在大就先让一段脚本或一个小模型提炼成要点再塞回上下文。工具返回做得干净Agent的成功率会肉眼可见地提升。5.3 记忆短期上下文和长期存储要分开设计Agent的“记忆”是个容易被神话的概念实际分两层。短期上下文就是当前任务的对话历史包括用户输入、工具调用、中间推理等。它的容量受限于模型的上下文窗口。超出窗口怎么办要么对早期的过程做摘要要么只保留最近几轮不能无脑塞。长期记忆则要落到外部存储。比如把用户偏好、历史订单、历史决策写成结构化记录或向量下次任务开始时按用户ID检索相关记录放进来。这里的核心是“检索”而不是“全量塞入”。把几年的历史全部塞给模型只会让模型被无关信息淹没看起来参数很足实际效果很差。5.4 防呆权限、超时、预算、人工审批缺一不可Agent的“自主”是一把双刃剑。一旦它真的能调用工具就一定会犯错。我在生产环境里要求的底线配置是这四样权限最小化。每个工具只给当前任务需要的最小权限绝不让Agent拥有一把“删库”级别的刀。超时与最大步数。任务必须有硬性极限绝不允许无限制循环。预算上限。把token和费用预算写进系统超了就停机。很多失控事故都是从“多跑了几十个循环”开始的。人工审批。凡是会产生真实世界影响的动作发邮件、下单、改数据库一律不直接执行而是返回一个确认请求等人在界面上点了确认再执行。这四条优先级甚至高于模型本身的聪明程度。宁可用一个笨但可靠的Agent也不要一个聪明但会乱动手的Agent。6. 从Demo到生产我踩过的坑和给新手的建议6.1 模型在循环里原地打转怎么办我见过最多的故障是Agent一直重复调用同一个工具或者陷入“调用A工具→返回结果→还想调用A工具”的循环。表面上看是模型傻实际上通常是两个问题一是工具返回的信息不满足模型下一步需要它只能重试二是提示词里没有告诉模型“什么时候该停”。解决思路有三个把任务的完成条件写清楚给工具增加去重和缓存给最大步数设一个严格限制。有团队把最大步数设到50一个简单查询任务跑了40多步费用直接爆掉。生产环境我一般默认5步特殊情况再放宽到10。6.2 Token消耗比想象中快得多新手容易低估工具调用对token的消耗。一次普通对话可能只要几百token一个Agent任务却可能在内部跑四五个工具调用每个工具返回几百上千token几个来回下来就是几千token复杂度一高上万也不奇怪。所以做Agent项目成本预估要按“任务数×每任务平均token数”来算而不是按“对话轮次”来算。优化手段包括精简工具返回字段、给工具结果加缓存、控制历史消息长度、能用小模型做的步骤比如摘要不要用大模型。6.3 忽略评估等于闭着眼睛改流程Agent没有标准答案同一个输入模型每次输出可能都不一样这是它和传统接口最大的差别。正因如此回归测试更重要。我习惯的做法先攒20到30条来自真实业务的典型case用相同输入跑一遍记录任务成功率、平均步数、平均耗时、平均token、失败原因这几个指标。改动提示词、换模型、加工具之后都用同一份case重跑。如果没有这套评估你根本不知道这次改动是变好了还是变坏了只能靠感觉。靠感觉的Agent项目通常活不长。6.4 一张表排查最常见的故障现象常见原因处理建议Agent反复调用同一个工具工具结果不满足下一步需要精简返回字段、增加缓存和去重模型完全不调用工具提示词没说清、平台开关没打开在系统提示词里写明“必须先查工具”检查开关最终回答和工具结果无关工具结果没被放回messages检查tool消息及tool_call_id是否正确任务经常超时最大步数过高或单步耗时过长限制步数、把慢工具改成异步长时间不输出模型连续输出text但没最终结果校验是否误判了结束条件这张表不是标准答案而是我排障时的一个习惯先看日志再猜模型不要一上来就怪“模型太笨”。大多数问题都出在工程侧不在模型侧。6.5 我的学习与落地路径建议如果你现在刚接触Agent我的建议路径是先用现成平台Dify这类搭一个真实业务场景完整走一遍从提示词到工具的流程把Agent循环的体感建立起来然后对照本文第3章的代码自己画一遍调用过程理解状态是怎么流转的接着尝试给Agent加一个新工具比如查订单、播报库存等你觉得平台或者框架限制你了再深入LangGraph或者自己写核心循环。我在带团队时反复强调一句话不要先研究框架先研究循环。框架会更新但“感知—推理—行动—观察”这套循环思路不会变。说个我自己的体会。刚开始做Agent时我很喜欢把工具数量堆得很多觉得功能越全越厉害。后来在真实项目里踩了几次坑才发现工具越少越好少而精才能真正可控。一个Agent能用好三五把工具已经能解决绝大多数业务问题。把工具定义清楚、返回格式整理干净比一味追求模型聪明更重要。
这两年做AI应用开发最常被朋友问的一句话是“我把GPT接到业务里做了个Agent你帮我看看效果怎么样”点开一看绝大多数其实是套了一层提示词的聊天机器人。这不是咬文嚼字聊天机器人和智能体Agent的架构、故障模式、迭代方式完全不同搞混了后面会吃大亏。这篇文章就用最直白的方式把一个大模型智能体的简易流程讲清楚一个任务进来之后Agent内部到底经历了什么你应该怎么设计工具、怎么选框架、怎么避开最常见的坑。目标是让有基础编程能力或者天天泡在AI工具里的人看完能搭出第一个真正干活的Agent。1. 先泼一盆冷水聊天机器人不等于智能体1.1 用“会不会主动做事”来判断很多人把Agent当作“升级版聊天机器人”接上大模型API写一段系统提示词再套一个好看的网页就对外叫Agent。这种理解最大的问题是把“响应”当成了“行动”。聊天机器人的工作模式是用户输入 → 大模型生成文本 → 展示。整个过程只有一次模型调用模型没有渠道去获取任何外部信息只能依赖自己的内置知识。而Agent的工作模式是循环式的用户给一个目标 → 模型判断需要什么信息 → 调用工具获取信息 → 基于反馈继续推理 → 直到目标达成。所以“会不会根据用户的目标主动调用外部工具”是我判断一个系统到底是不是Agent最直接的试金石。这不是说聊天机器人不好很多客服场景它反而是最合适的选择而是说如果你想解决的是“需要实时数据、需要操作外部系统”的问题那就必须用Agent架构。为了更直观我列个对比对比项聊天机器人智能体Agent核心模式一问一答任务循环模型调用次数通常一次多次直到任务完成外部工具不调用主动调用典型问题知识截止、编造数据循环失控、工具出错1.2 大模型的能力边界决定了Agent的必然性大模型隐含的假设是“知识都在参数里”但这一点在实际业务中会带来三个硬伤。第一知识有截止日期。训练完毕的那一刻它对世界的认知就冻结了最新的事件、行情、政策它都不知道。第二它没有实时交互能力。问“现在几点”“今天上海天气如何”“这个订单发货没”它回答不了因为参数里没有这些状态。第三它会一本正经地编造数据。让它猜一个具体数字它宁可编一个看起来合理的数字也不愿意承认自己不知道。也就是说大模型真正擅长的是“理解意图、拆解步骤、组织表达”不擅长的是“精确地读取和修改现实世界状态”。Agent恰好补上了这块短板把模型当作大脑把工具当作手脚让大脑指挥手脚去获取事实、完成任务。看懂了这个前提你就能明白为什么现在所有主流Agent方案都在围绕“工具调用”做文章——工具是模型和现实世界之间唯一的通道。1.3 一个Agent应该具备的四个特征如果让我给Agent下个定义至少要包含这四件事缺一个都不完整目标驱动。输入是一个“任务”比如“把这份Excel里的低库存商品整理成预警清单并发给我”而不是一句简单的问候。自主规划。由模型决定先做什么、再做什么步骤不是程序员预先写死的。工具调用。能调用至少一个外部函数、API或服务去获取信息或产生影响。反馈修正。拿到工具结果后发现自己原来的计划有问题能调整计划继续执行。这四条是递进的。如果只做到了“任务输入预设工作流”那算半个Agent如果只有对话没有工具那就还停留在聊天机器人阶段。理解了这些基础下面看看Agent内部到底是怎么跑的。2. 一个Agent跑通任务的完整循环从提问到交付中间发生了什么2.1 用一次“出差安排”看懂循环我在给团队讲Agent原理时最喜欢用一个例子让Agent安排明天去上海的出差行程。这个任务够日常又能把整个循环的复杂度体现出来。如果是聊天机器人它会直接生成一篇“建议你去外滩、陆家嘴……”的小作文而Agent的流程完全不同。模型先解析任务地点上海、时间明天、要求交通便利。接着它意识到自己并不知道明天的天气也不知道各地点间的通行时间于是安排第一步行动——调用天气工具查询上海明天天气。拿到“明天下雨”的结果之后它调整计划把原本排在室外的景点砍掉换成室内场馆。然后第二步调用地图时间估算工具计算两个室内地点之间坐地铁要多久。最后把所有信息组织成一份带时间表的行程。这个过程中模型被调用了很多次每一次调用都基于上一次工具返回的新信息。这就是Agent和普通API调用的本质区别——它在循环里工作而不是一锤子买卖。这也是为什么很多人第一次看Agent日志会觉得“啰嗦”因为系统真的像人一样查一次资料思考一会儿再查一次再思考。2.2 循环里的四个阶段感知、推理、行动、观察一个Agent循环可以拆成四段感知、推理、行动、观察。感知Observation把用户输入、工具返回结果、历史消息这些信息整理成模型当前能读到的上下文。推理Reasoning模型根据当前上下文判断“还缺什么信息”“下一步该干什么”。在ReAct风格的实现里这一步通常表现为模型输出Thought想法和Action动作。行动Action执行一次具体动作比如调用天气API、执行一段Python代码、查询数据库。动作的类型由Agent可用的工具集决定。观察Observation把动作的执行结果比如API返回的JSON再放回上下文里。观察结束后模型开始下一轮推理。如果它觉得还缺信息就继续行动如果它觉得信息够了就输出最终答案。这个“推理—行动—观察”的循环会一直重复直到任务完成或到达终止条件。2.3 没有终止条件的循环就是失控循环Agent循环听起来简单但有一个潜在问题模型是概率性的它有可能永远觉得“还不够”。比如让它收集某一年的行业数据它会一次一次去查查完觉得还可以更全于是再查一次直到token耗尽或者预算打爆。所以一个工程上可用的Agent必须有明确的终止信号完成信号。模型决定不再调用工具输出最终回复这是最理想的终点。最大步数。不管完成没有循环到N轮常见3到10轮就强制结束。超时与预算。整个任务达到一定时长或token数就截断避免失控。这三个条件在实际系统里通常同时存在。后面的最小Demo就实现了“完成信号最大步数”两个先让你直观感受一下。3. 不依赖框架手写一个最小可运行的Agent Demo3.1 环境准备一个兼容接口就够了很多人以为写Agent一定要上LangChain这种重框架其实不然。Agent的核心循环用代码实现起来很短几百行以内就能写完。我建议所有想深入的人先手写一遍最小循环把手感建立起来再谈框架。准备条件很简单Python 3.8以上安装openai库因为大多数大模型服务都提供OpenAI兼容接口无论云端还是本地部署都能用一个可用的API Key和base_url。我之所以用OpenAI兼容方式来写是因为这样你后面换模型时只需要改model和base_url核心逻辑完全不用动。这对“不绑定某个供应商”非常重要。3.2 定义工具天气查询函数与它的Schema先做一个最简单的工具函数查询天气。我用内置字典模拟数据真实项目里替换成HTTP调用即可。def get_weather(city: str) - dict: weather_table { 北京: {temperature: 18, condition: 晴, wind: 3级}, 上海: {temperature: 22, condition: 多云, wind: 2级}, } data weather_table.get(city) if not data: return {error: f暂不支持查询城市 {city}} return {city: city, **data}但光有Python函数不够模型并不知道这个函数的存在必须给它一份JSON Schema。这就是Function Calling的“说明书”tools [ { type: function, function: { name: get_weather, description: 查询指定城市当前天气情况包括温度、天气状况和风力。, parameters: { type: object, properties: { city: { type: string, description: 城市名例如 北京、上海 } }, required: [city] } } } ]这里有个容易被忽略的点description写得越清楚模型选错参数的概率越低。很多人随便写一句“查询天气”模型就经常把“北京明天”整个塞进city字段。把参数含义和示例写清楚是工具设计的第一课。3.3 核心循环用代码实现感知—推理—行动—观察工具定义好了接下来实现Agent主循环。流程是把用户问题放入messages调用模型带上tools参数判断返回结果里有没有tool_calls有就解析函数名和参数执行本地函数把结果以roletool的message放回messages继续循环没有说明模型准备直接输出取出content结束。代码如下import json import openai client openai.OpenAI( api_key你的API_KEY, base_urlhttp://你的服务地址/v1, ) def run_agent(user_input: str, max_steps: int 5) - str: messages [{role: user, content: user_input}] for step in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, # 换成你实际用的模型 messagesmessages, toolstools, ) message resp.choices[0].message messages.append(message) if not message.tool_calls: return message.content for tool_call in message.tool_calls: fn_name tool_call.function.name args json.loads(tool_call.function.arguments) print(f[Step {step1}] 调用工具: {fn_name}({args})) if fn_name get_weather: result get_weather(args[city]) else: result {error: f未知工具 {fn_name}} messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) return 已达最大步数任务未完成请调整提示词或工具。这段代码就是一个完整的Agent骨架。整个过程中messages的维护是核心每一步模型的历史消息必须完整保留尤其不能漏掉tool角色返回的那一条。一旦漏掉模型就不知道刚才调用的工具结果是什么然后开始胡编。3.4 跑一个例子看Agent的中间轨迹用“北京明天适合跑步吗”来跑你会看到一个典型轨迹Step 1模型输出tool_calls调用get_weather({city: 北京})工具返回 {city: 北京, temperature: 18, condition: 晴, wind: 3级}Step 2模型不再调用工具输出最终结论“北京明天是晴天温度18度风力3级适合跑步建议穿一件薄外套。”但注意这个Demo有一个明显缺陷它查的是“当前天气”而不是“明天天气”因为工具本身没做时间区分。这就引出一个重要结论工具能力决定了Agent能力的上限。模型再聪明也只能在工具给的数据范围内做判断。真实系统里你的工具必须覆盖任务所需的真实数据源。4. 用现成平台搭建智能体Dify这类工具到底帮你省了什么4.1 为什么已经有手写Demo还要用框架上面的Demo能跑通但它距离“可生产的Agent”还有很长的路。你会立刻遇到几个问题多个用户并发时上下文状态怎么隔离工具调用日志在哪里看运营同事想调整提示词难道要改代码重新部署吗某个模型服务不稳定想一键切换怎么办。这些就是Agent框架和平台存在的价值。它们把对话状态管理、工具注册、模型供应商适配、日志追踪这些公共能力提前做好了。你要做的只是填写业务相关的提示词和工具。所以我的判断是如果你是产品经理或业务方直接用可视化平台搭如果你是开发也建议先用平台快速验证业务再决定要不要自研。先跑通再优化永远比一上来就写框架稳。4.2 在Dify上搭建一个Agent的完整步骤Dify是现在比较主流的开源智能体平台既支持私有化部署也有官方云端版本。在Dify里搭一个Agent完整流程大概是这样的登录后创建“Agent”类型应用这里注意别选成“Chatbot”或“Workflow”类型选错后面的交互逻辑完全不一样。在“模型”配置里选择模型供应商填写API Key选好具体模型。编写系统提示词。这一步最重要建议显式写明你是谁、你能调用哪些工具、什么情况必须调用工具、输出格式是什么。在“工具”区域添加工具。Dify自带了一批内置工具比如搜索、天气、计算器也支持自己导入OpenAPI Schema把你公司的接口暴露给Agent。打开“模型自行调用工具”的开关。这是Agent类型应用和其他应用最大的区别不开这个开关模型就不会主动用工具。在调试界面输入一个任务点运行看每一步的输入输出特别是工具返回的原始内容和模型基于它生成的推理。满意后发布Dify会生成API接口你可以把它接到自己的前端、公众号、企业微信机器人等地方。很多人卡在第4步。自己写的内部接口要以OpenAPI格式导入建议先用一个简单的GET接口试通再上POST和复杂鉴权一次全上很容易排查不出问题。4.3 主流框架怎么选LangGraph、Dify、Coze、AutoGen对比我按自己的理解做了一张对比方便你对号入座。框架/平台形态适合谁核心优势主要成本LangGraphPython代码库开发者为主对状态的精细控制适合复杂图结构Agent学习曲线陡所有事都要写代码Dify可视化平台可私有化产品/运营为主开发配合搭得快日志清晰能对接多种模型高度自定义场景需要写插件Coze云端平台想快速接内容生态的个人/团队插件市场丰富发布渠道多不用运维平台绑定较深扩展受平台限制AutoGenPython代码库研究多智能体协作支持多Agent对话和任务编排生产稳定性需要自己做更多工作这里不做“谁更好”的结论只看匹配度。先想清楚业务逻辑的复杂度、团队里谁会维护、对数据私有化的要求再选型。4.4 关于选型的个人建议如果让我给一个通用建议大多数业务型项目从Dify这类可视化平台起步是最保险的因为它的可观测性天然比代码好。你的运营同事也能直接看到Agent每一步在干什么这在debug阶段价值巨大。当业务长到平台满足不了比如需要非常精细的状态机、复杂的反思循环再迁移到LangGraph这类代码框架。到了最后你会发现自己写核心循环不难难的是周边生态比如监控、评估、权限控制。这些成熟平台已经替你解决了不少。5. 让Agent在真实场景撑得住工具设计、记忆与防呆5.1 工具调用的两种主流实现Function Calling与ReAct很多人以为工具调用只有一种方式其实区别挺大。我分一下Function Calling模型经过专门训练会直接输出一个结构化的JSON包括函数名和参数。代码拿到后直接执行不需要去解析自然语言。好处是稳定、解析成本低坏处是要求模型本身支持这个能力。ReAct模型不输出结构化JSON而是按提示词要求输出Thought、Action、Action Input这样的固定格式代码用正则或字符串匹配去解析。好处是任何模型都能用坏处是格式不稳定一旦模型哪天不按套路出牌解析就崩了。实际项目里我会优先用Function Calling因为它把“意图到参数”的转换变成了模型的原生能力。但如果用的是本地部署的开源模型且该模型不支持Function CallingReAct是可行的兜底方案。对比项Function CallingReAct依赖模型原生支持需要不需要输出稳定性高一般受提示词影响大解析成本低直接JSON解析高需要解析文本格式工具数量多了之后能处理较多工具容易混乱5.2 工具返回格式决定了Agent的下限Agent在做工具调用时最怕的不是失败而是返回结果“没法看”。想象一个场景工具返回了一大段HTML页面或者一个几千行的查询结果。模型需要从中提取有用信息噪声一大推理质量立刻下降token开销也会指数上涨。所以你设计的每一个工具返回时都应该做“面向模型的摘要”。我的习惯是外部API拿到数据后先过滤掉模型用不到的字段只保留必要的、JSON格式干净的字段再返回给模型。如果数据量实在大就先让一段脚本或一个小模型提炼成要点再塞回上下文。工具返回做得干净Agent的成功率会肉眼可见地提升。5.3 记忆短期上下文和长期存储要分开设计Agent的“记忆”是个容易被神话的概念实际分两层。短期上下文就是当前任务的对话历史包括用户输入、工具调用、中间推理等。它的容量受限于模型的上下文窗口。超出窗口怎么办要么对早期的过程做摘要要么只保留最近几轮不能无脑塞。长期记忆则要落到外部存储。比如把用户偏好、历史订单、历史决策写成结构化记录或向量下次任务开始时按用户ID检索相关记录放进来。这里的核心是“检索”而不是“全量塞入”。把几年的历史全部塞给模型只会让模型被无关信息淹没看起来参数很足实际效果很差。5.4 防呆权限、超时、预算、人工审批缺一不可Agent的“自主”是一把双刃剑。一旦它真的能调用工具就一定会犯错。我在生产环境里要求的底线配置是这四样权限最小化。每个工具只给当前任务需要的最小权限绝不让Agent拥有一把“删库”级别的刀。超时与最大步数。任务必须有硬性极限绝不允许无限制循环。预算上限。把token和费用预算写进系统超了就停机。很多失控事故都是从“多跑了几十个循环”开始的。人工审批。凡是会产生真实世界影响的动作发邮件、下单、改数据库一律不直接执行而是返回一个确认请求等人在界面上点了确认再执行。这四条优先级甚至高于模型本身的聪明程度。宁可用一个笨但可靠的Agent也不要一个聪明但会乱动手的Agent。6. 从Demo到生产我踩过的坑和给新手的建议6.1 模型在循环里原地打转怎么办我见过最多的故障是Agent一直重复调用同一个工具或者陷入“调用A工具→返回结果→还想调用A工具”的循环。表面上看是模型傻实际上通常是两个问题一是工具返回的信息不满足模型下一步需要它只能重试二是提示词里没有告诉模型“什么时候该停”。解决思路有三个把任务的完成条件写清楚给工具增加去重和缓存给最大步数设一个严格限制。有团队把最大步数设到50一个简单查询任务跑了40多步费用直接爆掉。生产环境我一般默认5步特殊情况再放宽到10。6.2 Token消耗比想象中快得多新手容易低估工具调用对token的消耗。一次普通对话可能只要几百token一个Agent任务却可能在内部跑四五个工具调用每个工具返回几百上千token几个来回下来就是几千token复杂度一高上万也不奇怪。所以做Agent项目成本预估要按“任务数×每任务平均token数”来算而不是按“对话轮次”来算。优化手段包括精简工具返回字段、给工具结果加缓存、控制历史消息长度、能用小模型做的步骤比如摘要不要用大模型。6.3 忽略评估等于闭着眼睛改流程Agent没有标准答案同一个输入模型每次输出可能都不一样这是它和传统接口最大的差别。正因如此回归测试更重要。我习惯的做法先攒20到30条来自真实业务的典型case用相同输入跑一遍记录任务成功率、平均步数、平均耗时、平均token、失败原因这几个指标。改动提示词、换模型、加工具之后都用同一份case重跑。如果没有这套评估你根本不知道这次改动是变好了还是变坏了只能靠感觉。靠感觉的Agent项目通常活不长。6.4 一张表排查最常见的故障现象常见原因处理建议Agent反复调用同一个工具工具结果不满足下一步需要精简返回字段、增加缓存和去重模型完全不调用工具提示词没说清、平台开关没打开在系统提示词里写明“必须先查工具”检查开关最终回答和工具结果无关工具结果没被放回messages检查tool消息及tool_call_id是否正确任务经常超时最大步数过高或单步耗时过长限制步数、把慢工具改成异步长时间不输出模型连续输出text但没最终结果校验是否误判了结束条件这张表不是标准答案而是我排障时的一个习惯先看日志再猜模型不要一上来就怪“模型太笨”。大多数问题都出在工程侧不在模型侧。6.5 我的学习与落地路径建议如果你现在刚接触Agent我的建议路径是先用现成平台Dify这类搭一个真实业务场景完整走一遍从提示词到工具的流程把Agent循环的体感建立起来然后对照本文第3章的代码自己画一遍调用过程理解状态是怎么流转的接着尝试给Agent加一个新工具比如查订单、播报库存等你觉得平台或者框架限制你了再深入LangGraph或者自己写核心循环。我在带团队时反复强调一句话不要先研究框架先研究循环。框架会更新但“感知—推理—行动—观察”这套循环思路不会变。说个我自己的体会。刚开始做Agent时我很喜欢把工具数量堆得很多觉得功能越全越厉害。后来在真实项目里踩了几次坑才发现工具越少越好少而精才能真正可控。一个Agent能用好三五把工具已经能解决绝大多数业务问题。把工具定义清楚、返回格式整理干净比一味追求模型聪明更重要。
