大概在半年前我被问得最多的问题还是“大模型怎么调 API”而最近两个月这个问题已经悄悄变成了“Agent 到底怎么搞”。不管是做内部工具、智能客服还是想把工作流里的重复环节自动化大家心里想的其实都是同一件事能不能让模型不只是聊天而是自己去调用工具、完成任务。这其实就是 Agent 开发的核心。说穿了Agent 并不是什么黑魔法——它就是一个“会用工具的对话系统”让大模型在回答问题之外还能去查天气、搜数据库、调接口、写代码甚至操作浏览器。而“开发入门”这四个字的难点从来不是“不会写代码”而是要理解 Agent 的架构、选型逻辑和踩坑规律。这篇文我按自己的实战经验捋一条路线从核心概念、模型选型、框架对比到一个最小可运行的 Agent 完整代码再到最容易被坑的上下文与记忆问题最后附一份常见问题排查表。所有内容都是偏实操的适合刚入门或已经在边学边做的朋友参考。1. 先搞清楚Agent 到底是个什么玩意儿1.1 别被概念绕晕Agent 本质上是什么Agent 这个词听起来高大上但拆开看它其实就是三件事的叠加第一让大模型具备“任务拆解”的能力。你丢给它一个目标比如“帮我调研一下上周竞品的定价策略”它不直接给答案而是先把这个目标拆成几个子步骤——搜索资料、筛选信息、对比分析、生成报告。第二给模型配上“手和脚”。也就是工具调用Function Calling / Tool Use。模型本身只是一个“大脑”无法访问外部世界但通过工具调用它可以执行代码、访问数据库、调用搜索引擎、读写文件。这是 Agent 和纯 Chatbot 最大的分水岭。第三加入一个“执行循环”。模型思考 → 调用工具 → 拿到结果 → 再思考 → 再调用……直到任务完成。这个循环就是 Agent 的核心运行机制也是所有框架都在背后帮你做的事。用生活化的比喻来说普通的 Chatbot 是一个只动嘴皮子的顾问而 Agent 是一个既会思考又会动手干活儿的员工。它虽然还是会犯错但至少具备了“把一件事办成”的闭环能力。1.2 为什么这两年 Agent 突然火了很多人问Agent 这个概念不是早就有了吗为什么现在还拿出来讲。确实早年也有基于规则的 Agent但那时候它依靠人工编写的 if-else 逻辑无法应对开放性问题。真正让 Agent 冲出圈的核心变量是大模型带来了两个关键能力一是意图理解能力。模型能听懂自然语言背后的真实需求而不是靠关键词匹配。这使得 Agent 可以处理开放式任务比如“帮我整理一下这个项目里所有 TODO 注释”模型知道要用 grep 或读文件的方式去扫描而不是死板地等着你选菜单。二是工具调用能力。今天的模型在训练阶段就专门优化了工具接口。只要你按照特定的 Schema 给它声明工具它就能自己生成格式正确的调用请求。这相当于模型本身就学会了“使用说明书”你在旁边给它一本手册它就会照着操作。再加上开源模型和推理框架的成熟玩 Agent 的成本被迅速拉低。以前做一套自动化流程要写几百行业务逻辑现在可能定义一个工具函数就够了。大环境已经变了Agent 开发从“实验室玩具”变成了“工程问题”——这也是我建议每个做 AI 应用的人都认真学一遍 Agent 的重要原因。1.3 Agent 和 Chatbot、RAG、Workflow 的区别要把 Agent 讲清楚必须先把几个容易混淆的概念摆在一起对比。名称核心机制典型场景交互形态Chatbot单轮/多轮对话直接生成回复问答机器人、闲聊助手一问一答RAG先检索文档再让模型生成企业知识库问答、客服文档辅助一问一答引用来源Workflow预先编排的固定步骤数据清洗、定时报表、审批流流程驱动Agent模型自主决策、循环调用工具自动化调研、多步操作、动态任务目标驱动、循环执行从这张表能看出来RAG 和 Workflow 都是“把人要做的事情告诉机器怎么按步骤走”而 Agent 是“只告诉机器最终要什么让它自己一步一步走”。当然实际工程里它们不是互斥的很多成熟系统是 Agent RAG Workflow 混用。我见过不少团队最外层是 Agent 做意图路由左边挂搜索引擎右边挂知识库 RAG底层再串几条固定的 Workflow 做审批。这也是 Agent 真正的价值所在——它不是取代其他技术而是把其他技术全部“调度”起来。2. 动手前先想清楚模型选型与运行环境2.1 选大模型就是选 Agent 的大脑别随便凑合Agent 的上限很大程度由模型的能力决定。我在入门阶段踩过的最大一个坑就是拿一个只擅长文本续写的模型来跑 Agent结果它根本不会按格式输出工具调用整个流程寸步难行。所以如果你真的想认真做 Agent第一步就是选一个“支持 Function Calling / 工具调用”的模型。选型时我一般按需要回答三个问题第一你的场景能否接受调用外部 API如果能接受优先考虑效率较高的商业化模型。部分服务虽然一开始免费但生产环境下要关注限额尤其是 Agent 这种会连续多次调用模型的场景消耗速度比单轮聊天高出数倍。而且 Agent 天然适合并发的场景选有并发保障的服务更稳。第二你的数据能出域吗对数据安全要求极高的业务比如医疗、金融、内部审计答案通常是不能。这时候要走私有化部署路线——用开源模型自建 Agent 服务数据完全不出内网。第三你需要在多模态环境下工作吗如果 Agent 要处理图片、PDF 扫描件、表格截图就需要选带视觉能力的多模态模型。很多 Agent 在流程设计上把“看图”误当作普通文本处理效果会差很远。在开源模型里Qwen 系列和 Llama 3.1 系列都有不错的工具调用能力前者对中文场景更友好后者胜在生态大、社区资料多。我个人的经验是做中文业务优先考虑 Qwen做国际化产品优先考虑 Llama。如果你还在犹豫可以把两三个模型放在同一个测试集上跑一遍工具调用准确率用数据说话效果比看测评文章靠谱得多。2.2 推理框架与部署方案选定模型之后第二步是搞定推理框架。如果只是本地实验、不追求生产很多框架足够用了。但一旦要面对并发请求就要认真考虑推理服务的架构。我自己习惯用 Ollama 做原型验证因为安装简单、模型下载方便一条命令就能跑起来。但原型和上线是两回事——Ollama 的并发吞吐能力在压力上来时会成为瓶颈倒不是说它不能用于生产而是你需要额外做请求排队、超时重试、水平扩容这些工程化改造。如果一开始就奔着生产环境去我建议考虑 vLLM 或 SGLang 这类专门为高吞吐推理设计的框架。它们支持连续批处理continuous batching能把多用户的请求动态拼成一个 batch 送进 GPU显存利用率高很多。实测下来在相同的显卡配置下这类框架的吞吐量通常比朴素的逐请求推理高出数倍。另外要提醒一句不要忽略上下文的长度。Agent 在一次任务里可能来回调用工具几十次每次对话历史都会累计模型需要的上下文窗口如果太小很快就会被截断。选模型和部署框架时最好直接选支持长上下文的版本并且在逻辑层做好历史压缩和裁剪后面第 5 部分专门讲。2.3 并发问题Agent 系统的隐性门槛很多人在本地单测时一切顺畅一上生产就崩原因往往不在单请求的执行逻辑而在并发量。一个大模型 API 响应时间在几秒到几十秒之间一个 Agent 任务调用几次模型单个用户的一次请求就可能让服务器占用半分钟以上的时间。如果同时来 100 个用户就是一场大考。处理思路有三板斧。第一是异步化别用同步阻塞式的 Flask 应用直接跑长任务用 FastAPI 的异步接口或者更底层的异步队列去承接请求。第二是加缓存把重复出现的工具调用结果、检索结果、常见问题答案做缓存能省掉大量模型调用。第三是限流和降级对每个用户、每个工具设置配额超出部分直接返回排队提示而不是把服务打挂。这里有个实战细节在代码层面可以给每个 Agent 实例加一个信号量Semaphore来限制并发超出阈值的请求自动排队。同时给工具调用加上超时某个工具卡住了不能一直阻塞整个循环。这些虽然都是老生常谈的工程手段但在 Agent 场景下尤其重要因为你是在跟一个“不可预测的模型”协作而不是在调一个规格明确的服务。3. 框架到底怎么选LangChain、AutoGen、Dify 还是自研3.1 几个主流框架的定位差异框架选型是新手最容易纠结的问题因为网上的评测和争吵太多了。我的观点很直接没有最好的框架只有最合适的场景。LangChain / LangGraph生态最丰富资料最多适合想深入理解 Agent 机制、愿意自己掌控编排逻辑的人。LangGraph 特别适合有状态、有分支的复杂 Agent 流程因为它是基于图结构来做状态转移而不是简单的链式调用。AutoGen / CrewAI / 多智能体框架核心卖点是“多智能体协作”让几个模拟不同角色的 Agent 互相讨论、分工、验证。适合研究实验和团队协作模拟但如果你的业务只是“一个助手完成一件事”用多智能体反而画蛇添足不必要的模型调用和 token 消耗会显著拉高成本。Dify / Coze 这类低代码平台非常适合产品验证和运营人员使用可视化编排、内置知识库、日志面板都很成熟。劣势是灵活的定制能力相对有限特殊业务逻辑可能需要平台原生的插件机制支撑。自研当你的业务逻辑足够简单不想被框架约束或者需求足够特殊自研完全可行。Agent 底层机制自己写并不复杂就是一个消息循环加工具注册表。3.2 我为什么从一个极端建议“第一步先别急着上框架”很多入门教程一上来就让你装 LangChain然后照着文档跑一个 demo。这么做的确快但容易造成一个问题你根本不知道为什么它这么工作出了问题也不知道怎么查。我建议的顺序是反过来的。先用原生代码写一个非常小的 Agent——不需要任何框架只需要一个支持 Function Calling 的模型 API、两个手写的工具函数、一个 while 循环大概 100 行代码就能跑起来。等这个最小实现完全跑通对工具调用、消息循环、上下文累积这些概念有了体感再回头选框架。这就像学做菜想真正理解火候不能只照着成品菜谱做而要自己把肉切一遍、把油温试一遍。框架帮你隐藏了大量细节但在你没建立心智模型之前那些被隐藏的细节恰恰是未来排查问题的关键。如果你已经跑通过原生实现再用 LangChain 或 LangGraph就会觉得它们只是把你自己会做的事封装成好用的 API而不会一头雾水。3.3 一个简单的选型决策流程我给自己总结了一个选型决策清单分享在这里你的情况推荐方案纯入门、想建立认知先自研最小 Agent再学 LangGraph内部工具、快速验证Dify / Coze 可视化搭建复杂流程、多分支状态LangGraph / 自研状态机研究实验、多角色模拟AutoGen / CrewAI深度定制、数据隐私要求高自研 部署开源模型这个清单不一定适合所有人但它体现了一个核心原则框架服务于业务复杂度而不是反过来让业务适配框架。4. 核心实战从零实现一个最小可用的 Agent4.1 代码准备环境与依赖在这个部分我会带你完整跑通一个最小但五脏俱全的 Agent。它做的事情很简单用户问“北京今天适合穿什么衣服”Agent 会调用天气查询工具和温度建议工具最后综合生成回答。用到的工具只有两个get_weather(city)—— 模拟查询天气返回温度、天气状况get_clothing_advice(temp, condition)—— 根据温度和天气给出穿衣建议为了演示清晰我用一个字典模拟天气数据实际项目里替换成 HTTP API 调用即可。模型部分用 OpenAI 兼容接口你也可以换成任何支持 Function Calling 的开源模型服务。先安装依赖pip install openai然后准备好你的 API Key 和 Base URL。如果你是用本地部署的模型把base_url指到你的推理服务地址就行如果你用云端 API直接用官方地址。from openai import OpenAI client OpenAI( api_keysk-xxxxx, base_urlhttps://你的模型服务地址/v1 )这里有一个很实用的点现在很多开源模型服务都提供 OpenAI 兼容接口所以代码写一套后面换模型只需要改base_url和model两个字段其他全部不用动。这也是我把 OpenAI SDK 选为基础依赖的原因——兼容性足够广。4.2 定义工具 Schema接下来是 Agent 开发中最核心的一步定义工具说明。模型看到的是工具的“说明书”而不是工具的实现代码。它根据这些说明决定什么时候调用、传什么参数。tools [ { type: function, function: { name: get_weather, description: 获取指定城市的当前天气信息包括温度和天气状况, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京、上海、广州 } }, required: [city] } } }, { type: function, function: { name: get_clothing_advice, description: 根据温度和天气状况给出穿衣建议, parameters: { type: object, properties: { temp: { type: number, description: 当前温度摄氏度 }, condition: { type: string, description: 天气状况描述例如晴、雨、雪、多云 } }, required: [temp, condition] } } } ]Schema 的关键是description字段。不要小看这句描述——模型对工具功能的理解完全来自这里。描述越具体、边界越清晰模型的调用准确率越高。比如你写“获取天气”模型可能犹豫要不要在用户问“明天冷不冷”时调用它如果你写“获取指定城市的当前天气信息包括温度和天气状况”模型就会明确地知道这正是它需要的工具。4.3 实现工具函数工具函数的签名要和 Schema 里的参数对齐。我在这里做个简单的模拟实现def get_weather(city): # 模拟天气数据实际项目替换为 HTTP 调用 weather_db { 北京: {temp: 18, condition: 晴}, 上海: {temp: 24, condition: 多云}, 广州: {temp: 30, condition: 雨}, } data weather_db.get(city, {temp: 20, condition: 晴}) return f当前{city}气温{data[temp]}摄氏度天气{data[condition]} def get_clothing_advice(temp, condition): if condition 雨: return 建议携带雨伞穿防水外套 if temp 10: return 建议穿羽绒服、毛衣 if 10 temp 20: return 建议穿夹克、长袖衬衫 if 20 temp 28: return 建议穿短袖、薄外套 return 建议穿短袖、短裤注意防晒这里注意工具函数的返回值必须是字符串。因为模型的下一步输入是文本工具返回的内容会被拼进消息历史里。如果你返回结构化的字典或列表也要先序列化成 JSON 字符串再返回否则模型可能读不懂。4.4 核心循环让模型自主决策并调用工具这是整个 Agent 的心脏。逻辑很简单把消息发给模型 → 模型决定是直接回答还是调用工具 → 如果是工具调用执行工具把结果追加到对话里再发给模型 → 重复直到模型不再请求调用工具。def run_agent(user_input): messages [ {role: system, content: 你是一个智能助手可以根据用户的请求调用工具来获取信息并给出合理建议。}, {role: user, content: user_input} ] max_iterations 5 for i in range(max_iterations): response client.chat.completions.create( model你的模型名称, messagesmessages, toolstools, tool_choiceauto ) assistant_message response.choices[0].message # 如果没有工具调用说明任务已完成直接返回 if not assistant_message.tool_calls: return assistant_message.content # 把模型的工具调用请求追加到消息历史中 messages.append(assistant_message) # 逐个执行工具调用 for tool_call in assistant_message.tool_calls: function_name tool_call.function.name function_args json.loads(tool_call.function.arguments) # 根据工具名称分发到对应函数 if function_name get_weather: result get_weather(**function_args) elif function_name get_clothing_advice: result get_clothing_advice(**function_args) else: result f未知工具: {function_name} # 把工具执行结果追加到消息历史中角色是 tool messages.append({ role: tool, tool_call_id: tool_call.id, content: result }) return 已达到最大执行轮数任务未能完成请稍后重试或简化问题。这段代码里有个容易出错的地方messages.append(assistant_message)追加的是完整的 assistant 消息里面包含tool_calls字段这个必须带上否则模型不知道这是它自己之前的调用请求。而工具执行结果的消息必须带tool_call_id用来和 assistant 消息里的工具调用关联起来。这两条规则违反了任何一个模型调用就会报错或者出现上下文错乱。跑一下完整流程if __name__ __main__: result run_agent(北京今天适合穿什么衣服) print(result)预期输出会是类似这样的过程模型先调用get_weather拿到北京气温 18 度、晴天然后调用get_clothing_advice(18, 晴)拿到建议最后生成回答“北京今天气温 18 摄氏度天气晴朗建议穿夹克或长袖衬衫体感舒适。”看到没有模型没有一次性回答“北京适合穿什么”而是先查数据再基于数据给出建议。这就是 Agent 和普通 Chatbot 的区别它不是凭训练时的记忆瞎猜而是真的“看了看现实数据”再开口。4.5 给玩具 Agent 加上一点工程味上面的代码能跑但离生产级别还差得远。我平时在做 MVP 迭代时会逐步加上几个增强点按收益顺序排列第一给工具执行加超时控制。用asyncio或concurrent.futures包一层工具调用超过比如 10 秒就返回“工具超时”让模型决定下一步。不然某个外部 API 卡住了整个 Agent 也跟着卡死。第二做简单的参数校验。模型的参数生成不是百分百可靠的有时候会把参数类型搞错比如把温度传成字符串。工具函数入口做好类型转换和容错能避免大量低级报错。第三引入日志。在每次模型调用、每次工具执行时打印时间戳、token 数、调用内容。Agent 出问题时这些日志能帮你快速定位是模型理解错了还是工具本身出错了。第四加上多轮记忆的截断。当消息历史过长时把早期的对话做摘要或者直接丢弃防止上下文超出窗口长度。这一点真的很重要下面单独用一节来讲。5. 记忆与上下文Agent 能不能多干活的关键5.1 聊两句就“失忆”问题多半出在这Agent 越用越久对话历史越长模型越来越“笨”最后甚至开始胡言乱语。这是新手的第二个大型翻车现场。原因很简单模型每次处理新请求时必须把完整的对话历史都放进上下文窗口。当历史太长时一方面 tokens 不够用导致早期信息被截断另一方面即使能装下模型对长上下文的注意力也会被过度稀释关键的早期指令反而被忽略。就像一个人听你唠了一个小时细节太多早就忘了最开始交代的重点。解决思路有三层。第一层固定窗口。只保留最近 N 轮对话更早的删除。这个方案简单但会丢失重要信息。第二层总结历史。系统会定期把最早的对话用一次额外的模型调用压缩成摘要比如“用户之前提到他是项目经理希望每天生成进度报告”。然后历史替换为“摘要 最近 M 轮”。这样既保留了关键信息又控制了体积。第三层外部记忆。真正需要长期记忆的场景用一个向量数据库比如 ChromaDB、FAISS来存历史关键信息。每次用户说话先用 embedding 搜索相关记忆再把命中的记忆拼进提示词。这也是“给 Agent 装上长期记忆”的标准做法。5.2 长期记忆还涉及 Agent 的个性化除了技术实现还有一个产品层面的问题Agent 需不需要“记住用户”很多团队把 Agent 设计成一次性的用户每次来了重新介绍自己。但实际体验下来如果一个 Agent 自己能记住偏好——比如“我一直用这个工具的人喜欢简洁回答”“我不喜欢每次重复解释背景”那种感觉完全不同。这类记忆目前最朴素但有效的做法就是把“用户偏好摘要”也存成一个结构化的记忆库每次对话之前先检索、再注入。这个方向上做好做坏差异很大也是拉开 Agent 体验差距的一个点。5.3 上下文管理的三个实用小技巧一是预算分配。对启动时固定的 system prompt、工具定义、RAG 检索结果分别设定 token 上限比如总共 8K 上下文system工具的说明最多占用 2K历史最多 4K每次检索结果控制在 2K 以内。这样系统行为更可预期。二是压缩优先于截断。能摘要就不要直接砍。砍了之后你永远不知道模型丢掉了哪个关键信息。摘要虽然多花一次模型调用但长期稳定。三是善用stop和工具约束。在某些任务里可以通过提示词明确告诉模型“最多调用三次工具”避免 Agent 进入死循环。虽然模型不是百分百遵守但多数场景下有效。6. 常见问题与排查技巧实录6.1 高频问题速查表我把自己在开发中遇到过的问题整理成了一张速查表配合典型排查路径现象可能原因排查步骤解决建议模型不调用工具工具描述不清晰查看模型原始输出确认是否生成 tool_calls重写工具描述增加“何时使用”的说明模型反复调用同一个工具上下文里缺少终止条件检查循环限制和提示词在提示词中明确“得到答案后停止”上下文溢出报错历史消息太长统计消息 token 总量加摘要压缩或滑动窗口工具结果返回乱码序列化问题打印工具返回值统一返回 JSON 字符串Agent 回答明显错误却不知错缺少反思环节检查中间日志增加一次模型自校验调用生产环境并发一高就挂推理瓶颈或缺少限流监控 GPU 和 API 调用量上推理框架、加队列、加缓存6.2 两个翻车案例与排查过程案例一一个给财务团队做的报销 Agent用户上传发票图片后模型总是自己“脑补”金额而不去调用 OCR 工具。排查后发现问题出在给模型的工具描述是“提取图片中的文字”而正确的做法应该强调“在进行任何金额判断之前必须先调用 OCR 工具”。改完描述之后模型在绝大多数轮次都会主动先调 OCR 再回答。这个案例印证了一个道理Agent 的很多问题不是出在模型能力上而是出在“说明书”没写清楚。案例二一个内部知识问答 Agent用户问“去年的年度总结在哪”模型检索到一个相关文档后直接回答“在知识库里”不再继续调用工具读取内容。这是因为工具定义里的“搜索工具”描述让模型以为搜到就结束了。修复方式是把流程拆成两个工具搜索工具负责定位文档 ID阅读工具负责读取具体内容并且提示词说明“当拿到文档 ID 后必须继续调用阅读工具”。拆完工具之后准确率明显提升。6.3 我调 Agent 常用的调试三板斧第一板斧打开原始输出。不管用什么框架第一件事永远是看模型到底输出了什么——是直接回复了一段话还是生成了工具调用这个原始响应包含的信息量远超一切日志。第二步是看工具返回的实际数据确认到底是模型理解错了还是工具本身出了问题。第二板斧最小化复现。把问题 Prompt 缩小到一条消息、一个工具反复测试。很多时候问题不是工具逻辑而是上下文里某个历史消息的干扰。缩小范围后很容易定位。第三板斧镜像对比。保留同一个 Prompt分别换不同模型跑看会不会触发同样的问题。如果换了模型就正常了那基本可以断定是原来模型在工具调用上的能力差异而不用怀疑自己的代码。7. 对新手最有价值的一个认知最后想分享一个我多次跟朋友强调的观点Agent 开发入门最关键的转折点不是你背会了多少框架 API而是你真正理解了“模型 工具 循环”这个过程并且亲手把这三个环节拼接起来跑通过一遍。在我自己看来最快的学习路径就一条先写一个 100 行的原生 Agent就像第 4 部分这种跑通然后刻意制造故障再修好比如故意写错工具 Schema 看模型怎么反应、故意让工具超时看 Agent 怎么处理、故意把历史撑爆看会发生什么。经历过这些坑之后你再去看任何框架的文档都会觉得通透很多。如果这篇文章只能给你留下一个认知我希望是这个Agent 不是什么不可企及的高深技术它是一个你需要用工程思维去伺候的协作系统。模型负责思考工具负责执行循环负责推进而你的工作就是当好这三者之间的“调度员”。把这个调度逻辑想明白后续学什么都快。
