别再让你的 Agent 当“黑盒”了：LangSmith 如何用可观测性、评估和洞察闭环驯服生产级智能体

别再让你的 Agent 当"黑盒"了：LangSmith 如何用可观测性、评估和洞察闭环驯服生产级智能体

一、开场：Agent 上了生产，才是噩梦的开始

你花了三周时间搭了一个 Agent，本地测试全部通过，Demo 演示惊艳全场。然后你把它部署上线了。

第一天：用户反馈"回答不对"。你翻日志，发现 Agent 调了三个工具，但不知道它为什么选这三个、为什么跳过第四个、为什么在第二轮改变了策略。第二天：延迟突然从 2 秒飙到 8 秒。你怀疑是某个模型调用出了问题，但几百条 trace 摆在那里，你只能一条一条看。第三天：成本涨了 40%，你完全不知道钱花在哪里。

这就是所有 Agent 开发者都会撞上的那堵墙：确定性代码有断点，LLM 应用只有"黑盒"。

传统的 APM 工具能告诉你"接口耗时 3 秒"，但告诉不了你"Agent 为什么在第 7 步决定放弃检索、改用模型内部知识"。传统的单元测试能覆盖固定输入输出，但覆盖不了"同一个输入，模型这次可能走完全不同的推理路径"。

LangSmith 就是 LangChain 团队为这堵墙准备的答案。

二、先定位：LangSmith 在 LangChain 生态里是什么

如果你看过我之前写的那篇 DeepAgents 的文章，应该记得三层结构：

• LangChain 是 Agent Framework：模型接口、工具定义、消息类型。
• LangGraph 是 Agent Runtime：持久化执行、流式输出、人在回路。
• DeepAgents 是 Agent Harness：在 LangGraph 上封装好的规划、子 Agent、文件系统。

而 LangSmith 不在这个"构建栈"里，它是横跨整个生命周期的平台层。

LangChain 官方文档写得很清楚：LangSmith 是框架无关的（framework-agnostic） 平台，用于追踪、评估、提示词管理和部署，覆盖从开发到生产的整个 Agent 生命周期。你不需要用 LangChain 也能用它------可以配 OpenAI SDK，可以配 Anthropic 官方库，甚至可以通过 OpenTelemetry 接入任何 LLM 应用。

IBM 对它的定位总结得很精准："LangChain 帮你构建工作流，LangSmith 确保工作流平稳运行。"

一句话：LangChain 造车，LangGraph 修路，LangSmith 建监控中心。

三、核心机制一：Tracing------把一次 Agent 调用拆成一棵树

LangSmith 的根基是 Tracing（追踪） 。没有这个，后面的一切都无从谈起。

3.1 它到底追踪什么

当你用 LangChain 的 create_agent 构建 Agent 时，不需要写任何额外代码，只要设置两个环境变量，所有步骤就会自动被追踪：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

然后正常运行你的 Agent：

from langchain.agents import create_agent

agent = create_agent(
    model="gpt-5.5",
    tools=[send_email, search_web],
    system_prompt="你是一个能发邮件和搜索网络的助手。",
)

response = agent.invoke({
    "messages": [{"role": "user", "content": "搜索最新AI新闻，发摘要给john@example.com"}]
})

这些代码运行之后，LangSmith 会自动记录每一次模型调用、每一次工具调用、每一个决策点，从用户输入到最终输出，完整还原 Agent 的执行路径。

3.2 分布式追踪：跨服务的 Trace 拼接

真实的生产环境里，Agent 很少只跑在一个进程里。前端调你的 API 网关，网关调 Agent 服务，Agent 服务调工具服务------一次用户请求可能横跨三四个服务。

LangSmith 支持开箱即用的分布式追踪 ，通过 langsmith-trace 和可选的 baggage 头，把不同服务里的 run 拼成一棵完整的 trace 树。在 FastAPI 或 Starlette 里加上 TracingMiddleware，上游服务的 trace context 会自动传递到下游。

这个设计的工程含义很重要：它让"端到端延迟归因"从不可能变成了可能。 用户等了 5 秒，到底是模型慢、工具慢、还是网络慢？一棵完整的 trace 树直接给出答案。

3.3 多轮对话的 Thread 机制

Agent 往往不是一问一答，而是多轮交互。LangSmith 用 Thread 把同一会话里的多个 trace 关联起来。

它的处理逻辑值得细看：每一轮对话被追踪为一个独立的 run，通过共享的 thread ID 关联。LangSmith 会收集每条 trace 的 messages，如果每条 trace 只包含最新消息，就跨轮次拼接；如果连续 trace 重复发送了历史消息，就自动去重。

换句话说，你不需要自己维护会话状态------LangSmith 从 trace 里重建对话历史。 这解决了一个很烦人的问题：排查多轮对话的失败时，你看到的不是孤立的请求，而是一整条对话上下文。

四、核心机制二：Evaluation------用数据集把"感觉还行"变成"量化指标"

Tracing 解决了"Agent 在做什么"，但下一个问题更尖锐：Agent 做得对不对？

LLM 应用有个让人头疼的特性：提示词改一个字、模型换一个版本，行为可能天翻地覆。靠人工"感觉还行"来把关，在 Demo 阶段勉强能撑，到了生产就是灾难。

LangSmith 的评估体系基于三个核心概念：

• Dataset（数据集） ：一组测试输入，可选带期望输出。来源可以是人工编写、历史生产 trace、或合成数据生成。
• Target function（目标函数） ：你要测试的那部分应用------可能是一次带新提示词的模型调用、一个模块、或者整个工作流。
• Evaluator（评估器） ：给目标函数输出打分的函数。

4.1 离线评估：把生产 trace 变成回归测试

实际使用中，最高效的评估流程是这样流转的：

从生产环境的 tracing 项目里筛选出一批 trace，把失败案例一键加入数据集。然后每次修改提示词或模型配置后，跑一次实验（Experiment），对比新旧版本的得分。LangSmith 官方把这种离线评估比作传统软件开发里的单元测试。

但它比单元测试更灵活的地方在于：评估器本身可以是 LLM。你可以配置一个"LLM-as-a-judge"评估器，让它判断输出是否准确、是否包含了幻觉、是否符合特定格式。这比写死断言规则要实用得多，因为 LLM 的输出空间是开放的。

4.2 在线评估：生产流量的实时质量把控

离线评估覆盖的是"已知的测试用例"，但生产环境永远会给你惊喜。

LangSmith 的在线评估（Online Evaluations） 让你把评估器挂到生产 trace 上，对每一条实际请求实时打分。反馈来源可以是自动评估器，也可以是用户在 UI 里提交的反馈（user feedback）。

这样你得到的就不仅仅是一个静态的"离线测试通过率"，而是一个持续更新的质量信号。当某个评估指标突然下降，你可以在用户投诉之前就发现问题。

五、核心机制三：Insights------让 AI 帮你读 Trace

前面两个机制解决的是"已知问题"的排查和验证。但生产环境里最耗时的往往不是修已知的 bug，而是发现未知的 bug。

几百上千条 trace 摆在那里，你不可能一条一条看。LangSmith 的 Insights 就是为解决这个问题而生的。

5.1 它做什么

Insights 自动分析你的 trace，检测使用模式、常见 Agent 行为、以及失败模式，无需你手动审查 thousands of traces。

它使用分层分类（hierarchical categorization） 来理解数据：先把 trace 自动分组到顶层类别，显示每个类别的出现频率分布；然后你可以下钻到子类别，查看具体的 trace、反馈和运行统计。

每份 Insights Report 顶部都有一个执行摘要（Executive Summary） ，告诉你最重要的模式是什么，以及它们出现的百分比。关键发现旁边还有可点击的引用编号，直接跳转到最相关的 trace。

5.2 生成成本

生成一次覆盖 1000 条 thread 的 Insights Report，用 OpenAI 模型大约 $1-1-$ 1−2，用 Anthropic 模型大约 $3-3-$ 3−4。对于任何有生产流量的 Agent 来说，这个成本远低于人工逐条排查的人力成本。

5.3 它和 Tracing 的关系

Tracing 是显微镜 ------让你看清一次请求内部发生了什么。 Insights 是卫星地图------让你看清一万次请求里，哪些模式在反复出现。

两个视角缺一不可。

六、核心机制四：LangSmith Engine------从"发现问题"到"自动修复"

2026 年 5 月，LangChain 发布了 LangSmith Engine，这是 LangSmith 从"被动可观测性"向"主动可靠性"迈出的关键一步。

传统的 Agent 改进循环是这样的：

1. 追踪 Agent，理解它在做什么
2. 发现失败模式或功能缺口
3. 修改提示词、工具或逻辑
4. 从生产 trace 创建 ground truth 数据集
5. 跑实验确认改进、检查回归
6. 上线，然后重复

这个循环的痛点在于：每一步都是手动的，而且"知道该修什么"本身就很困难。 单条 trace 的审查揭示不了模式，跨 trace 统计错误频率也很费劲。

LangSmith Engine 把这个循环自动化了。它做四件事：

1. 聚类生产失败：把相似的失败 trace 聚合成命名 issue，比如"Agent 无法准确处理订阅取消请求"。
2. 诊断根因：连接你的代码仓库后，Engine 读取相关代码，定位问题源头。
3. 草拟修复：生成 PR，直接提交给你审查。
4. 防止回归 ：为每个 issue 提议一个自定义在线评估器，把失败 trace 拉入离线评估数据集------确保同一个 bug 不会在上线后悄悄复发。

用一个具体场景来理解：客服 Agent 处理"取消订阅"请求时频繁出错。Engine 发现一组 trace，在线评估器打了低分，用户反馈也是负面的。Engine 把这个聚合成一个命名 issue，显示严重程度（影响本周 12% 的客服会话）、时间线（四天前开始，与一次部署相关），并链接到具体 trace 作为证据。连接仓库后，Engine 读代码发现：取消工具的 description 写得模糊，导致 Agent 在用户只是询问选项时就尝试执行取消。Engine 草拟一个 PR，修改工具描述。同时提议一个针对性的在线评估器，确保这个失败模式不再悄悄回归。

这背后的设计哲学很清晰：可观测性的终点不是"看到问题"，而是"自动修复问题"。

七、代码看一眼：从 Tracing 到 Evaluation 的完整链路

理论说了不少，上代码。

7.1 启用 Tracing

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "lsv2_pt_..."

# 你的 Agent 代码正常运行，trace 自动记录

7.2 运行一次评估

from langsmith import Client, evaluate

client = Client()

# 1. 创建数据集
dataset = client.create_dataset("customer-support-qa")
client.create_examples(
    dataset_id=dataset.id,
    inputs=[
        {"question": "如何重置密码？"},
        {"question": "退款流程是什么？"},
    ],
    outputs=[
        {"answer": "点击登录页的'忘记密码'，按邮件指引操作。"},
        {"answer": "进入订单页，点击退款按钮，3-5个工作日到账。"},
    ],
)

# 2. 定义目标函数（你的 Agent）
def target(inputs: dict) -> dict:
    return agent.invoke({"messages": [{"role": "user", "content": inputs["question"]}]})

# 3. 定义评估器
def correctness(run, example):
    predicted = run.outputs["answer"]
    expected = example.outputs["answer"]
    return {"score": 1.0 if expected in predicted else 0.0}

# 4. 跑实验
results = evaluate(
    target,
    data="customer-support-qa",
    evaluators=[correctness],
    experiment_prefix="prompt-v2",
)

LangSmith 会自动追踪 target 函数内部的每一次模型调用和工具调用，作为该次评估运行的子 run。实验结果在 UI 里可以直接对比不同 prompt 版本的得分。

八、部署与定价：从免费试用到生产级自托管

8.1 定价

LangSmith 的定价结构很清晰：

• Developer：$0/席/月，含 5k base traces/月，1 个席位。适合个人开发者验证想法。
• Plus：$39/席/月，含 10k base traces/月，无限席位。适合团队生产使用，包含 Deployment、Engine 等高级功能。
• Enterprise：自定义定价，支持自托管和混合部署、自定义 SSO/ABAC/RBAC、支持 SLA。

初创公司可以申请创业计划，获得折扣价格和慷慨的免费月度 trace 配额。

8.2 自托管

对于数据不能离开自己环境的企业，LangSmith 支持完整自托管，跑在自己的 Kubernetes 集群上。基础安装包含可观测性、评估、提示词工程、Insights 和 Chat；Sandboxes、Engine、Fleet、LLM Gateway 和 Deployment 按需添加。

自托管是 Enterprise 计划的附加项，需要 LangSmith 许可证密钥。LangChain 提供 Terraform 模块，支持在 AWS、Azure、GCP 上快速部署。

这个选项的存在说明了一件事：LangSmith 的定位不是"玩具平台"，而是面向有安全合规要求的团队的工程基础设施。

九、什么时候该用它，什么时候不用

LangSmith 不是万能药。它解决的是Agent 从原型走向生产这个阶段的问题。

适合用的场景：

• 你的 Agent 已经开始处理真实用户请求，你需要知道它为什么失败
• 你在迭代提示词或模型配置，需要量化对比不同版本的效果
• 你的团队需要共享 prompt、数据集和实验结果
• 你有合规要求，数据不能离开自己的基础设施

不太适合的场景：

• 你还在跑一个简单的链式调用 Demo，一条 trace 就能看完
• 你的应用完全不涉及 LLM（那用传统 APM 就行）
• 你只想做一次性的评估，不需要持续监控

一个更实用的判断标准： 如果你曾经在凌晨两点对着几百条日志试图找出"Agent 为什么在那次请求里做了那个决定"，那你就需要 LangSmith。

十、收尾

回到开头那个问题：Agent 上了生产，为什么是噩梦的开始？

因为 LLM 应用的行为空间是开放的，传统软件工程里"日志 + 断点 + 单元测试"那套方法论，在这个空间里几乎失效。你需要的不是更多的日志，而是一套为不确定性设计的工程体系：用 Tracing 把黑盒变成白盒，用 Evaluation 把感觉变成数字，用 Insights 把个体变成模式，用 Engine 把手动修复变成自动闭环。

LangChain 团队对这个问题的理解是清晰的。从 LangChain 到 LangGraph 到 DeepAgents 再到 LangSmith，他们画出的是一条完整的线：构建 → 编排 → 执行 → 观测 → 评估 → 改进。

前三步解决"怎么让 Agent 跑起来"，后三步解决"怎么让 Agent 跑得对、跑得久"。

Agent 的上限不取决于模型有多强，而取决于你能不能看清它每一步在做什么、做错了什么、以及下一次怎么做得更好。 LangSmith 的价值，就是把这三个问题变成可操作的工程实践。