1. 为什么 ChatGPT 那套问答思路套不住 LangChain Agent很多人第一次接触 LangChain Agent脑子里默认还是 ChatGPT 的交互模型用户发一句话模型回一段话结束。这个心智模型在单轮问答里没问题但一旦你开始写 Agent就会发现它根本不够用。ChatGPT 的对话是「输入—输出」的直线而 LangChain Agent 的运行是一条「思考—选工具—执行—观察—再思考」的循环链路。这两者的差别不是功能多少的差别而是架构范式的差别。我先把核心检索词摆出来LangChain Agent 是一个让大模型自主决定「要不要调用工具、调用哪个工具、传什么参数」的运行时框架它适合想把 LLM 接到真实业务动作查数据库、发请求、读写文件的开发者。ChatGPT 更像一个知识渊博但手脚被绑住的顾问它能告诉你「怎么查天气」但不会真的去调天气 APILangChain Agent 则是给这个顾问装上了手和脚还配了一本可以随时翻看的记事本。这个「记事本」就是记忆管理。ChatGPT 的记忆是平台侧黑盒你无法精细控制它记什么、忘什么、以什么结构存。LangChain Agent 的记忆是你自己定义的可以是对话历史缓冲可以是向量库检索也可以是结构化的事实表。工具调用链路和记忆管理正是拆解 Agent 底层机制的两把钥匙。理解这条链路对开发者来说有非常实际的价值。当你的 Agent 出现「该调工具时不调」「参数传错」「多轮之后忘了前面说过什么」这些问题时如果你脑子里只有 ChatGPT 的问答模型你会完全不知道从哪下手。但如果你清楚 Agent 的循环结构你就能定位到是提示词里的工具描述不清楚还是记忆没接上还是解析器把模型输出解析错了。下面我会带你从零跑通一条完整的 LangChain Agent 调用链路把工具注册、记忆挂载、执行验证一步步做出来再和 ChatGPT 的单轮问答做对照让你亲眼看到两者在运行时的分叉点在哪里。整个过程你都可以跟着敲代码是可直接复制的。2. TaoToken 前置准备给 Agent 接上可编程的模型入口在写 Agent 代码之前得先解决模型调用入口的问题。LangChain Agent 需要一个能通过 API 调用的模型而且这个模型要支持工具调用tool calling / function calling能力否则 Agent 的「选工具」这一步根本无从谈起。ChatGPT 网页版是给人用的你没法在代码里让它按你的格式返回工具调用意图你需要的是一个标准的、可编程的模型 API。我这边用的是 TaoToken 提供的模型接入服务它的 API 地址是 https://taotoken.net/api 兼容 OpenAI 的接口格式所以 LangChain 里可以直接用 ChatOpenAI 这个类只要把 base_url 指过去就行。这样做的好处是你不需要为了换模型去改 Agent 的整套代码工具注册、记忆管理这些逻辑完全不用动。先拿到 API Key。访问 https://taotoken.net/api-keys 登录后在控制台里创建一个新的 Key复制出来保存好。这个 Key 就是你后面代码里要填的凭证。注意不要把它硬编码进要提交到 Git 的代码里用环境变量或者 .env 文件管理。模型选择上Agent 场景建议选工具调用能力强的模型。你可以在模型对话页面 https://taotoken.net/models 里先手动试一下看看模型对「请调用工具查询天气」这类指令的响应是否符合预期。如果模型本身不擅长输出结构化的工具调用请求后面 Agent 的循环就会频繁卡壳。环境变量这样设置Linux/macOS 下export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:TAOTOKEN_API_KEY你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/apiPython 依赖方面LangChain 的包拆分比较细装这几个就够跑通本文的链路pip install langchain langchain-openai langchain-community这里有个容易踩的坑langchain 和 langchain-core 的版本要匹配如果你之前装过旧版本建议先pip install -U langchain langchain-openai升到较新的版本否则create_tool_calling_agent这类函数可能导入失败。我实测下来版本不匹配导致的 ImportError 是新手最常见的第一个拦路虎。准备好这些你就有了一个可编程、支持工具调用的模型入口。接下来进入正题把 Agent 的初始化配置和工具注册写出来。3. 可复制配置Agent 初始化与工具注册完整代码这一节是全文的技术核心我会把 Agent 的初始化、工具注册、记忆挂载三部分拆开讲最后拼成一个可运行的完整脚本。你直接复制就能跑。先看模型初始化。LangChain 里用 ChatOpenAI 指向 TaoToken 的兼容接口import os from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, # 换成你在模型列表里确认可用的模型 ID api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], temperature0, )temperature 设成 0 是为了让工具调用决策更稳定Agent 场景下你希望它按规则办事而不是发挥创意。接下来注册工具。LangChain 用tool装饰器把一个普通 Python 函数变成 Agent 可调用的工具。关键点是 docstring模型就是靠这段描述来判断「什么时候该用这个工具」的from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市的当前天气。输入应为城市名称例如 北京。 fake_db {北京: 晴12℃, 上海: 多云18℃, 深圳: 小雨24℃} return fake_db.get(city, f暂无 {city} 的天气数据) tool def calculate(expression: str) - str: 计算一个数学表达式例如 23 * 47 8。仅支持四则运算。 allowed set(0123456789-*/(). ) if not set(expression) allowed: return 表达式包含不允许的字符 return str(eval(expression))注意calculate里我做了字符白名单校验。Agent 调工具时参数是模型生成的你不能假设它一定生成安全的输入eval 直接裸用是有风险的。这个细节在 ChatGPT 单轮问答里你根本不用考虑因为模型只输出文本但 Agent 会真的执行代码安全边界必须自己守。然后是记忆管理。ChatGPT 的记忆是平台托管的你插不上手LangChain 里记忆是你自己挂的组件。最简单的是对话历史缓冲from langchain_core.chat_history import InMemoryChatMessageHistory memory InMemoryChatMessageHistory()生产环境你会换成基于 Redis 或数据库的实现但接口是一样的。记忆的作用是在每一轮把历史消息拼进提示词让模型「记得」之前说过什么。最后把三者组装成 Agentfrom langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder prompt ChatPromptTemplate.from_messages([ (system, 你是一个会使用工具的助手。需要实时数据或计算时必须调用工具不要凭记忆回答。), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) tools [get_weather, calculate] agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools, verboseTrue)agent_scratchpad这个占位符是 Agent 循环的关键它承载「中间步骤」——模型第一次输出的工具调用意图、工具返回的结果都会被塞回这里再喂给模型做下一轮决策。ChatGPT 单轮问答没有这个概念因为它不需要「观察结果后再决定下一步」。如果你用配置文件管理可以写一个agent_config.json{ model: gpt-4o-mini, base_url: https://taotoken.net/api, temperature: 0, tools: [get_weather, calculate], memory: in_memory, max_iterations: 5 }max_iterations是防止 Agent 陷入死循环的保险丝后面排障会讲到它的作用。4. 验证请求亲手跑通一条完整调用链路配置写好了现在验证它到底跑不跑得通。这一步很重要因为 Agent 的失败往往是静默的——它可能不报错但就是不调工具直接编一个答案给你。先跑一个必然触发工具调用的请求result executor.invoke({input: 北京现在天气怎么样}) print(result[output])把 verbose 打开后你会在终端看到类似这样的中间过程 Entering new AgentExecutor chain... Invoking: get_weather with {city: 北京} 晴12℃ 北京现在天气晴朗气温 12℃。 Finished chain.这段输出就是 Agent 和 ChatGPT 分叉的地方。ChatGPT 收到「北京天气」会直接生成一段可能过时甚至编造的回答而 Agent 先输出一个结构化的工具调用请求get_weather(city北京)框架执行这个函数拿到真实结果再把结果喂回模型模型才生成最终自然语言回答。整条链路是「模型决策 → 框架执行 → 模型总结」中间有真实的外部动作发生。再验证多步调用。问一个需要先算再答的问题result executor.invoke({input: 帮我算一下 128 乘以 37 等于多少}) print(result[output])你会看到calculate被调用参数是128 * 37返回4736模型再把它组织成一句话。如果模型偷懒直接心算verbose 里就不会出现工具调用这时候你要回头检查工具 docstring 是否说清楚了「什么时候用」。接着验证记忆。连续两轮对话executor.invoke({input: 我叫小明记住这个名字}) result executor.invoke({input: 我叫什么}) print(result[output])这里要注意上面这个 executor 默认不带记忆第二轮它会答不上来。要让它记住你得把 memory 接进 prompt 的历史占位符或者用带 memory 的 Agent 构造方式。这个对比实验恰好说明了 ChatGPT 和 LangChain 的差异ChatGPT 的记忆是自动的、黑盒的LangChain 的记忆要你显式挂载但挂载之后你能完全控制它存什么、存多久、怎么检索。跑通这三组验证你就亲手走完了一条完整的 Agent 调用链路。接下来把常见的报错过一遍这些坑我基本都踩过。5. 本篇常见错排查401、local proxy failed 与解析异常Agent 跑不起来报错信息往往不直观。我把几个高频错误和对应解法列出来你对照着查。401 Unauthorized。这个最常见基本是 Key 的问题。检查三处环境变量TAOTOKEN_API_KEY是否真的被当前 shell 读到echo $TAOTOKEN_API_KEY验证Key 是否复制完整有没有多带空格或换行base_url 是否写成了https://taotoken.net/api而不是别的路径。注意 base_url 末尾不要多加/v1之类的后缀LangChain 的 OpenAI 兼容层会自己拼路径你多写一段就 404 或 401。local proxy failed / Connection error。这类报错通常是网络层的问题不是 Key 的问题。先确认你的机器能正常访问https://taotoken.net/api可以用 curl 测一下curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:hi}]}如果 curl 通而 Python 不通多半是 Python 环境里设了额外的代理变量检查HTTP_PROXY/HTTPS_PROXY是否指向了一个不可用的地址清掉再试。reading choices of undefined。这个报错说明代码在解析响应时响应体里没有choices字段。原因通常是模型 ID 写错了服务端返回了一个错误对象而不是正常的补全结果。回到模型列表确认你填的 model 名称是真实存在的。另一个可能是你把 base_url 写成了网页地址而不是 API 地址请求打到了 HTML 页面上返回的自然是网页而不是 JSON。Agent 不调用工具直接编答案。这个不报错但结果不对。排查顺序先看工具 docstring 是否清晰描述了使用场景模型靠它决策再看 system prompt 有没有明确要求「必须调用工具」最后确认你选的模型本身支持 tool calling有些轻量模型不支持会退化成纯文本输出。Agent 陷入循环反复调用同一个工具。这是max_iterations没设或设太大的问题。Agent 拿到工具结果后如果觉得「还不够」会再调一次理论上可能无限循环。把max_iterations设成 5 左右超过就强制停止并返回当前结果避免烧 token。OAuth / 认证相关报错。如果你在别的工具里见过 OAuth 报错注意 LangChain 直连 API 用的是 Bearer Token不涉及 OAuth 流程。如果你用的是 Claude Code 这类工具它的认证配置在~/.claude/settings.json或环境变量里和本文的 LangChain 配置是两套东西别混在一起改。用 Cline 接 MCP 时配置里要同时写全 Base URL、API Key、Model ID 三件套缺一个都会认证失败。把这几类错误过一遍你基本能独立定位 Agent 跑不通的原因了。6. 从跑通到用好把 Agent 接进真实工作流跑通一条链路只是起点。真正让 Agent 产生价值是把它接进你日常的重复性工作流里并且让记忆机制替你积累上下文。我在实际项目里发现Agent 好不好用八成取决于工具描述和记忆设计而不是模型本身。工具 docstring 写得含糊模型就乱调记忆结构设计得差多轮之后 Agent 就开始答非所问。这跟 ChatGPT 的体验逻辑完全相反——ChatGPT 你几乎不用调开箱即用LangChain Agent 你得持续打磨但打磨之后它能干 ChatGPT 干不了的活。如果你想把这套链路用到长期编码或 Agent 自动化场景可以了解一下 Coding Plan它面向的就是需要持续调用、批量任务的开发场景。验证模型能力的话模型对话页面可以先手动试。接入文档在 https://taotoken.net/doc 里配置细节和参数说明都在那。最后留一个实用技巧调试 Agent 时永远开着 verbose别嫌输出乱。那条中间步骤日志是你唯一能看清「模型到底想了什么、调了什么、拿到了什么」的窗口。等链路稳定了再关掉换成结构化日志落盘方便回溯线上问题。
