1. 为什么你的 LangGraph Agent 总在“盲飞”
LangGraph 是把 LLM 调用、工具执行、条件路由串成有向图的框架，适合做多跳推理、ReAct Agent、多智能体协作这类复杂编排。但它的执行路径是非确定性的：同一个输入，条件边可能走 A 分支也可能走 B 分支，模型这次返回结构化 JSON、下次掺两句解释，工具调用可能成功也可能静默失败。传统 CRUD 那套print+try/except的调试方式，在这种场景下基本失效。
我见过最典型的翻车现场：一个退款 Agent 本地测了二十遍都正常，上线后用户反馈“它说退款成功了，但订单根本没动”。翻服务器日志只有一行INFO: graph finished。到底是路由节点判断错了意图？还是工具节点拿到了错误的订单号？还是模型在最终回复里产生了幻觉？没有链路追踪，你只能靠猜。而 LangGraph 的图结构意味着一次请求可能产生十几个嵌套调用，靠print打点，等于在迷宫里撒面包屑，撒完自己都找不到路。
LangSmith 是 LangChain 官方配套的可观测性平台，它天然理解 LangGraph 的语义：知道哪个 Run 对应哪个节点，能还原完整的 State 流转，记录每次 LLM 调用的 Prompt、Completion、Token 用量和耗时。接入之后，你的 Agent 从黑盒变成玻璃盒——每一次“心跳”都看得见。
这一篇聚焦第 8 章的可观测性与调试主题，交付三样东西：可复制的 LangSmith 接入配置骨架、TaoToken 统一 Key 与 API 通道的 settings.json / config.toml 示例、以及验证追踪数据上报与调试断点生效的具体动作。适合正在用 LangGraph 做 Agent、被“玄学调试”折磨过的开发者，也适合刚接触可观测性、想从第一天就把基础设施搭好的新手。
2. TaoToken 前置：统一 Key 与 API 通道配置
在接入 LangSmith 之前，先把模型调用的通道理顺。很多人的配置分散在四五个地方：OpenAI 的 Key 写在.env，Claude 的 Key 写在config.toml，本地测试又临时改环境变量。一旦要切换模型或者排查“到底是模型问题还是代码问题”，光找 Key 就耗掉半小时。
TaoToken 提供统一的 API 通道，Base URL 是https://taotoken.net/api，一个 Key 可以走通多家模型。这样你的 LangSmith Trace 里，模型调用来源是统一的，排查时不会因为“这个节点用的是哪家 Key”而分心。
先拿 Key。访问https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=langgraph_langsmith&utm_campaign=rewrite，登录后在控制台创建 API Key，格式类似sk-xxxxxxxx。这个 Key 同时用于模型调用和后续的配置验证。
接下来是配置文件。不同工具读取的路径不一样，我按最常见的三种给出示例，你按自己用的工具对号入座。
Claude Code / ClaudeCodeAnthropic 场景，配置文件通常在~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }Codex 场景，配置文件在~/.codex/auth.json：
{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "model": "gpt-4o" }通用 Python 项目场景，用.env管理：
TAOTOKEN_BASE_URL="https://taotoken.net/api" TAOTOKEN_API_KEY="sk-你的TaoToken密钥" TAOTOKEN_MODEL="gpt-4o"三件套记牢：Base URL、Key、Model ID。缺任何一个，调用都会失败。Base URL 统一填https://taotoken.net/api，不要带路径后缀；Key 从控制台复制，注意不要有多余空格；Model ID 按你实际要用的模型填。
配置好之后，先单独验证模型通道是否通，再叠加 LangSmith。这样出问题时能快速定位是通道问题还是追踪问题。验证命令：
curl https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}] }'返回里有choices字段就说明通道正常。如果返回 401，检查 Key 是否复制完整；如果返回local proxy failed，检查 Base URL 是否写成了带/v1的旧格式。
3. 可复制配置：LangSmith 接入骨架与 settings 片段
通道通了，现在叠加 LangSmith。接入的核心是环境变量，LangChain 和 LangGraph 在导入时会读取这些变量来决定是否初始化追踪器。所以加载顺序很关键：必须在所有 LangChain 相关导入之前执行。
先装依赖：
pip install langsmith langgraph langchain-openai python-dotenv然后建.env文件，把 LangSmith 和 TaoToken 的配置放一起：
# LangSmith 追踪配置 LANGCHAIN_TRACING_V2="true" LANGCHAIN_API_KEY="ls-你的LangSmith密钥" LANGCHAIN_PROJECT="langgraph-agent-dev-v1" # TaoToken 统一通道 TAOTOKEN_BASE_URL="https://taotoken.net/api" TAOTOKEN_API_KEY="sk-你的TaoToken密钥" TAOTOKEN_MODEL="gpt-4o"LangSmith 的 Key 从https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=langgraph_langsmith&utm_campaign=rewrite旁边的 LangSmith 入口获取，格式是ls-开头。LANGCHAIN_PROJECT建议用项目名-环境-版本的格式，别用test或aaa，否则后面在面板里过滤数据时会想砸键盘。
代码里加载顺序这样写：
from dotenv import load_dotenv load_dotenv() # 必须在 LangChain 导入之前 import os from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI from typing import TypedDict class State(TypedDict): msg: str llm = ChatOpenAI( base_url=os.getenv("TAOTOKEN_BASE_URL"), api_key=os.getenv("TAOTOKEN_API_KEY"), model=os.getenv("TAOTOKEN_MODEL"), ) def hello_node(state: State): resp = llm.invoke(state["msg"]) return {"msg": resp.content} builder = StateGraph(State) builder.add_node("hello", hello_node) builder.set_entry_point("hello") builder.add_edge("hello", END) graph = builder.compile() result = graph.invoke({"msg": "你好"}) print(result)如果你用的是 Claude Code 或 Codex 这类工具，LangSmith 的配置要写进对应的 settings 文件。Claude Code 的~/.claude/settings.json里追加：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514", "LANGCHAIN_TRACING_V2": "true", "LANGCHAIN_API_KEY": "ls-你的LangSmith密钥", "LANGCHAIN_PROJECT": "claude-code-agent-dev" } }Codex 的~/.codex/auth.json同理，把 LangSmith 的三个变量加进去。注意 JSON 里不能有注释，变量名大小写要完全一致。
配置写完后，跑一次上面的 hello 图。如果 LangSmith 面板里出现一条 Trace，说明链路通了。如果面板是空的，先别急着改代码，打开 Debug 日志看数据有没有发出去：
import logging logging.basicConfig(level=logging.DEBUG)控制台里如果有Sending request to LangSmith之类的记录，说明 SDK 在尝试上报，问题可能出在网络或 Key 上；如果完全没有记录，说明环境变量没被读到，检查load_dotenv()的位置。
4. 验证请求：追踪数据上报与调试断点生效
配置写完只是第一步，得验证两件事：追踪数据真的上报了，调试断点真的生效了。
验证追踪上报。跑完 hello 图后，打开 LangSmith 的 Project 页面。正常情况下你会看到一条 Trace，点进去是一棵树：根节点是 graph 调用，子节点是 hello 节点，再下面是 LLM 调用。每个节点都能看到 input、output、耗时、Token 用量。如果只看到根节点没有子节点，说明 LangGraph 的节点级追踪没生效，检查langgraph版本是否太旧。
再验证一下带工具调用的场景，因为工具调用是最容易出问题的地方：
from langchain_core.tools import tool @tool def search_order(order_id: str) -> str: """根据订单号查询订单状态""" if not order_id or len(order_id) < 6: raise ValueError(f"订单号格式错误：{order_id}") return f"订单 {order_id} 状态：已发货" tools = [search_order] llm_with_tools = llm.bind_tools(tools) def agent_node(state: State): resp = llm_with_tools.invoke(state["msg"]) return {"msg": resp} builder2 = StateGraph(State) builder2.add_node("agent", agent_node) builder2.set_entry_point("agent") builder2.add_edge("agent", END) graph2 = builder2.compile() graph2.invoke({"msg": "帮我查一下订单 123456"})跑完后在 LangSmith 里看这条 Trace，应该能看到 agent 节点下面挂着一个 tool 调用。点开 tool 节点，能看到传入的order_id参数和返回结果。如果工具抛了异常，LangSmith 会把这条 Run 标红，并在 Error 列表里按异常类型聚合。这就是“保留现场”的价值——线上偶发的工具报错，你能精确看到当时传了什么参数。
验证调试断点。LangSmith 的 Playground 功能允许你在 Trace 详情页直接重跑某一次调用。找到那条出问题的 Run，点进 Playground，用完全一致的上下文重新执行。你可以在这里改 Prompt、换模型、调 temperature，实时看效果，不用改代码。这相当于把生产环境的一次异常请求搬进了实验室。
还有一个实用技巧：给调用注入元数据，方便后续检索。
config = { "run_name": "order_query_test", "tags": ["dev", "v1.0", "order_module"], "metadata": { "user_id": "user_9527", "session_id": "sess_abc123", "env": "development" } } graph2.invoke({"msg": "帮我查一下订单 123456"}, config=config)注入之后，在 LangSmith 搜索框里直接搜tag:v1.0或metadata.user_id=user_9527，瞬间过滤出目标 Trace。团队多人开发时，这个习惯能省下大量翻页时间。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
接入过程中最容易卡住的几个报错，我按实际遇到的频率排一下。
401 Unauthorized。两种可能：TaoToken 的 Key 错了，或者 LangSmith 的 Key 错了。先分清是哪个环节报的 401。如果是模型调用报 401，检查TAOTOKEN_API_KEY是否复制完整、有没有多余空格；如果是 LangSmith 上报报 401，检查LANGCHAIN_API_KEY是不是ls-开头。有个隐蔽的坑：.env文件里 Key 后面跟了行内注释，比如LANGCHAIN_API_KEY=ls-xxx # 我的key，dotenv 会把注释也读进去，导致 Key 无效。Key 单独占一行，不要加注释。
local proxy failed。这个报错通常出现在 Base URL 配置错误时。TaoToken 的 Base URL 是https://taotoken.net/api，不要写成https://taotoken.net/api/v1或带其他路径。有些旧教程里的地址格式已经变了，照抄会失败。另外检查一下系统环境变量里有没有残留的HTTP_PROXY或HTTPS_PROXY，如果有，SDK 可能会走错误的网络路径。清理掉再试。
reading 'choices' 报错。典型症状是TypeError: Cannot read properties of undefined (reading 'choices')。这说明请求发出去了，但返回体里没有choices字段。常见原因有三个：一是 Model ID 写错了，比如把gpt-4o写成了gpt4o；二是请求体格式不对，比如messages字段拼写错误；三是通道返回了错误信息但被代码吞掉了。先用 curl 单独测一次模型调用，确认返回体结构，再对比代码里的解析逻辑。
OAuth 相关报错。如果你用的是 Claude Code 或 Codex 这类带 OAuth 流程的工具，可能会遇到OAuth token expired或invalid_grant。这类工具通常有两套认证：一套是工具本身的登录态，一套是模型 API 的 Key。LangSmith 的追踪不依赖 OAuth，它只读环境变量。所以遇到 OAuth 报错时，先确认工具本身的登录态是否有效，再确认ANTHROPIC_API_KEY或api_key是否配置正确。两者不要混在一起排查。
Trace 面板空白但代码不报错。最隐蔽的一种。代码跑完了，结果也对，但 LangSmith 里什么都没有。原因通常是load_dotenv()放在了 LangChain 导入之后。LangChain 的追踪器在模块导入时就初始化了，你后面再加载环境变量，它已经决定不追踪了。把load_dotenv()挪到所有 LangChain 导入之前，问题解决。
Project 数据混在一起。本地测试、CI 环境、生产环境的 Trace 全进了一个 Project。排查时自己的测试数据和线上真实流量混在一起，根本分不清。解决办法是每个环境用不同的LANGCHAIN_PROJECT值，比如agent-dev、agent-staging、agent-prod。在 CI 配置里通过环境变量覆盖，不要硬编码。
6. 语义一致 CTA：把通道和追踪一起用起来
配置和排障都走通之后，日常开发流程会变成这样：改 Prompt 或调参数之前，先在 LangSmith 的 Dataset 里跑一遍基线；改动后再跑一遍，对比分数变化。LangSmith 支持代码评估器和 LLM-as-a-Judge 两种方式，前者适合检查 JSON 合法性、字段完整性这类硬逻辑，后者适合判断回答相关性、礼貌度这类语义指标。
from langsmith.evaluation import evaluate def check_json_valid(run, example): import json try: json.loads(run.outputs["output"]) return {"key": "json_valid", "score": 1} except Exception: return {"key": "json_valid", "score": 0} evaluate( graph2.invoke, data="order-agent-dataset-v1", evaluators=[check_json_valid], )跑完评估后，LangSmith 会生成对比报告，告诉你哪些样本改善了、哪些退步了。如果整体分数掉超过 5%，坚决回滚，哪怕你觉得改得很牛。
模型通道这边，TaoToken 的统一 Key 让你在切换模型时不用改代码，只改TAOTOKEN_MODEL环境变量就行。LangSmith 的 Trace 里会记录每次调用用的哪个模型，对比不同模型在同一 Dataset 上的表现时，数据是干净的。
需要长期跑 Agent 任务、做批量评估的，可以看看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=langgraph_langsmith&utm_campaign=rewrite。想先验证模型对话效果的，走模型对话入口：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=langgraph_langsmith&utm_campaign=rewrite。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=langgraph_langsmith&utm_campaign=rewrite，里面有各语言的完整示例。
最后说个我踩过的坑：LangSmith 的免费额度对个人开发够用，但如果你在循环里疯狂调用，Trace 数量会暴涨。建议在开发阶段给graph.invoke加个recursion_limit，防止 Agent 在条件边里打转：
result = graph2.invoke( {"msg": "帮我查一下订单 123456"}, config={"recursion_limit": 15} )如果 LangSmith 里大量 Trace 因为recursion_limit被截断，说明你的条件边逻辑有问题，赶紧去修路由判断。这个限制既是保护钱包，也是帮你发现死循环的信号。
