做 AI Agent 的人多半都有同一种感受模型效果不好不可怕最怕的是出了 Bug 你根本没法查。传统后端出问题打开日志、看报错、翻调用链基本能定位。Agent 应用完全是另一回事——一次回答背后可能调用了十几次甚至几十次大模型中间穿插着工具返回、上下文拼接、路由判断任何一环悄悄跑偏用户感知到的只是“它答非所问”而你在后端连个像样的堆栈都拿不出来。我在带一个客服型 Agent 项目时对这种痛点体会特别深。线上偶尔反馈“这个机器人又在乱说了”本地死活复现不了最后靠 LangSmith 做全链路观测把整条推理链路上每一个输入输出抓出来问题才真正按住。这篇文章算是一次使用复盘聊清楚 LangSmith 怎么接、怎么用、能解决哪些问题以及哪些坑是我踩过之后不希望你再踩的。1. AI Agent 为什么需要全链路观测1.1 传统日志体系在这里为什么失灵传统 Web 服务的调用是确定性的。请求进来经过固定代码路径返回结果。你只需要在关键节点打日志出了问题顺着链路就能找回来。但 Agent 不一样它的执行路径不是写死在代码里的而是模型根据当前上下文、工具返回结果、历史消息现场“决策”出来的。举个最简单的例子同一个问题用户多问了一句“顺便帮我查下天气”Agent 就可能多走一次工具调用。也就是说不存在一份固定的调用堆栈供你事后对照。你想复现一个线上问题往往需要复现当时完整的对话上下文这在用户量大起来以后基本做不到。所以传统日志体系在这里至少有三个盲区日志只记录了业务侧的入参出参记录不到每一轮的 prompt 拼了什么内容。对工具返回的数据没有完整的快照脏数据导致模型跑偏的时候根本不知道源头在哪。模型调用有随机性同样的输入两次输出可能不同靠经验猜不如靠回放看清。我当时最大的挫败感来源就是“猜”。猜是上下文问题猜是模型问题猜是工具超时。猜来猜去效率极低。1.2 一个“幽灵故障”是怎么被揪出来的分享一个真实发生过的现场。客服 Agent 接到一个订单查询请求用户说“我的订单还没发货”。正常流程应该是 Agent 先查出订单列表再调用物流工具查进度。但线上有段时间出现偶发情况Agent 不直接回答反而反问用户“请问您的订单号是什么”。从业务日志看推理工具确实被调用了返回结果也正常但 Agent 给出的回复就是不对劲。我把日志翻来覆去看了好几遍Local 复现又一直正常一度怀疑是模型概率问题。直到接上 LangSmith才看到整条 Trace 里某一个环节的真相。问题出在上游另一个 Agent。它在会话上下文里生成订单号时有一次因为外部接口超时落库了一个默认占位符“N/A”。等客服 Agent 后续拿到这个字段去查物流查询工具正常返回了“未查询到有效订单”这个结果再被塞回上下文模型判断“无订单信息”于是进入了话术兜底分支反问用户订单号。这一整条因果链牵涉两个 Agent、两次大模型推理、一次外部接口超时中间任何一个环节用传统日志都看不到全貌。但 Trace 把它从头到尾串起来了。这正是全链路观测的意义你不仅要看到“某一个调用返回了什么”还要看到“这个结果是在什么上下文中被接收的”。2. LangSmith 的核心设计从调用链到评测体系2.1 几个必须先搞懂的概念LangSmith 的基础概念不复杂但对第一次接触的人来说最容易被术语绕晕。我按自己的理解给你捋一遍。概念一句话解释类比Run一次最小执行单元比如一次 LLM 调用、一次工具调用、一次检索器查询快递链路里的一个站点Trace多个 Run 按调用关系组成的树展示一次 Agent 任务的完整流水从商家到用户手的全流程Project逻辑隔离的容器一般按环境或业务线分独立的快递仓库各管各的Dataset用于评测的任务样本集试卷Evaluator对 Trace 或输出打分的规则/模型阅卷老师你用 LangChain 或 LangGraph 写 Agent 时每一次model.invoke()、tool.execute()、retriever.search()都会被自动包装成一个 Run。这些 Run 自带上层调用关系LangSmith 拿到以后按照时间线和父子关系拼成 Trace。在 UI 里你会看到一个一左一右的树形瀑布图每一条树干代表一次完整 Agent 任务点开以后每一层都能看输入、输出、耗时、Token 数。这不是事后拼接的日志而是执行时就被埋好的结构化因果链所以它有传统日志给不了的回放能力。2.2 光“看得到”还不够得把评测做进闭环全链路观测如果只是给一个可视化界面那它顶多算是一个升级版日志平台。LangSmith 真正的增值点在于它把观测数据和评测能力绑在了一起。什么是评测你可以把线上跑过的优质对话收集起来作为正样本建一个 Dataset。之后每当 Agent 逻辑改动你可以拿这个数据集重新跑一遍让系统自动给结果打分。打分方式既可以是简单的 Python 规则比如回答里是否包含关键字段也可以是用另一个大模型当裁判按“正确性”“语气”“是否完整引用工具结果”等维度打分。我用得最多的组合是先靠 Trace 发现“某类问题在上下文缺失工具结果时会出现”然后把这类样本打入 Dataset写一个 LLM-as-a-judge 的评估规则再修改 prompt 或路由逻辑用网格跑测试验证修复是否生效。换句话说LangSmith 帮你把“发现线上问题”这件事从偶发的人工排查变成了可持续的回归测试。这是 Agent 工程化里特别重要的一环。模型输出天然不稳定如果评测不沉淀成测试集每次迭代都是带盲区上线。3. 实操接入把 LangSmith 跑起来3.1 最小配置两步就能出 Trace接入过程比想象中简单最基础的方式连代码都不用改只用环境变量。先去 LangSmith 官网创建一个账号拿到一个项目 API Key。Key 的格式一般是lsv2_开头。然后在你启动 Agent 进程的环境里加上以下几项export LANGCHAIN_TRACING_V2true export LANGCHAIN_API_KEYlsv2_你的key export LANGCHAIN_PROJECTmy_agent_demo设置完以后只要你的 Agent 项目是用 LangChain、LangGraph 或 LangChain 生态的组件搭的所有通过组件触发的大模型调用、工具调用、链式逻辑都会自动上报到 LangSmith 对应的 Project 里。什么都不用改运行一次任务去 Web 控制台刷新就能看到第一条 Trace。如果你的环境不是纯 LangChain或者你只想在特定进程里开启追踪也可以在代码里显式初始化from langsmith import Client client Client( api_urlhttps://api.smith.langchain.com, api_keylsv2_你的key, ) # 相当于在进程内开启追踪 from langchain_core.tracing import set_tracing_callback_manager不过说实话日常项目里环境变量那一套是最省事的改代码反而容易漏。跑不同的业务模块时换个LANGCHAIN_PROJECT再启动进程即可不用动业务逻辑。3.2 在 LangGraph Agent 里接入观测如果你的 Agent 是用 LangGraph 写的接入观测几乎零成本而且 LangGraph 的节点执行信息也会被完整记录。这里给你一个最简的 ReAct Agent 示例from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.prebuilt import create_react_agent tool def get_weather(city: str) - str: 返回指定城市的天气信息。 return f{city}今天多云气温 24 摄氏度。 model ChatOpenAI(modelgpt-4o-mini, temperature0) agent create_react_agent(model, tools[get_weather]) resp agent.invoke({ messages: [{role: user, content: 北京今天天气怎么样}] }) print(resp[messages][-1].content)只要环境变量在前面已经配好这段代码跑完LangSmith 控制台会自动出现一条 Trace。你能看到它分为 “Agent 节点” “工具调用 get_weather” “最终回复” 几个层级每一层分别耗时多少、消耗了多少 Token、输入输出是什么。有一点实际经验值得注意在 LangGraph 里做复杂 Agent 时节点命名很重要。默认的节点名如果是一串难以理解的英文Trace 可读性会很差。建议在定义 Graph 时给每个节点一个语义化的 name比如retrieve_order、check_refund_policy这样排查问题时一眼就知道执行到哪一步也方便后续用名字做过滤器。3.3 不用 LangChain 也能接SDK 直连方式不是所有团队都用 LangChain。有些项目会直接用 OpenAI SDK 写循环有些用 Spring AI极端的还有用 Rust 从零搭 Agent 运行时。这些场景下LangSmith 依然可以接入因为它本质上是一个可上报的追踪后端只不过提供了 LangChain 生态的自动埋点。你可以通过官方 Python 或 TypeScript SDK手动创建 Run 和嵌套子 Run。代码结构大概是这样的from langsmith import Client client Client() # 开启一条自定义 Agent 执行记录 run_id client.create_run( namecustom_agent, inputs{question: 用户问题原文}, run_typechain, ) # 你的Agent实际逻辑内部可以再嵌套LLM Run或Tool Run # ... client.update_run( run_id, outputs{answer: 最终回答}, )这种手动埋点的方式也适用于 Rust 或 Java 生态。你可以在网关层统一封装一个上报函数把每次模型请求和工具返回序列化后发到 LangSmith。我们组有一个用 Rust 写工具的同事他最后就是在网关层做了统一上报而不是在每个工具函数里手写埋点效果一样还省得侵入业务代码。4. 全链路观测的实战要点4.1 拿到一条 Trace 后先看哪几个指标Trace 页面打开以后信息量很大新手容易一头扎进输入输出文本里。我的建议是按以下顺序看第一是总耗时和各级耗时。整个 Agent 任务用了 40 秒到底卡在哪一步如果大模型调用占了 35 秒可能是模型响应慢也可能是上下文太大导致首 Token 延迟高。如果工具调用占了 20 秒那问题大概率在上游 API。第二是 Token 消耗分布。Agent 反复调用模型经常出现“上下文越滚越大、单次调用输入 Token 数千”的情况。Trace 里会标注每次调用的输入输出 Token 数看到某层输入异常大就该怀疑是否有历史消息被重复注入。第三是错误信息和重试标记。LangSmith 会记录异常堆栈Rate Limit、超时、格式解析错误都会显示。特别要注意“看起来成功但实际上内容不对”的情况。模型返回 200 不代表没出错有可能返回的是兜底话术这需要看输出内容本身去判断。有一条 UI 使用习惯值得分享排查具体用户问题时不要只在“最近 Trace”列表里刷。优先用 Trace 里的搜索框按 metadata 过滤或者按时间范围、Token 数排序要么精准定位要么排掉干扰项。4.2 用 Metadata 和标签做业务维度的切片线上 Agent 服务用户量大所有 Trace 混在一个 Project 里等于没有观测。我习惯在每次调用时写入业务元数据LangSmith 支持通过 metadata 字段携带业务维度信息。以 LangChain/LangGraph 为例agent.invoke( {messages: [{role: user, content: 我要退款}]}, config{ metadata: { user_id: u_10086, session_id: s_20240101, channel: app, env: production, business_line: after_sale } } )这些键值对会跟着 Trace 一起存储。之后在 LangSmith 的查询界面里你就能按user_id、session_id过滤出某一个用户当天的所有 Agent 操作。业务侧客服反馈“某个用户昨天在 App 端遇到了问题”你可以用 channel 和 user_id 两个条件精准筛出当时的原始链路。我还会在 metadata 里加一个version字段记录当前 Agent 的 prompt 版本或代码发布版本。这个字段看起来简单但对复盘“这个版本上线之后召回率下降”这类问题非常有用。没有版本标记你以为在对比数据实际上比的是不同代码时期的产物结论全是错的。4.3 把成本“观测”起来Agent 项目里最大的隐藏成本不是推理模型而是被中间反复调用堆积出来的 Token。传统应用没有这个概念后端逻辑多跑几次最多是 CPU 多点负载Agent 多跑一轮模型就是在烧钱。LangSmith 在每次 LLM Run 上都会记录 Token 数并且按模型单价折算成本估算。我建议每个项目从第一天就关注这几个指标单次会话平均 Token 成本、工具调用失败后的重试成本、上下文滚大之后的边际成本。我实际遇到过一个场景Agent 在做多轮问答时每轮都把完整聊天记录发给模型导致第 10 轮时单次输入 Token 已经接近上下文窗口上限。单看每一轮不觉得贵用 LangSmith 按 session 聚合看趋势后才知道成本曲线是陡增的。后来改成按需截断历史消息策略总成本降了差不多 60%。5. 生产环境常见问题与排查技巧实录5.1 高并发场景下观测采样怎么取舍很多人一上来就把 Agent 服务的所有调用 100% 接入 LangSmith结果跑到某天发现上报量大、费用上涨、存储与检索变慢。这里“怎么扛并发”的关键不一定在客户端而在于采样策略。我建议分环境区别对待开发环境100% 全量上报哪怕成本高一点但要保证每次实验都有完整回放能力。生产环境按需采样。LangSmith 支持设置采样率你可以配置 trace_sample_rate比如线上只采样 10%但把错误链路和关键业务链路设为 100% 上报。怎么实现关键业务全量你可以在调用代码里做判断。比如支付、退费等高风险意图的会话把 metadata 里标记must_tracetrue同时开启一个单独的强制上报通道。这样既保留了大部分业务场景的排查能力又不会让所有高并发流量把观测平台打爆。采样还有一个隐藏作用它强迫你想清楚“什么业务真的需要精细观测”。不是所有 Agent 调用都值得全链路记录把有限的存储留给高价值请求是生产级工程的正确思路。5.2 大模型调用失败的排查链路生产环境里最恶心的问题之一是大模型接口偶发失败。原因五花八门触发限流、上下文超长、网关超时、返回格式不合法。以前排查这类问题只能看服务端日志里的一行报错而 Agent 往往在调用前已经拼了很长的上下文只靠一个错误码完全搞不清触发条件。接上 LangSmith 以后排查路径就清晰了。一次超时异常你会在 Trace 里看到完整的 prompt 详情包括系统提示词、工具返回内容、历史轮次。请求耗时和重试次数。有些模型 SDK 会自动重试Trace 里能看到 Retry 标记定位到是“第一次超时后重试成功”还是“重试仍然失败”。异常类型和报错原文。上下文超限、Rate Limit 这类错误在 Trace 树上一目了然不用再去查云服务商的纯裸日志。有一次线上问题很邪门Agent 偶尔返回“抱歉我无法处理你的请求”。看返回内容是正常的也没有任何异常。Trace 一拉发现工具层返回了一个超长字符串把它塞进 LLM 之后上下文压缩策略把关键指令给截掉了导致模型判定无法回答。这种事情如果没有完整 Trace光靠观察最终结果永远定位不到工具返回长度这个根因。5.3 敏感字段的脱敏问题别等出事再处理观测平台把所有输入输出都记录下来这对排查问题很方便但也直接带来了数据安全和隐私问题。Agent 在客服场景里经常会拿到手机号、订单号、身份证等信息如果原样上报到观测平台不合规且风险极大。我的处理习惯是在埋点上报之前对敏感字段做系统级脱敏。这不是靠提示词要求模型“不要输出敏感信息”模型做不到稳定承诺。正确做法是在业务代码的边界层把手机号、身份证号等字段做正则替换如138****1234订单号保留前后几位即可。LangSmith 本身也提供一些数据处理能力比如在 SDK 里配置阻断规则或者在上报前对输入输出做二次处理。但我还是那句话不要把敏感信息发出去再回来清洗源头就别让它流出。观测要的是结构化信息不是隐私原文。6. 选型对比与个人体会6.1 LangSmith 与同类工具怎么选说到全链路观测可选的方案不止 LangSmith。我用过的还有 Langfuse 这类开源或半开源方案也见过团队直接基于 OpenTelemetry 自建链路监控。给你一张主观对比表供参考。维度LangSmith开源/自建方案自建监控体系LangChain 集成度极深基本零代码中等需要配置低完全自己写自动评测能力内置 Dataset/Evaluator部分有需自建大概率没有开箱即用体验高中低数据管控灵活度受平台限制高最高上手门槛低中高选型建议很简单如果你整个技术栈深度绑定 LangChain / LangGraphLangSmith 的自然优势非常明显开箱即用评测闭环也最完整。如果你的 Agent 是纯自研架构用 Rust、Go、Spring AI 这类生态或者公司对数据私隐管理要求极其严格那自部署一个开源观测平台或者自建收集链路可能更务实别被框架绑定拖住。6.2 什么时候其实不需要全链路观测不是所有项目都要上全套观测。刚起步的 Demo、个人玩具项目、原型验证阶段直接打印日志看结果反而更快没必要为了观测而观测。真正需要全链路观测的信号我觉得有三个第一Agent 已经开始服务真实用户第二问题不再能靠本地复现第三你正在高频迭代 prompt 和工具逻辑。满足任意两个就值得接观测。回到我自己的体会Agent 工程化中最贵的东西不是 Token是排查问题的时间。一个线上问题如果靠猜可能消耗整个团队一周靠 Trace 回放可能半天就定位。LangSmith 这种全链路观测工具解决的不只是“看得到”它让 Agent 的推理路径变得可回放、可评估、可改进这是一个把玄学变成工程的过程。最后再分享一个我最近养成的习惯每次改动 Agent 的 prompt 或工具逻辑都强制先跑一遍历史问题集在 LangSmith 里把评测结果和上一版做 Diff。刚开始觉得很折腾坚持下来以后线上回归问题明显少了。如果你也在维护一个投入生产的 Agent建议从今天就开始准备一个属于你自己的问题集把每一次线上翻车都沉淀进去。