1. 从一段真实报错说起LangChain create_agent 到底解决什么问题如果你最近在搜 LangChain 快速入门、create_agent 怎么用、Claude 模型怎么接进智能体大概率已经踩过下面这个坑照着旧教程写initialize_agent结果 import 直接报ImportError: cannot import name initialize_agent或者跑起来提示AgentExecutor已被标记为 legacy。这不是你环境装错了而是 LangChain 在 1.x 之后把智能体入口收敛到了create_agent这一个函数上。create_agent是什么一句话它是 LangChain 里创建 ReAct 风格智能体的统一入口把「模型 工具 系统提示词 结构化输出 对话记忆」这几件事用一个函数串起来。能做什么你可以用它搭一个会自己决定调不调工具、调哪个工具、最后按你指定 schema 返回 JSON 的智能体。适合谁适合已经会写 Python、想从「调一次 chat 接口」进阶到「做一个能上线的 Agent 服务」的开发者。我试过用旧版AgentExecutor和新的create_agent各写一遍同样的天气查询逻辑后者代码量少了将近一半而且结构化输出和记忆是原生支持的不用自己拼output_parser。这篇就按「能直接复制跑通」的标准从依赖安装、Claude 接入、工具定义、结构化输出、多轮记忆一路写到排错中间所有模型调用都走 TaoToken 的统一通道你只需要一个 Key 就能切换模型。先说清楚整体路径装依赖 → 配 Key 和 Base URL → 写工具函数 → 用create_agent组装 →invoke验证 → 按报错排查。每一步都有可复制的代码块最后你会得到一个能多轮对话、能调工具、能返回结构化结果的智能体。2. 前置准备用 TaoToken 统一 Key 接入 Claude 模型在写create_agent之前得先解决模型从哪来的问题。LangChain 本身不提供模型它只是个编排框架真正干活的是背后的 Claude、GPT 这些大模型。传统做法是去 Anthropic 官网注册、拿 Key、配环境变量但如果你同时想试 Claude 和别的模型就得维护多套 Key 和多套 SDK 配置切换起来很烦。TaoToken 在这里的角色是「统一模型通道」它提供 OpenAI 兼容的 API 格式你拿一个 Key改一下 Base URL就能在 LangChain 里调用 Claude 系列模型。对create_agent来说模型只要符合 LangChain 的 chat model 接口就行所以接入方式非常直接。第一步去 TaoToken 控制台创建一个 API Key。地址是 https://taotoken.net/api-keys 登录后点新建复制那串sk-开头的字符串先存到安全的地方。第二步安装依赖。LangChain 的包拆得比较细智能体、模型、工具、记忆分别在不同包里建议一次性装全pip install -U langchain langchain-core langchain-anthropic langgraph这里解释一下每个包的作用langchain是主包create_agent从这里导入langchain-core提供消息、工具等基础抽象langchain-anthropic是 Claude 的官方集成包负责把 Anthropic 的接口适配成 LangChain 的 chat modellanggraph提供 checkpointer对话记忆的实现InMemorySaver就在里面。第三步配置环境变量。TaoToken 兼容 OpenAI 的调用方式所以最省事的做法是用langchain-openai的ChatOpenAI把base_url指向 TaoTokenexport TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你更想用 Anthropic 原生格式也可以装langchain-anthropic并用ChatAnthropic把base_url指向 TaoToken 的 Anthropic 兼容端点。两种方式在create_agent里用法完全一样传进去的都是一个 chat model 实例。这里有个容易忽略的点create_agent的model参数既接受字符串比如claude-sonnet-4-5-20250929也接受已经初始化好的 model 对象。字符串形式会走 LangChain 的默认推断逻辑需要你环境里有对应的 Key而传对象的形式更可控Base URL、超时、温度都能自己定。生产环境我建议用对象形式下面配置章节会给出完整写法。3. 可复制配置create_agent 的模型、工具与结构化输出片段这一节是全文的核心给你一份能直接落地的配置。先看模型初始化用ChatOpenAI指向 TaoTokenimport os from langchain_openai import ChatOpenAI model ChatOpenAI( modelclaude-sonnet-4-5-20250929, api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], temperature0, timeout30, max_retries2, )参数说明model填你要用的模型 IDTaoToken 支持的 Claude 系列都可以在这里替换base_url必须是https://taotoken.net/api注意不要带末尾斜杠temperature0让输出尽量确定适合结构化场景timeout和max_retries是生产必备防止单次请求卡死拖垮整个服务。接下来定义工具。create_agent的工具就是普通 Python 函数加tool装饰器函数的 docstring 会被当作工具描述传给模型所以一定要写清楚用途from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市的天气。参数 city 是城市名例如 Beijing。 return f{city} 今天晴气温 22 度。 tool def get_user_location(user_id: str) - str: 根据用户 ID 查询用户所在城市。参数 user_id 是用户唯一标识。 return Beijing if user_id 1 else Shanghai然后是结构化输出。生产环境里你往往不希望模型返回一大段自然语言而是希望它按固定字段返回方便入库或给前端渲染。create_agent支持用 Pydantic 模型或 dataclass 定义response_formatfrom pydantic import BaseModel, Field class WeatherReport(BaseModel): 智能体的结构化输出格式。 summary: str Field(description一句话天气总结) city: str Field(description城市名) temperature: int Field(description摄氏温度整数)最后用create_agent把上面这些组装起来并加上对话记忆from langchain.agents import create_agent from langgraph.checkpoint.memory import InMemorySaver agent create_agent( modelmodel, tools[get_weather, get_user_location], system_prompt你是一个天气助手。用户问天气时如果没给城市先用 get_user_location 查用户所在城市再调 get_weather。, response_formatWeatherReport, checkpointerInMemorySaver(), )对照一下参数model是上面初始化的对象tools是工具列表system_prompt定义行为规则这里明确告诉模型「没给城市就先查用户位置」这是让工具调用变可靠的关键response_format绑定结构化 schemacheckpointer提供多轮记忆InMemorySaver适合本地测试生产可换成基于数据库的实现。如果你用 Claude Code 或 Cline 这类工具辅助开发可以把上面的 Base URL、Key、Model ID 三件套填进它们的模型配置里让编辑器里的补全也走同一条通道省得来回切账号。模型对话入口在 https://taotoken.net/models 接入文档在 https://taotoken.net/doc 需要长期跑 Agent 任务的话可以看 Coding Planhttps://taotoken.net/coding-plan 。4. 验证请求跑通第一个可上线的智能体并检查结果配置写完接下来验证它真的能跑。先写一个最小调用确认模型通道是通的config {configurable: {thread_id: user-1-session-1}} result agent.invoke( {messages: [{role: user, content: 今天天气怎么样}]}, configconfig, ) print(result[structured_response])预期输出是一个WeatherReport对象类似summary北京今天晴气温 22 度 cityBeijing temperature22。注意这里用户没指定城市智能体应该先调get_user_location再调get_weather最后按 schema 返回。如果你打印result[messages]能看到完整的工具调用轨迹包括模型决定调哪个工具、传了什么参数、工具返回了什么。再验证多轮记忆。用同一个thread_id再发一条result2 agent.invoke( {messages: [{role: user, content: 那明天呢}]}, configconfig, ) print(result2[structured_response])因为thread_id相同智能体记得上一轮聊的是北京天气所以「明天呢」能被正确理解为「北京明天天气」。如果你换一个thread_id它就会当成全新会话这就是记忆隔离。验证结构化输出是否稳定可以连续跑五次同样的请求观察temperature字段是不是整数、city是不是字符串。如果偶尔返回自然语言而不是结构化对象通常是response_format没生效或模型不支持检查一下create_agent的版本和模型 ID。最后做一个「上线前检查」把InMemorySaver换成持久化 checkpointer把timeout调小到 10 秒加一层 try/except 捕获模型调用异常。这三步做完这个智能体就具备基本的线上可用性了。需要看更多模型和参数组合的话模型对话页面可以直接试https://taotoken.net/models 。5. 常见报错排查401、local proxy failed 与 reading choices跑create_agent的过程中报错基本集中在模型通道和依赖版本两块。下面按真实遇到的错误逐条对照。报错一AuthenticationError: 401 - Invalid API key。这是 Key 没配对。检查三处环境变量TAOTOKEN_API_KEY是否真的导出到了当前 shellecho $TAOTOKEN_API_KEY看一下Key 有没有多余空格或换行base_url是不是写成了https://taotoken.net/api/末尾斜杠有时会导致路径拼接错误。如果都没问题去控制台确认这个 Key 还有效、额度没耗尽。报错二APIConnectionError: local proxy failed或连接超时。这类错误通常是网络层的问题不是 Key 的问题。先确认base_url拼写正确再检查本机是否有奇怪的网络配置拦截了请求。如果你在公司内网可能需要确认出口策略允许访问taotoken.net。另外timeout设太短也会表现为连接失败建议先设 30 秒排除。报错三KeyError: choices或reading choices。这个错误说明返回的 JSON 结构里没有choices字段常见原因是base_url指向了一个不兼容 OpenAI 格式的端点或者模型 ID 写错了导致服务端返回了错误对象。解决方法是先用 curl 直接打一次接口看返回结构curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5-20250929,messages:[{role:user,content:hi}]}如果 curl 返回正常但 LangChain 报错那就是包版本问题升级langchain-openai到最新。报错四ImportError: cannot import name create_agent。说明langchain版本太旧。create_agent是较新版本才有的入口执行pip install -U langchain升级。如果升级后还报错检查是不是有多个 Python 环境装到了另一个解释器里。报错五工具没被调用模型直接编答案。这不是异常是行为问题。原因通常是system_prompt没写清楚工具使用规则或者工具 docstring 太模糊。把「什么时候必须调工具」写进 system promptdocstring 里把参数含义写全模型调用工具的准确率会明显提升。报错六结构化输出偶尔失败。如果structured_response是 None先确认response_format传的是 Pydantic 模型而不是实例再确认模型本身支持结构化输出。部分模型对 schema 的遵循度不同必要时在 system prompt 里补一句「必须严格按给定字段返回」。排查顺序建议固定为先 curl 验证通道 → 再验证 Key → 再看 LangChain 版本 → 最后看 prompt 和 schema。这样能快速定位是通道问题还是代码问题。接入相关的完整说明在 https://taotoken.net/doc Key 管理在 https://taotoken.net/api-keys 。6. 把智能体接到真实业务从本地跑通到长期运行本地跑通只是第一步真正上线还要考虑几件事。第一是记忆持久化InMemorySaver进程一重启就没了生产环境要换成基于数据库或 Redis 的 checkpointerLangGraph 提供了对应实现接口和InMemorySaver一致替换成本很低。第二是错误处理模型调用可能超时、可能限流给invoke包一层重试和降级逻辑别让单次失败影响整个请求。第三是成本控制max_tokens和temperature按场景调结构化输出场景温度设 0 就够了。如果你打算把这个智能体做成长期运行的服务比如每天定时跑任务、或者作为后端 API 持续接收请求可以了解一下 Coding Planhttps://taotoken.net/coding-plan 它更适合这种持续调用的场景。日常调试和验证模型效果直接用模型对话页面最快https://taotoken.net/models 。需要新建或轮换 Key 的时候去控制台https://taotoken.net/api-keys 。最后留一个实用技巧把create_agent的组装逻辑封装成一个build_agent()函数模型、工具、prompt 都作为参数传入。这样你在测试环境用InMemorySaver、生产环境用数据库 checkpointer只改一个参数不用动业务代码。智能体这东西配置和业务逻辑分离得越干净后面迭代越省心。