最近总有朋友问我想上手大模型智能体Agent开发预算又有限到底该选哪个模型说实话这个问题我当初也纠结了很久。GPT-4o 能力确实强但每次工具调用链跑下来Token 费用肉眼可见地跳涨本地小模型又撑不起稳定的 function calling。最后我把日常开发和生产环境都锁定在“LangChain GPT-4o-mini”这个组合上智能体的编排逻辑交给 LangChain模型的工具调用和自然语言理解交给 4o-mini。跑了几十个真实任务之后效果超出我预期——响应延迟低常见工具的调度准确率够用成本大约是满血版的十分之一量级。这篇文章我就把选型思路、搭建过程、踩过的坑以及可以直接照抄的代码全部摊开适合刚接触智能体开发、想在真实项目里快速落地的开发者参考。1. 为什么我用 GPT-4o-mini 而不是“满血版”大模型1.1 先看账单智能体最烧钱的不是“对话”是“循环”在做选型之前得先搞清楚智能体的计费逻辑。普通聊天是一次“输入-输出”花不了多少 Token。但 Agent 不一样它会自己规划、调用工具、拿到结果后再继续思考经常要往返好几轮才算完成一个任务。举个例子用户问“今天上海适合穿什么衣服”一个完整的智能体工作流可能是系统提示词加工具描述大约 2000~3000 Token用户问题再占几百 Token这是第一次请求。模型决定调用天气查询工具返回一个工具调用指令。工具执行完把天气结果作为 ToolMessage 塞回上下文这又要重新发送前面所有历史加上工具结果。模型读完天气结果可能还觉得信息不够再调一次空气质量接口。这么一圈下来一次看似简单的问题实际消耗的 Input Token 经常是“问题本身”的十几倍甚至几十倍。我之前做过粗略统计一个普通工具链任务平均要消耗 6000~12000 Token。GPT-4o-mini 的百万 Token 单价本就比满血版低一个数量级一次任务可能只是几厘钱而换成满血版就是动辄几美分。到了每天几千次调用的量级这个差距就是真金白银。1.2 小模型的工具调用能力以前不行现在真的行了很多人不敢用小模型做 Agent是吃过早期小模型的亏。早几年的小模型要么不支持 function calling要么经常把工具参数生成得乱七八糟比如把数字字段传成字符串或者漏传必填参数。但 GPT-4o-mini 这一代模型的工具调用能力已经有明显提升尤其在“结构化输出”这块官方是专门做了对齐训练的。我实测的感受是在工具数量不超过五六个、参数结构不特别复杂的场景下它调用工具的准确率和满血版基本拉不开差距。只有在三种情况下它会明显吃瘪长链条推理、复杂代码生成、需要精确理解超长文档。对这些场景我会单独路由到大模型而日常的信息查询、数据聚合、通知发送这类偏“接线员”的工作4o-mini 完全能胜任。1.3 什么场景我仍然建议换大模型说句公道话4o-mini 不是万能的。如果你要做的智能体是“数据分析师”需要连续做多步推理、频繁校验中间结果或者要处理几百页的 PDF 并做深度问答那该用大模型还是得用。我的做法是做了一个简单的路由层先让 4o-mini 判断任务的复杂度给出一个置信度低复杂度的直接自己处理高复杂度的转给大模型。这样既保住了成本又没牺牲关键场景的效果。2. 环境搭建版本不对后面全白费2.1 一套能直接跑起来的最小依赖清单LangChain 生态的版本迭代速度在这两年堪称“一天一个样”网上大量教程的代码其实已经过期了。我建议新项目直接用下面的版本组合在写这篇文章时这套组合我是跑稳定了的pip install langchain0.2 pip install langchain-openai0.1 pip install langchain-core0.2 pip install openai1.30注意不要一股脑安装langchain[all]里面的langchain-community包含了大量第三方集成包版本兼容性特别容易出问题。我的习惯是只需要什么就装什么最小依赖原则能帮你省掉很多莫名其妙的报错。2.2 新版 Agent API 和老教程的差别如果你翻过早期的 LangChain 教程大概率见过initialize_agent、ZeroShotAgent、AgentExecutor这些名字。坦白说我刚接触时照着半年前的教程写一运行就报initialize_agent已弃用当时整个人都有点懵。LangChain 0.1 之后主推的是底层基于原生工具调用协议的create_tool_calling_agent配合AgentExecutor使用。这个组合不再需要手写 ReAct 格式的 prompt也不需要自己解析“Action: xxx”这种文本因为模型原生支持工具调用返回的是结构化指令。2.3 环境变量与密钥管理的几个习惯密钥千万别写死在代码里。我之前踩过一次坑在 Jupyter Notebook 里直接硬编码了 API Key结果不小心把 notebook 分享出去虽然及时发现没有造成实际损失但那种后背发凉的感觉到现在还记得。推荐在项目根目录建一个.env文件OPENAI_API_KEYsk-你的密钥然后在代码开头统一加载from dotenv import load_dotenv load_dotenv()另外一个容易被忽略的细节是如果公司或团队有统一的 API 网关需要拼接 base_url那么用ChatOpenAI(base_url...)传入网关地址即可模型名仍然写gpt-4o-mini。这个我在接入内部网关时亲测有效。3. 构筑第一个智能体从对话助手到会调用工具的 Agent3.1 三步搭起最小可运行示例代码不用一开始就设计得很复杂。我的建议是先用一个“最小可运行”的骨架把链路跑通再逐步加工具、加记忆。下面这套代码我每次开新项目都会从备份中复制过来已经帮我省了不少时间import os from dotenv import load_dotenv load_dotenv() from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder llm ChatOpenAI( modelgpt-4o-mini, temperature0, max_retries3, ) # 第一步先定义一个最基础的工具后面再扩展 from langchain_core.tools import tool tool def add_numbers(a: float, b: float) - float: 两个数字相加返回和。当用户询问求和、总和时使用。 return a b tools [add_numbers] # 第二步组合提示词、模型和工具创建 Agent prompt ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的智能助手可以调用可用工具帮助用户完成任务。), (user, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) agent create_tool_calling_agent(llm, tools, prompt) # 第三步纳入 AgentExecutor 执行循环 executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, ) result executor.invoke({input: 请帮我计算 123.45 加 678.9 等于多少}) print(result[output])这套代码跑通之后你就拥有了一个“能调用工具”的智能体雏形。如果你只想快速验证链路甚至不用接任何外部 API那个add_numbers工具就够用了。3.2 拆解 create_tool_calling_agent 内部发生了什么理解了 Agent 原理排错时才不会两眼一抹黑。create_tool_calling_agent做的事情可以简化成四步把用户问题、系统提示词、工具定义一起发给模型如果模型认为需要工具会返回一个tool_calls结构化对象包含工具名和参数AgentExecutor收到这个对象去tools列表里找到对应函数执行把执行结果包装成ToolMessage追加到上下文把新的上下文再次发给模型直到模型不再请求调用工具返回自然语言答案。所以整个循环的本质是“模型做决策工具做执行环境做中转”。其中最容易出错的地方在第 2 步——模型返回的tool_calls格式是否完全匹配工具定义。这也是我在第 6 节要专门展开的坑。3.3 提示词里预留 agent_scratchpad 的原因MessagesPlaceholder(variable_nameagent_scratchpad)这是整个 Agent 工作流的“草稿区”。在循环执行期间模型每一次的思考内容和工具结果都会被塞到这个占位符里作为下一轮请求的上下文。如果你图省事把它删了模型就失去了中间推理的记录Agent 也就退化成普通问答了。所以这个占位符是必须保留的千万别动。4. 让 Agent 具备真实“行动力”工具集的定义、注册与容错4.1 用 tool 定义自己的工具工具是智能体的手和脚定义工具的质量直接决定了 Agent 的上限。我最常用的是tool装饰器配合类型标注和中文 docstring简单直接from langchain_core.tools import tool tool def get_city_weather(city: str) - str: 查询指定城市当天的天气情况包括温度、天气现象和风力。 城市参数请使用中文城市名例如“北京”“上海”。 当用户询问天气、气温、下雨与否时使用。 # 这里替换成真实天气 API 调用 # 如果 API 异常返回可供模型理解的错误说明 try: # resp requests.post(...) return 上海多云25摄氏度东南风3级 except Exception as e: return f天气查询失败{e} # 注意这里不抛异常 tool def send_notification(phone_number: str, content: str) - str: 给指定手机号发送短信通知。content 为短信正文长度不超过 70 个字。 当用户要求发送通知、提醒、短信时使用。 return f已成功向 {phone_number} 发送通知你可能会奇怪为什么要让工具内部自己try/except而不是让错误直接抛出来。因为 Agent 循环一旦遇到未捕获异常整个执行就中断了而如果工具返回的是一串错误说明模型反而能读懂然后决定换个参数重试或者直接告诉用户失败原因。这个习惯让我少接了无数次生产事故。4.2 工具描述是模型选择工具的“说明书”很多初学者把精力全放在函数实现上docstring 随便写一句话结果 Agent 老是选错工具或不选工具。这里要记住一个核心原则**模型不是读你的代码而是读你的描述。**同一个函数你写“获取天气”和写“当用户询问未来 24 小时天气、气温、降水概率、风力信息时使用城市请用中文名查询失败时返回说明”前者模型可能一头雾水后者模型基本每次都能选对。参数描述同样重要。如果某个参数比较特殊一定要在 docstring 里写清楚格式。比如日期参数“2025-06-01”还是“6月1日”模型不知道你的偏好它只能猜。我在某个数据查询工具上就吃过亏模型把“2025年6月1日”直接传给了 API结果后端解析失败白白浪费了一整轮工具调用。4.3 工具注册多了反而会干扰模型判断再说一个反直觉的经验工具不是越多越好。我在一个项目里一开始注册了 18 个工具结果 4o-mini 在“该用哪个”这件事上频繁犯错。后来把工具精简到 8 个核心工具把低频工具合并成“其他查询”的兜底工具准确率立刻上来了。因为模型每次都要在十几个工具描述里做判别描述之间互相干扰的概率很高。与其让模型纠结不如把相近功能的工具合并成一个内部用分支逻辑处理。5. 记忆与对话历史为什么智能体经常“失忆”怎么解决5.1 AgentExecutor 默认不带历史的原因新手最常见的困惑是我明明在同一个对话里问了“我叫小明”下一轮问“我叫什么名字”它居然不知道。原因很简单——AgentExecutor默认是无状态的每次invoke你只传了最新的{input: ...}它怎么会记得上一轮你说过什么这里要建立一个基本认知大模型本身没有记忆所谓的“记忆”是把对话历史拼接进上下文。你喂给它多少历史它就“记得”多少你不喂它就是失忆状态。5.2 给智能体接上多轮记忆解决方式其实不复杂。在 prompt 里增加一个chat_history占位符每次调用时把历史消息列表传给 Agentprompt ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的智能助手。), MessagesPlaceholder(variable_namechat_history), (user, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) history [] # 保存上一轮的 HumanMessage / AIMessage / ToolMessage # 每次调用前把 user 消息和 assistant 消息追加到 history history.append(HumanMessage(contentquestion)) result executor.invoke({ input: question, chat_history: history, }) history.append(AIMessage(contentresult[output]))需要注意消息类型的顺序HumanMessage、AIMessage、ToolMessage必须严格按照实际对话顺序追加一旦顺序乱了模型就很容易“精神错乱”。我自己在本地调试时曾经把两条HumanMessage连在一起结果模型以为用户在自问自答给出的回答牛头不对马嘴排查了很久才找到原因。5.3 历史变长后的 Token 控制滑动窗口与摘要记忆记忆是要花钱的。对话轮次越多历史占用的 Token 越多最终不仅账单上涨模型还可能被旧信息“淹没”反而忽略了当前问题。我用的方案是滑动窗口加摘要保留最近 6 轮完整消息保证短时上下文完整更早的历史每过 4 轮让 4o-mini 生成一句摘要只保留摘要文本每次请求约 400~600 token 的固定“记忆成本”不会随对话无限膨胀。实际实现时我在一个字典里维护两条字段summary和recent_messages。每次调用前组装成chat_history。跑了两周效果很稳定账单也保持在可接受范围内。6. 实测中的返工记录工具参数错位、循环调用和输出解析问题智能体开发一半以上的时间都在处理“模型不听话”的问题。下面这几类问题是我在真实项目里反复遇到的每一条都对应一次返工记录。6.1 模型把工具参数名“编”错了第一个经典事故是我定义了一个工具query_sales_data(start_date: str, end_date: str)用户问“看看 6 月到 7 月的销售数据”模型居然返回了{start_date: 6月, end_date: 7月}。后端当然解析失败模型拿到报错后又开始瞎猜来回三次才给出正确答案。后来我的解决办法是给参数加更严格的描述明确“日期格式请使用 YYYY-MM-DD”必要时用 Pydantic 模型做参数校验格式不对就返回友好错误在 system prompt 里明确写一句“调用工具前请检查参数格式是否与描述一致”。用pydantic定义工具参数结构还能顺带让模型看得更清楚尤其是多参数工具效果立竿见影。6.2 一个工具反复被调用就是不收敛第二种情况更气人模型第一次查天气拿到了结果但它好像“上了瘾”又调了第二次、第三次每次都传相同的参数。工具返回的都是一样的数据它还在循环里打转。这既浪费 Token 又影响体验。我试过把max_iterations从 5 调到 10结果只是让它多转几圈。真正有效的做法是两个在 system prompt 里加一句“如果工具已经返回所需信息请直接基于结果回答不要重复调用工具”把max_iterations设成 6并且在AgentExecutor中设置early_stopping_methodgenerate让它在超限后强制返回当前内容。这样改造之后循环调用的情况几乎绝迹了偶尔一次还能触发“兜底输出”。6.3 最终回答被代码块包住导致解析失败还有一个看着奇怪、实则常见的坑模型最终回答有时会带上 Markdown 代码块包裹比如json {answer: 上海今天多云}如果你的下游程序是按“纯文本”解析的这种返回就会判为失败。我一直以为这是 Prompt 的问题后来发现很可能是模型内部输出习惯决定的与 prompt 关系不大。 我的兜底做法是在拿到 result[output] 后做一次清理 python import re def clean_output(text: str) - str: pattern r^(?:json)?\s*(.*?)\s*$ match re.search(pattern, text, re.DOTALL) return match.group(1) if match else text.strip()虽然不优雅但确实能挡住大半这类问题。如果下游是 JSON 解析我还会再套一层json.loads的 try/except失败就原样返回文本。7. 性能与成本的平衡上下文压缩、并发调用与监控项目从 Demo 走到生产你会发现单次调用的“正确率”不再是唯一指标。吞吐量、延迟、成本稳定性才是真正让人头疼的部分。7.1 并发调用前先搞清楚速率限制我们曾并行跑了 20 个 Agent 任务结果前几个正常后面几个齐刷刷报错。一看日志原来是触发了每分钟请求数限制。OpenAI 的限流是按账号维度算的个人开发者的限额并不高。我的经验是在ChatOpenAI里显式设置max_retries5和request_timeout60让库自动处理瞬时限流并发控制在 5~8 个线程左右不要一上来就 20 并发如果并发量还要再往上就得对工具调用和 LLM 调用做分层限速比如用一个队列控制整体 QPS。7.2 给调用链路上盯上 Token 消耗成本不监控月底账单会教你做人。LangChain 的返回信息里其实带上了 Token 用量在result对象的response_metadata里usage result[response_metadata].get(token_usage, {}) total usage.get(total_tokens, 0)我在一个内部小工具里每次调用都累加total_tokens按小时写入日志再结合 4o-mini 的单价换算成本。有了数据之后你才知道哪类任务最烧钱哪些改造成本最值得做。7.3 一个值得长期使用的设计工具链记录生产环境里我还会额外打印/保存完整的工具调用轨迹包括每个工具名、入参、出参、耗时。某个任务出问题时没有这套轨迹根本没法定位是模型选错了工具还是工具本身报错了。其实就是给每次executor.invoke包一层日志装饰器把中间步骤记录下来。别嫌麻烦等出了线上问题你就会感谢当初的自己。8. 最后分享几个对我影响最大的习惯如果让我给刚开始做智能体开发的朋友提几个建议我会说这几条都是“真金白银”换来的经验第一永远先跑通一个最小的工具链再往上加功能。很多人一开始就想搭知识库、查数据库、发邮件、查日历一整套结果环境就折腾了两天。我自己到现在开新项目都还保留着那个只有add_numbers的最小代码骨架确认链路通了再扩展。第二保持 LangChain 版本更新节奏但不要盲目追新。新功能往往伴随新坑我在生产环境用的是固定版本号测试环境才会去试新接口。等社区把新版本踩稳了再平滑升级。第三不要迷信“模型什么都能做”。哪怕是 4o-mini 这样的模型也有明显的能力边界。一条准则把复杂的逻辑放在代码里把简单的判断留给模型。比如“该不该调用天气工具”可以让模型判断但“调完天气后要不要把数据写进数据库”这种流程则由代码控制。责任划分越清楚系统就越稳定。这套组合我已经稳定跑了相当长时间从成本、效果到排错效率都比较满意。希望这篇文章能帮你少走一些弯路把更多时间留给自己真正想解决的问题上。