说实话看到这个报错我第一反应不是代码问题而是版本问题。ImportError: cannot import name create_tool_calling_agent from langchain.agents这句话几乎每天都在LangChain社区里出现而且问的人十有八九都是照着网上某篇旧教程敲的代码。你手里拿的标题、代码片段可能没错错的是你的langchain版本和你参考的资料版本对不上。这篇内容我会把这件事从头讲透这行导入到底想干什么、为什么报错、不同版本该怎么处理最后再带你用正确姿势跑通一个能用的Tool Calling Agent。无论你是刚入门LangChain还是被这个报错卡了半天按着后面的步骤走一遍基本能解决。1. 报错是怎么发生的从一行导入说起1.1 先看这行代码很多人在写Agent相关功能时第一行代码往往是这样的from langchain.agents import create_tool_calling_agent然后紧接着Python解释器就甩给你一个刺眼的红字ImportError: cannot import name create_tool_calling_agent from langchain.agents这个报错翻译成大白话就是langchain.agents这个模块里压根儿找不到create_tool_calling_agent这个名字。Python本身并不关心你有没有写错它只认模块里实际存在的名字。所以问题就来了是它不存在还是你找错了地方又或者你手里的模块版本跟教程不是同一个时代。1.2 报错背后的版本逻辑create_tool_calling_agent是LangChain在引入Tool Calling能力时提供的一个便捷构造方法作用是帮你把大模型、工具列表包装成一个能自主决定“调用哪个工具、传什么参数”的Agent对象。这个API不是从一开始就存在的它的出现和演进都跟LangChain的版本历史强绑定。大致路线是这样的LangChain早期0.0.x时代主要推的是initialize_agent和create_react_agent这种老式构造方式。后来模型生态里出现了OpenAI的Function Calling、Anthropic的Tool Use这类原生工具调用能力LangChain才在0.1.x版本里逐步引入了create_tool_calling_agent。所以如果你用的LangChain是0.0.x没有这个方法太正常了。到了0.2.x和0.3.xcreate_tool_calling_agent都还保留在langchain.agents里大部分老教程也是以此为准。但LangChain的迭代速度相当快API结构一直在调整加上很多人环境里装了多个版本的包互相覆盖这个报错就会以各种姿势出现。1.3 为什么网上教程会让它越来越乱我在网上搜这个问题时经常能看到两种极端的答案一种是“你版本太低了升级就好”另一种是“这个API在新版本已经删了换用别的写法”。这两种说法单独看都没错但放在一起就让人懵到底升还是不升升到哪个版本问题的核心在于网上教程的发布时间和对应版本往往没有明确标注很多人复制粘贴的是半年前的代码但环境里已经装上了最新版另一些人正好相反用的是老环境却抄了新教程。一来二去ImportError就成了LangChain入门的一道大坎。所以在动手改代码之前你真正需要做的第一件事不是改导入语句而是搞清楚自己环境里装的到底是什么版本。2. 对症下药三种情况对应三种解法2.1 情况A你的LangChain太老0.0.x如果你是通过pip show langchain查出来版本是类似0.0.356这种那事情就很简单你手里的LangChain太老了那个年代还没有Tool Calling这种概念。网上很多讲create_tool_calling_agent的教程都是基于0.1之后的版本写的你用0.0.x自然导不进来。解决办法也很直白升级LangChain到当前稳定版。pip install --upgrade langchain langchain-community langchain-openai升级之后原有的create_tool_calling_agent就有可能出现了。但这里我要多嘴一句升级不是无脑执行就完事它可能带来新的变化。比如0.2版本把很多模型集成拆成了独立包原来你可能只装了langchain现在需要额外装langchain-openai才能用ChatOpenAI。所以升级后如果报别的错别慌接着看后面的内容。2.2 情况B你的LangChain太新或API被迁移如果你查出来版本是0.4.x甚至更高的预览版那情况又不同了。LangChain官方在持续推进Agent API的重构新一代的Agent构建方式越来越依赖LangGraph大量辅助函数正在被逐步调整、迁移或者替换。虽然create_tool_calling_agent在很长一段时间内都是langchain.agents的正式导出成员但如果你遇到它突然消失的情况可以先试试看这个API是不是被移到更细分的子模块里比如# 尝试直接从agents模块的深层路径导入 from langchain.agents import create_tool_calling_agent如果确认不行请务必查一下你那个版本对应的官方迁移文档别硬猜。这里有一个比较通用的操作python -c import langchain; print(langchain.__version__)拿到了精确版本号之后去LangChain的GitHub Release页面看该版本的改动说明搜索create_tool_calling_agent看官方写的是被移除、改名还是替换。以官方文档为准比任何二手教程都靠谱。2.3 情况C环境依赖被搞乱还有一种很常见但很容易被忽略的情况你的环境里同时存在多个LangChain相关包版本互相覆盖。比如langchain是0.3但langchain-experimental还是0.0.x或者本地同时存在langchain和langchain-core版本不匹配。这时候Python解释器可能从错误的位置加载模块导致明明“应该存在”的名字却导入失败。尤其是很多小白喜欢用pip install langchain把所有东西一次性装完后来又为了跑某个Demo手动装了各种依赖最后环境成了一锅粥。如果你发现排查版本后依然报错不妨干净地重建一个虚拟环境只装必要依赖一了百了。conda create -n langchain-test python3.11 -y conda activate langchain-test pip install langchain langchain-openai langchain-community装完之后再跑一次导入大概率就正常了。一个干净的环境能帮你省下大量排查时间这个经验我反复说过很多次但每次都有人不听。3. 实操用正确姿势搭一个Tool Calling Agent3.1 环境准备与版本锁定既然要跑通我们就不碰运气了。我建议你干脆锁定一个已知稳定的组合避免“今天能跑明天不能跑”的玄学问题。目前我在生产环境里用得较稳的组合是pip install langchain0.3.7 langchain-core0.3.7 langchain-openai0.2.8为什么要锁定版本因为LangChain的API变化太频繁今天能用不代表明天能用。锁定版本意味着你可复现别人也能照着你写的教程跑通。这一点对于学习阶段的人来说尤其重要。装完验证一下python -c from langchain.agents import create_tool_calling_agent; print(ok)如果输出ok说明环境没问题可以直接进入下一步如果还报错那你可能命中了情况C请先用干净的虚拟环境再试一次。3.2 定义工具与核心代码下面这段代码是我平时演示Tool Calling Agent最常用的一段不复杂但足够说明问题。我们先定义一个加法工具然后让Agent反复调用它from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_openai import ChatOpenAI from langchain_core.tools import tool # 1. 定义工具 tool def add_numbers(a: int, b: int) - int: 把两个整数加起来并返回结果。 return a b # 2. 定义模型 llm ChatOpenAI( modelgpt-4o, temperature0, ) # 3. 定义提示词模板 from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一个只能使用加法工具的助手。), (human, {input}), (placeholder, {agent_scratchpad}), ]) # 4. 组装Agent tools [add_numbers] agent create_tool_calling_agent(llm, tools, promptprompt) # 5. 用AgentExecutor包一层 executor AgentExecutor( agentagent, toolstools, verboseTrue, ) # 6. 运行 result executor.invoke({input: 请计算 12 34 等于多少}) print(result[output])这里有个关键点create_tool_calling_agent的签名是(llm, tools, prompt)不是(llm, tools)。很多教程里的旧代码只传了两个参数在新版本里就会报TypeError: missing 1 required positional argument: prompt。如果你碰到了这种错复制我上面完整的函数签名就可以了。3.3 运行验证如果你用的是OpenAI的模型记得先设置环境变量export OPENAI_API_KEYsk-你的key然后运行脚本。verboseTrue会打印出Agent的思考过程你能看到类似“调用工具add_numbers参数a12b34”的日志。最后输出应该是46。从实操角度说我第一次跑通这个流程时最大的感受是LangChain这层封装简化了很多东西但也把底层逻辑藏得比较深。你看agent_scratchpad这个占位符它表面上只是一个空占位实际上内部会被AgentExecutor填充过往的工具调用记录让模型能记住前面做过什么。如果提示词里漏了它Tool Calling Agent在多次调用工具时就会“失忆”表现出来就是只调一次工具就乱答。所以在照抄代码时不要只关注导入那几行placeholder这一行同样是整个机制正常运转的关键。4. 同族错误速查与排查心得4.1 常见ImportError速查表除了create_tool_calling_agentLangChain相关项目里还有一批长得非常相似的报错光看结构就让人头疼。我把实际遇到过的几条整理成表格方便你对照排查报错信息常见原因推荐处理cannot import name create_tool_calling_agent from langchain.agentsLangChain版本过旧或API迁移升级到0.2或查迁移文档cannot import name AgentExecutor from langchain.agents版本过新AgentExecutor的位置调整尝试从langchain.agents导入或改用langgraphcannot import name tool from langchain.agents工具装饰器应来自langchain_core.tools改为from langchain_core.tools import toolImportError: numpy.core.multiarray failed to importnumpy与相关包版本不匹配重建环境统一升级numpy或降低到兼容版本DLL load failed while importing ...缺少底层动态库常见于Windows上PyQt5或部分二进制包修复系统运行库或改用conda安装相关包这里想单独说一下后面两类numpy.core.multiarray和DLL load failed。它们虽然跟create_tool_calling_agent不是同一个目录下的错误但在实际排查中经常一起出现因为它们的本质都是“依赖包版本或安装环境出了问题”。比如你同时装了langchain和某个老版本的numpy那LangChain底层很多依赖numpy的组件都可能发生导入异常。此时不要盯着LangChain改来改去直接用干净的虚拟环境把包统一装一遍问题往往就消失了。4.2 独家排查技巧先查名字再查版本最后查环境很多人在报错出现后的第一反应是去搜索引擎复制粘贴错误消息这没错但效率不高。我更推荐按照下面这个固定顺序来排查第一步确认当前环境的LangChain版本。用pip show langchain如果版本号显示为0.0.x停止浏览教程直接升级不需要再找其他原因。第二步确认API在对应版本中的合法位置。最简单的方法是打开Python交互式解释器用dir()查看模块成员import langchain.agents print([name for name in dir(langchain.agents) if tool in name.lower()])这样你能直接看到当前环境里到底有哪些可用名字比对着网上文章猜准得多。如果没有看到create_tool_calling_agent那就在这个环境里继续查create_agent、create_react_agent等名字总会找到替代方案。第三步确认环境是否被污染。如果你在dir()里看到了名字但import时仍然报错那极有可能是模块被重复加载、不同安装路径下的langchain混在一起。建议用下面命令检查实际加载路径python -c import langchain.agents; print(langchain.agents.__file__)如果发现一个很奇怪的路径比如site-packages裸目录下还有个langchain文件夹那说明环境里有残留的手动拷贝文件把多余的卸载干净就好。4.3 聊两句我的实际体会这个报错我在过去一年里至少帮人看了几十次坦白说绝大多数都不是什么高深问题就是版本错配。但为什么它如此折磨人因为LangChain的文档变化速度赶不上代码迭代速度而网上的教程又有很多是“历史遗留物”。我的经验是遇到这类导入错误先别急着怀疑自己的代码水平先怀疑环境。把版本对齐、环境搞干净80%的问题都会自己消失。另外如果你打算长期用LangChain做项目建议养成两个习惯第一为每个项目单独创建虚拟环境不要全局混装第二在一切能跑的时候立刻把依赖版本导出记录一份哪怕只是写在项目的requirements.txt里。这两个习惯看起来不起眼但在版本快速迭代的生态里能帮你省下大把排查时间。最后再说一点如果你用的模型是国产开源模型或者是本地部署的量化模型create_tool_calling_agent对模型的工具调用能力是有要求的——模型本身必须经过工具调用的训练否则即使代码导入成功运行时也可能完全不会触发工具。这种情况下你需要先确认模型是否支持Tool Calling再考虑是不是导入错误。别把模型能力问题当成代码问题来排查那才是真正的南辕北辙。
