
1. 为什么 LangChain 1.x 的 Agent 值得你花 3 小时跑通如果你最近在搜「LangChain create_agent 怎么用」「LangChain 1.x Agent 实战」大概率会遇到两个卡点一是 1.x 把旧的AgentExecutor那套彻底换成了基于 LangGraph 的create_agent网上大量 0.x 教程直接失效二是模型 Key 分散在 OpenAI、Anthropic、Google 各家光配环境变量就能耗掉半天。这篇就解决这两件事。我会带你从零搭好 LangChain 1.x 环境用 TaoToken 统一 Key 接入模型通道然后跑通第一个能聊天、能自己决定调不调工具的 Agent。全程照着敲3 到 5 小时能出结果。先说清楚create_agent是什么。它是 LangChain 1.x 的核心入口函数签名大致是create_agent(model, tools, system_prompt)返回一个CompiledStateGraph对象——也就是一张有状态的图。你不再需要手动拼 Prompt 模板、不再需要AgentExecutorAgent 的「思考—调工具—再思考」循环由框架自动处理。适合谁适合已经会点 Python、想快速把大模型接进自己业务工具链的工程师尤其是做内部工具、数据查询、RAG 检索这类场景的人。我实测下来最容易劝退新手的不是代码而是环境。Python 版本不对、依赖装错、Key 配错、base_url 写错任何一个都能让你卡在第一步。所以下面我按「环境 → Key → 配置 → 跑通 → 排错」的顺序来每一步都给可复制的命令和配置。核心检索词先记住LangChain 1.x 环境搭建、create_agent 最小示例、TaoToken 统一 Key、LangGraph Agent 架构。这几个词贯穿全文你按它们去搜也能找到对应资料。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在写 Agent 之前先把模型通道搞定。传统做法是每个模型厂商注册一遍、拿一遍 Key、记一遍 base_url切换模型时改代码。TaoToken 的思路是给你一个统一的 API 通道和一个 Key模型 ID 通过参数区分这样你在 LangChain 里换模型只改一个字符串。先注册并拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到形如sk-xxxx的 Key 后先存好别直接写进代码提交到 Git。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数是纯粹的接口入口。在 LangChain 里我们用的是 OpenAI 兼容协议所以base_url要写成https://taotoken.net/api/v1api_key填你刚拿到的 Key。这里解释一下为什么用ChatOpenAI这个类来接。TaoToken 的接口兼容 OpenAI 的/v1/chat/completions协议而 LangChain 的langchain-openai包里的ChatOpenAI允许你自定义base_url所以只要把 base_url 指向 TaoToken就能用同一套代码调不同模型。模型 ID 用字符串区分比如你想用某个 Claude 系列模型就填对应的模型 ID想换成别的改字符串即可。如果你后面要做长期编码任务或者 Agent 工作流可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的开发场景。想先验证模型通不通可以用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接试。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数问题可以对照查。有一点要提醒TaoToken 是合规的 API 聚合通道不是让你绕过什么限制的工具它的价值在于统一管理和切换模型别把它理解成别的东西。每段我都自查过你放心跟着配。3. 可复制配置依赖安装与环境变量落地这一节全是能直接复制的命令和文件内容。先确认 Python 版本终端里跑python3 -V版本要 ≥ 3.10建议 3.11。如果版本不够用 uv 管理 Python 版本会更省心uv python list接着初始化项目并装依赖。我习惯用 uv速度快、虚拟环境自动管uv init langchain1x-agent cd langchain1x-agent uv add langchain langchain-openai python-dotenv装完后你会看到langchain、langchain-core、langchain-openai、langgraph这些包。注意 LangChain 1.x 的 Agent 架构依赖 LangGraph所以langgraph会被自动带上这是正常的。然后是环境变量。在项目根目录建一个.env文件内容如下# TaoToken 统一 Key 配置 TAOTOKEN_API_KEYsk-你的Key填这里 TAOTOKEN_BASE_URLhttps://taotoken.net/api/v1 TAOTOKEN_MODEL你的模型ID.env一定要加进.gitignore别提交。如果你不想用.env也可以临时在终端导出但只对当前会话有效export TAOTOKEN_API_KEYsk-你的Key填这里再给一份pyproject.toml的关键片段确认依赖版本区间版本号以你实际安装为准这里示意结构[project] name langchain1x-agent version 0.1.0 requires-python 3.10 dependencies [ langchain1.0, langchain-openai1.0, python-dotenv1.0, ]如果你用 VS Code建议装 Python 和 Pylance 插件把解释器指向.venv。这样create_agent、tool这些符号能自动补全写代码时少踩拼写坑。配置这块有个细节base_url结尾的/v1不能少。TaoToken 的 API 根是https://taotoken.net/apiOpenAI 兼容路径是/v1/chat/completions所以 LangChain 里要写全https://taotoken.net/api/v1。少写/v1会直接 404这是新手最常见的坑之一。4. 验证请求create_agent 最小示例跑通与结果核对现在写第一个 Agent。新建agent01.py整段复制先跑通再逐行理解from __future__ import annotations import os from dotenv import load_dotenv from langchain.agents import create_agent from langchain.tools import tool from langchain_openai import ChatOpenAI load_dotenv() API_KEY os.getenv(TAOTOKEN_API_KEY) BASE_URL os.getenv(TAOTOKEN_BASE_URL) MODEL_ID os.getenv(TAOTOKEN_MODEL) tool def get_current_weather(city: str) - str: 根据城市名返回当前天气信息示例工具数据写死 city city.lower() if beijing in city or 北京 in city: return 北京当前天气晴-4℃空气质量良。 if shanghai in city or 上海 in city: return 上海当前天气多云2℃有阵风。 return f{city} 当前天气信息暂不可用。 def main(): llm ChatOpenAI( modelMODEL_ID, base_urlBASE_URL, api_keyAPI_KEY, temperature0.2, ) tools [get_current_weather] agent create_agent( modelllm, toolstools, system_prompt( 你是一个乐于助人的中文 AI 助手。 当用户询问天气相关问题时优先调用相应工具。 ), ) user_input 帮我查一下北京的天气再用一句话建议我要不要带伞。 result agent.invoke({messages: [(user, user_input)]}) messages result.get(messages, []) if messages: print(【Agent 最终回答】) print(messages[-1].content) print(\n【工具调用轨迹】) step 0 for msg in messages: if msg.type ai and getattr(msg, tool_calls, None): for tc in msg.tool_calls: step 1 print(fStep {step}: 工具{tc.get(name)} 参数{tc.get(args)}) elif msg.type tool: print(f工具返回: {msg.content}) if step 0: print((本次未调用工具)) if __name__ __main__: main()运行uv run python agent01.py预期输出类似【Agent 最终回答】 北京当前晴天、-4℃建议不需要带伞但注意保暖。 【工具调用轨迹】 Step 1: 工具get_current_weather 参数{city: 北京} 工具返回: 北京当前天气晴-4℃空气质量良。看到这个结果说明三件事都成了模型通道通了、create_agent构建成功、Agent 自己决定调用了工具并把结果融进了回答。拆解一下关键点。ChatOpenAI是统一封装base_url指向 TaoTokenmodel填模型 ID换模型只改这一个字符串。tool装饰器把普通函数变成 Agent 能「看见」的工具函数签名和文档字符串会自动转成模型可理解的工具描述所以文档字符串一定要写清楚。create_agent返回的是CompiledStateGraph输入输出都是状态字典格式是{messages: [...]}消息类型有human、ai、tool三种。工具调用信息藏在 AI 消息的tool_calls属性里遍历消息历史就能还原整个决策过程。想验证模型通道本身通不通也可以去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接发一句话试试能回就说明 Key 和通道没问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth跑不通的时候别慌对照下面几个真实报错定位。401 Unauthorized。最常见。原因通常是 Key 没读到、Key 写错、或者.env没被load_dotenv()加载。先打印os.getenv(TAOTOKEN_API_KEY)看是不是None。如果是None检查.env是否在项目根目录、文件名是不是.env不是.env.txt。如果 Key 有值还 401去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 没过期、没被删。local proxy failed / connection error。这类报错一般是网络层问题不是代码问题。先确认base_url写的是https://taotoken.net/api/v1别多写斜杠也别少写/v1。然后用 curl 直接测通道curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY能返回模型列表说明通道正常问题在 LangChain 配置返回失败就检查 Key 和地址。reading choices / KeyError: choices。这个报错说明返回体里没有choices字段通常是模型 ID 写错了或者请求打到了非 OpenAI 兼容的路径。核对model参数是不是有效模型 IDbase_url是不是/api/v1结尾。模型 ID 可以在模型对话页面确认。OAuth / authentication 相关报错。如果你之前用过 Claude Code 或 Codex 的 OAuth 登录方式可能会残留旧的凭证配置导致请求走了错误的认证路径。检查环境变量里有没有冲突的OPENAI_API_KEY、ANTHROPIC_API_KEY之类清掉再跑。如果你在用 CC Switch、Cline MCP 或 Codex 的auth.json记住三件套必须齐全Base URL 填https://taotoken.net/api/v1、Key 填 TaoToken 的 Key、Model ID 填有效模型 ID缺一个都会认证失败。Agent 不调工具。不是报错但很常见。原因通常是system_prompt没引导、或者工具文档字符串写得太模糊。把文档字符串写具体比如「根据城市名返回当前天气」并在 system_prompt 里明确「天气问题优先调用工具」。消息类型判断出错。msg.type在 1.x 里是human/ai/tool别用旧版的msg.role。用getattr(msg, tool_calls, None)做安全判断避免属性不存在时报错。排错时如果拿不准参数格式翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照比瞎试快。6. 从跑通到能用下一步怎么接你的业务跑通最小示例只是起点。真正有价值的是把工具换成你自己的业务能力。tool装饰器可以包任何 Python 函数数据库查询、HTTP 请求、RAG 检索、内部接口调用都能变成 Agent 的工具。你只需要保证函数签名清晰、文档字符串准确模型就能自己决定什么时候调。想加第二个工具练手加个加法工具tool def add_numbers(a: float, b: float) - str: 返回两数之和 return str(a b)然后把tools [get_current_weather, add_numbers]输入改成「先算 12.5 7.3再告诉我上海天气」观察 Agent 是否在一次对话里依次调用两个工具。这是从「抄代码」到「自己改」的关键一步。多轮对话也不难invoke的输入是消息列表你把历史消息带上就行。状态字典里的messages会累积完整对话历史下一轮把它传回去即可。如果你要做长期编码或复杂 Agent 工作流Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更适合持续场景只是验证模型效果模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 最快要拿 Key 和管 Key去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入细节对照文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后说个我踩过的坑别把temperature设太高做工具调用0.1 到 0.3 之间比较稳太高会让模型在「调不调工具」上犹豫。还有工具函数里别做耗时太长的同步阻塞操作Agent 调用是串行的一个慢工具会拖垮整轮响应。把这两点记住你的第一个生产级 Agent 就稳了。