1. 为什么你的 LangGraph Agent 总在“盲飞”LangGraph 是把 LLM 调用、工具执行、条件路由串成有向图的框架适合做多跳推理、ReAct Agent、多智能体协作这类复杂编排。但它的执行路径是非确定性的同一个输入条件边可能走 A 分支也可能走 B 分支模型这次返回结构化 JSON、下次掺两句解释工具调用可能成功也可能静默失败。传统 CRUD 那套printtry/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 写在.envClaude 的 Key 写在config.toml本地测试又临时改环境变量。一旦要切换模型或者排查“到底是模型问题还是代码问题”光找 Key 就耗掉半小时。TaoToken 提供统一的 API 通道Base URL 是https://taotoken.net/api一个 Key 可以走通多家模型。这样你的 LangSmith Trace 里模型调用来源是统一的排查时不会因为“这个节点用的是哪家 Key”而分心。先拿 Key。访问https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentlanggraph_langsmithutm_campaignrewrite登录后在控制台创建 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_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_MODELgpt-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_V2true LANGCHAIN_API_KEYls-你的LangSmith密钥 LANGCHAIN_PROJECTlanggraph-agent-dev-v1 # TaoToken 统一通道 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_MODELgpt-4oLangSmith 的 Key 从https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentlanggraph_langsmithutm_campaignrewrite旁边的 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_urlos.getenv(TAOTOKEN_BASE_URL), api_keyos.getenv(TAOTOKEN_API_KEY), modelos.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(levellogging.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}, configconfig)注入之后在 LangSmith 搜索框里直接搜tag:v1.0或metadata.user_iduser_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_KEYls-xxx # 我的keydotenv 会把注释也读进去导致 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, dataorder-agent-dataset-v1, evaluators[check_json_valid], )跑完评估后LangSmith 会生成对比报告告诉你哪些样本改善了、哪些退步了。如果整体分数掉超过 5%坚决回滚哪怕你觉得改得很牛。模型通道这边TaoToken 的统一 Key 让你在切换模型时不用改代码只改TAOTOKEN_MODEL环境变量就行。LangSmith 的 Trace 里会记录每次调用用的哪个模型对比不同模型在同一 Dataset 上的表现时数据是干净的。需要长期跑 Agent 任务、做批量评估的可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentlanggraph_langsmithutm_campaignrewrite。想先验证模型对话效果的走模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentlanggraph_langsmithutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentlanggraph_langsmithutm_campaignrewrite里面有各语言的完整示例。最后说个我踩过的坑LangSmith 的免费额度对个人开发够用但如果你在循环里疯狂调用Trace 数量会暴涨。建议在开发阶段给graph.invoke加个recursion_limit防止 Agent 在条件边里打转result graph2.invoke( {msg: 帮我查一下订单 123456}, config{recursion_limit: 15} )如果 LangSmith 里大量 Trace 因为recursion_limit被截断说明你的条件边逻辑有问题赶紧去修路由判断。这个限制既是保护钱包也是帮你发现死循环的信号。