开篇：Agent 能跑起来，不等于能上线

前面我们已经讲了 Tools、Agent、Memory、LangGraph、Middleware 和 Streaming。到这里，很多人会以为：Agent 跑起来了，项目就完成了。

错。真正难的地方，从上线那一刻才开始。用户说答案不对，你要知道错在哪里；老板问为什么耗时 18 秒，你要知道卡在哪一步；版本改了 Prompt，你要知道效果到底有没有变好。

• 黑匣子：记录一次 Agent 请求的完整执行过程。

• 显微镜：把 LLM、Retriever、Tool、Prompt、Parser 每一步拆开看。

• 质检台：用数据集、评测器和实验对比，判断改动是否真的有效。

一、LangSmith 到底解决什么问题？

传统后端排查问题，看日志、看链路、看监控。大模型应用也一样，只是链路更复杂：一次回答可能包含问题改写、知识库检索、Rerank、Prompt 拼接、模型调用、工具调用、结构化输出、人工审批。普通日志只能看到碎片，LangSmith 要做的是把这些碎片还原成一棵完整的 Trace 树。

图 1：普通日志只能看碎片，LangSmith Trace 能看完整链路。

LangSmith 官方把它定位为 LLM 应用的可观测和评测平台，能从单条 Trace 到生产级指标提供可见性；官方文档也强调，它可以记录、检查和分析 LLM 应用执行的每一步。

• 开发期：看单次 Trace，调 Prompt、检索、工具参数。

• 测试期：跑 Dataset，做离线 Evaluation，比较不同版本。

• 上线后：看线上 Trace、Latency、Cost、Feedback、Online Eval。

二、几个核心概念，先压缩成一张图

LangSmith 的术语看起来多，其实就几层。Project 是应用空间。Trace 是一次请求。Run 是请求里的一个步骤。Thread 是多轮对话。Dataset 是评测题库。Experiment 是某个版本跑完题库后的结果。Evaluator 是打分规则。Feedback 是用户和人工标注。

图 2：Project、Trace、Run、Thread 的关系。

图 3：LangSmith 核心概念速查表。

三、Trace 是怎么被记录出来的？

看源码时，不要一头扎进细节。先抓主线。LangSmith 的追踪，本质就是在函数入口创建 RunTree，执行中创建 child run，结束时把 outputs、error、end_time patch 回平台。

图 4：LangSmith 追踪源码链路压缩图。

1. 环境变量只是开关，不是核心

最常见的接入方式，是设置 LANGSMITH_TRACING、LANGSMITH_API_KEY、LANGSMITH_PROJECT。它们解决的是“要不要追踪、发到哪里、归到哪个项目”。真正的源码逻辑，不在环境变量，而在 traceable、tracing_context、RunTree 和 Client。

2. @traceable 的本质：给函数包一层执行壳

LangSmith SDK 里的 traceable 装饰器会检查函数类型，支持普通函数、异步函数、生成器、异步生成器。函数执行前，它会准备一个 run container；函数执行成功，记录 outputs；函数抛错，记录 error；最后把结果写回 LangSmith。

3. RunTree 是 Trace 树的核心对象

RunTree 里有 name、run_type、inputs、outputs、error、tags、metadata、child_runs、trace_id、dotted_order。Root Run 代表一次完整请求，child run 代表模型调用、检索调用、工具调用等子步骤。

• name：这一步叫什么，例如 answer_agent、retriever、stock_tool。

• run_type：这一步是什么类型，例如 chain、llm、tool、retriever。

• inputs / outputs：这一步吃进去什么，吐出来什么。

• error：这一步是否异常。

• tags / metadata：用来标记环境、版本、用户、业务线、模型名。

4. post 和 patch：一个写开始，一个写结束

RunTree.post() 负责把 run 创建到平台；RunTree.end() 负责补 outputs、error、end_time；RunTree.patch() 负责把最终状态更新到平台。也就是说，Trace 不是一行日志，而是一个可持续更新的运行对象。

5. create_child：为什么 UI 里会出现树形链路？

当一个 Agent 里又调用 LLM、Retriever、Tool 时，源码会把这些步骤挂成子 run。父子关系保存下来，LangSmith UI 才能展示出树形 Trace。你看到的“展开每一步”，本质来自 RunTree 的父子结构。

四、排查 Agent 问题，不要凭感觉

很多人排查大模型问题，第一反应是改 Prompt。其实这是最低效的。Agent 的错，可能错在问题改写、检索、Prompt、工具、模型、结构化输出、记忆污染。LangSmith 的价值，就是把这些步骤拆开。

图 5：一次错误回答的排查顺序。

1. 先看输入

用户原始问题有没有被前端截断？有没有被 Router 改写错？thread_id 是否串到了别人的会话？这些问题如果不先看，后面全是误判。

2. 再看检索

RAG 问答错，大概率不是模型笨，而是检索给错资料。要看 query、TopK、文档内容、metadata、score、Rerank 后顺序。召回垃圾，模型只能用垃圾做饭。

3. 再看 Prompt

Prompt 最终进入模型时是什么样，和你代码里写的模板不一定一样。因为中间可能拼了历史消息、工具结果、检索上下文、系统规则、结构化输出约束。LangSmith 要看的不是模板，而是最终 Prompt。

4. 再看 Tool

工具调用要看三件事：模型选的工具对不对，参数抽取准不准，工具返回是否可信。很多 Agent 不是模型回答错，而是工具拿错数据。

5. 最后看模型输出

模型是否忽略资料？是否幻觉？是否没有遵守 JSON 格式？是否 token 不够被截断？这些都可以通过 LLM Run 的输入、输出、usage、latency 来排查。

五、评测：别再用“感觉还行”判断版本好坏

真正上线的 AI 应用不能只靠手动问几条。Prompt 改了、模型换了、TopK 调了、Rerank 换了，都要跑数据集。LangSmith Evaluation 的核心就是：拿同一批问题，跑不同版本，然后比较结果。

图 6：LangSmith Evaluation 的基本闭环。

1. Dataset：把问题沉淀下来

Dataset 不是随便找几条测试问题。它应该来自三类数据：高频问题、历史 Bad Case、核心业务场景。每条 example 至少要有 inputs，可以有 reference outputs 和 metadata。

2. Evaluator：打分规则要贴近业务

客服场景看是否解决问题；RAG 场景看答案是否基于资料；结构化输出看字段是否完整；金融或医疗场景还要看安全边界。不要只看“回答像不像人话”。

3. Experiment：每次改动都要留下证据

一次 Experiment 表示某个应用版本在 Dataset 上的评测结果。它不只存最终分数，还会保留每条样本的输出和 Trace。这样你能知道：分数变差，是哪一类问题变差。

4. Online Evaluation：上线后继续盯真实流量

离线评测只能证明测试集上有效。线上流量会出现更多边界问题，所以还要在线评测 runs 和 threads，监控质量退化、异常模式和用户反馈。

六、企业级接入：Java + Python 服务应该怎么落地？

如果你的系统是 Java 主服务 + Python AI 服务，LangSmith 不应该只在 Python 里随便开个环境变量。它要和业务链路对齐。否则 Trace 有了，业务日志却对不上。

图 7：Java + Python 企业级 LangSmith 接入架构。

1. Java 网关必须传业务标识

Java 侧负责 user_id、request_id、tenant_id、thread_id、灰度版本、业务场景。Python AI 服务调用 LangChain / LangGraph 时，把这些字段放进 metadata 和 tags。

2. Python AI 服务负责 Trace 粒度

AI 服务要把关键步骤拆清楚：rewrite_query、retrieve_docs、rerank_docs、build_prompt、call_model、call_tool、parse_output。不要所有步骤都塞进一个大 run。

3. 敏感数据要先脱敏

LangSmith 能帮你排查问题，但不代表什么都能发。手机号、身份证、订单敏感字段、内部密钥、客户隐私，要在进入 Trace 前做脱敏或屏蔽。

4. Prompt 版本、模型版本、数据版本必须记录

同一个问题今天答对，明天答错，往往是版本变了。你必须记录 prompt_version、model_name、model_params、retriever_version、embedding_model、vector_index_version、tool_version。

七、上线检查清单

• 每次请求必须有 request_id，可以和业务日志互查。

• 多轮对话必须有 thread_id / session_id。

• 关键节点必须拆成独立 run：检索、Prompt、模型、工具、解析。

• 每个 run 都要带 tags 和 metadata，至少包括环境、版本、业务线。

• 不能把隐私、密钥、内部账号明文写入 Trace。

• Bad Case 要能一键沉淀到 Dataset。

• Prompt 或模型改动后，必须跑 Experiment 对比。

• 上线后要监控延迟、成本、错误率、用户反馈和在线评测结果。

结尾：LangSmith 不是锦上添花，是上线底座

LangChain 和 LangGraph 负责让 Agent 跑起来。LangSmith 负责让 Agent 看得见、查得清、评得准。没有 Trace，你只能猜。没有 Evaluation，你只能凭感觉。没有反馈闭环，Agent 永远停在 Demo。