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 model；langgraph提供 checkpointer（对话记忆）的实现，InMemorySaver就在里面。
第三步，配置环境变量。TaoToken 兼容 OpenAI 的调用方式，所以最省事的做法是用langchain-openai的ChatOpenAI，把base_url指向 TaoToken：
export TAOTOKEN_API_KEY="sk-你的Key" export TAOTOKEN_BASE_URL="https://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指向 TaoToken：
import os from langchain_openai import ChatOpenAI model = ChatOpenAI( model="claude-sonnet-4-5-20250929", api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], temperature=0, timeout=30, max_retries=2, )参数说明：model填你要用的模型 ID，TaoToken 支持的 Claude 系列都可以在这里替换；base_url必须是https://taotoken.net/api，注意不要带末尾斜杠；temperature=0让输出尽量确定，适合结构化场景；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_format：
from 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( model=model, tools=[get_weather, get_user_location], system_prompt="你是一个天气助手。用户问天气时，如果没给城市，先用 get_user_location 查用户所在城市，再调 get_weather。", response_format=WeatherReport, checkpointer=InMemorySaver(), )对照一下参数：model是上面初始化的对象；tools是工具列表；system_prompt定义行为规则，这里明确告诉模型「没给城市就先查用户位置」，这是让工具调用变可靠的关键；response_format绑定结构化 schema；checkpointer提供多轮记忆，InMemorySaver适合本地测试，生产可换成基于数据库的实现。
如果你用 Claude Code 或 Cline 这类工具辅助开发，可以把上面的 Base URL、Key、Model ID 三件套填进它们的模型配置里，让编辑器里的补全也走同一条通道，省得来回切账号。模型对话入口在 https://taotoken.net/models ，接入文档在 https://taotoken.net/doc ，需要长期跑 Agent 任务的话可以看 Coding Plan：https://taotoken.net/coding-plan 。
4. 验证请求：跑通第一个可上线的智能体并检查结果
配置写完，接下来验证它真的能跑。先写一个最小调用，确认模型通道是通的：
config = {"configurable": {"thread_id": "user-1-session-1"}} result = agent.invoke( {"messages": [{"role": "user", "content": "今天天气怎么样？"}]}, config=config, ) print(result["structured_response"])预期输出是一个WeatherReport对象，类似summary='北京今天晴，气温 22 度' city='Beijing' temperature=22。注意这里用户没指定城市，智能体应该先调get_user_location，再调get_weather，最后按 schema 返回。如果你打印result["messages"]，能看到完整的工具调用轨迹，包括模型决定调哪个工具、传了什么参数、工具返回了什么。
再验证多轮记忆。用同一个thread_id再发一条：
result2 = agent.invoke( {"messages": [{"role": "user", "content": "那明天呢？"}]}, config=config, ) 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是否真的导出到了当前 shell（echo $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 prompt，docstring 里把参数含义写全，模型调用工具的准确率会明显提升。
报错六：结构化输出偶尔失败。如果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 的 checkpointer，LangGraph 提供了对应实现，接口和InMemorySaver一致，替换成本很低。第二是错误处理，模型调用可能超时、可能限流，给invoke包一层重试和降级逻辑，别让单次失败影响整个请求。第三是成本控制，max_tokens和temperature按场景调，结构化输出场景温度设 0 就够了。
如果你打算把这个智能体做成长期运行的服务，比如每天定时跑任务、或者作为后端 API 持续接收请求，可以了解一下 Coding Plan：https://taotoken.net/coding-plan ，它更适合这种持续调用的场景。日常调试和验证模型效果，直接用模型对话页面最快：https://taotoken.net/models 。需要新建或轮换 Key 的时候去控制台：https://taotoken.net/api-keys 。
最后留一个实用技巧：把create_agent的组装逻辑封装成一个build_agent()函数，模型、工具、prompt 都作为参数传入。这样你在测试环境用InMemorySaver、生产环境用数据库 checkpointer，只改一个参数，不用动业务代码。智能体这东西，配置和业务逻辑分离得越干净，后面迭代越省心。
