LangSmith Messages View：把 Agent 轨迹读成对话 · 干货攻略

  • 链接: https://x.com/hwchase17/status/2094985765629628904
  • 分类: x-tips
  • 来源: X @hwchase17
  • 作者: Jay
  • 更新: 2026-09-03

这是什么

LangSmith Messages View 是 LangSmith 轨迹查看器的三种视图模式之一（Messages / Turns / Details），目前处于 Beta 阶段。它将原本以结构化树状图呈现的 Agent 执行轨迹，转译为对话气泡式的聊天界面，让工程师无需理解 trace 术语也能快速定位问题。

根据官方文档（View traces - LangChain Docs），Messages View 的核心定位是：

Use the Messages view to scan the full trajectory and identify unexpected behavior, such as a bad tool result, an unexpected subagent handoff, or a latency spike, before drilling into a specific run.

每个 Turn 在 Messages View 里渲染为一个包含「模型回复 → 触发的 Tool Calls → 返回结果」的区块，可直接扫描整条轨迹而不必展开任何子 Run。

为什么值得关注

谁分享的

@hwchase17（Harrison Chase）是 LangChain 联合创始人兼 CEO，2026 年 9 月 2 日在 X 上发布该功能介绍，原文：

Agent traces shouldn't only be useful to infra teams. For most builders, the fastest way to debug an agent is to replay the conversation + tool calls in the shape the agent experienced them. That's the idea behind Messages View in LangSmith.

解决什么问题

传统 LangSmith trace 调试有几个门槛：

  1. 术语壁垒——Trace / Run / Thread / Trajectory 概念多，Agent Builder 新手上手成本高
  2. 树状结构难扫——一个请求展开几十个子 Run，要从最深处往回理解「为什么 Agent 走到了这里」
  3. 工具调用结果散落——Tool Call 和它的结果在不同层级，定位 Bad Case 需要在树里来回跳转

Messages View 用对话流的形式把上述所有信息打包进一个「气泡」里：用户输入 → 模型输出 → 调用的工具 → 工具返回结果，一气呵成。社区反馈（X 评论区）也印证了这一点：

  • @wearevalidating："following a trace like a chat is a UX win"
  • @elian_mcc："most debugging tools assume you already speak fluent trace, this assumes you speak english"
  • @suqitah（提醒局限）："chat view is great until a tool call result is 20kb of json"

核验过程

本攻略涉及的所有关键说法均经过以下官方来源交叉核验：

核验项 官方来源 结论
Messages View 处于 Beta 阶段 docs.langchain.com/langsmith/view-traces ✅ 确认，官方标注 beta
支持 Token 用量 / 费用 / 模型名显示 同上，"metadata row shows token usage, cost, model name" ✅ 确认
支持 Thought 块（扩展思考折叠） 同上，"Thought blocks appear inline with assistant messages when a model uses extended thinking, collapsed by default" ✅ 确认
支持 Subagent 内联展示 同上，"Subagents appear inline in the conversation as distinct actions" ✅ 确认
Tool Calls 支持分组折叠 同上，"multiple tool calls...collapse into a single grouped row" ✅ 确认
可导出为 Markdown 同上，"download button...exports as Markdown" ✅ 确认
快捷键 M/T/D 切换视图 同上，"Press M to switch" ✅ 确认
Beta 发布时间 Harrison Chase X 帖子（2026-09-02） ✅ 确认（Beta 功能）

原帖主张 vs 官方文档： - 原帖称「makes following traces as easy as following the chat」，为定性描述，与官方文档定位完全一致 - 原帖提及「beta rollout」与官方文档「beta」标注吻合 - 未核验项：Beta rollout 具体覆盖率（原帖主张 beta 灰度中，官方文档未给出具体比例）

上手步骤

前置要求

已有 LangSmith 账号，并在代码中开启了 tracing。

Step 1：确认 Tracing 开启

LangChain 应用默认自动 tracing；非 LangChain 应用可通过装饰器开启：

pip install langsmith
export LANGCHAIN_API_KEY=ls__...
export LANGCHANG_TRACING_V2=true
export LANGCHAIN_PROJECT=my-agent

from langsmith import traceable

@traceable(metadata={"ls_agent_type": "root"})
def my_agent(query: str):
    # Agent logic here
    ...

关键 metadata："ls_agent_type": "root" 表示此 Agent 的消息出现在主 Messages View；"ls_agent_type": "subagent" 则作为子 Agent 内联展示。

Step 2：打开 Threads 标签页

登录 smith.langchain.com，进入你的 Project → Threads 标签页。

⚠️ Threads 视图需要 Tracing 时传入 thread_id metadata，否则只能看到单独 Runs。

Step 3：切换到 Messages View

点击任意 Thread 打开 Side Panel，Side Panel 顶部有三个视图切换按钮：

  • Messages（Beta）——对话层，按 M 快捷键切换
  • Turns——每轮摘要卡片，按 T 切换
  • Details——调试层（默认视图），按 D 切换

Step 4：扫描轨迹找问题

在 Messages View 中，每个 Turn 块包含：

  • Token 用量 / 费用 / 模型名（元数据行）
  • AI 回复（可展开 Thought 折叠块）
  • Tool Calls（可折叠的分组）
  • 工具返回结果
  • Subagent（点击进入嵌套视图）

点击任意 Tool Call 或 AI 消息的链接，可直接跳转到 Details View 的对应 Run。

Step 5：导出对话

Messages View 右上角有下载按钮，可将完整轨迹导出为 Markdown 文件（包含用户消息、AI 回复、Tool Calls 和结果），方便在任何 Markdown 查看器中离线复盘。

排除特定 Run 不显示

如需从 Messages View 隐藏某个内部 Run：

from langsmith import LS_MESSAGE_VIEW_EXCLUDE

# 方式1：装饰器
@traceable(metadata={LS_MESSAGE_VIEW_EXCLUDE: True})
def internal_helper():
    ...

# 方式2：直接设置 metadata
runnable.invoke(input, config={
    "metadata": {"ls_message_view_exclude": True}
})

自定义消息格式

如自动格式检测不准，可强制指定：

@traceable(metadata={"ls_message_format": "openai"})  # completions / responses / anthropic
def my_agent():
    ...

坑与适用边界

⚠️ Beta 阶段已知局限

  1. Beta 功能，默认关闭——Side Panel 默认打开 Details View，需要手动切换到 Messages View
  2. 非所有集成自动支持——需确认你的框架/SDK 是否已集成 Messages View 支持（LangChain / OpenAI SDK / Vercel AI SDK 等已支持）
  3. 20KB+ JSON 工具结果——评论者 @suqitah 提醒：当 Tool 返回 20KB+ 的 JSON 时，气泡视图同样难读，此时需切回 Details View 展开原始输出

适用条件

✅ 适合的场景： - 多轮 Agent 对话调试（>3 轮） - Subagent 协作链路的可视化追踪 - 需要向非工程师（PM、设计）展示 Agent 行为 - 快速定位 Bad Tool Result 所在的 Turn

❌ 不太适合的场景： - 单步 LLM 调用（直接看 Details View 更快） - 超长 Tool 返回值（JSON > 10KB） - 追求精确性能分析（Token 计数、延迟拆解用 Details View）

Threads 视图的前置条件

Messages View 和 Turns View 都依赖 thread_id metadata。缺少此字段时，Trace 以单条 Run 展示，无 Threads 标签，Messages View 也不可用。

一句话结论

LangSmith Messages View 把原本需要「懂 trace 术语」才能调试的 Agent 轨迹，变成了任何人都能像读聊天记录一样理解的对话流，配合快捷键 M/T/D 在对话概览和深度调试之间无缝切换——是 Agent 开发工作流从 infra 视角转向 builder 视角的重要一步，目前处于 Beta，值得在非生产项目中小规模试用。

核验来源： - View traces - LangChain Docs（Messages View Beta 官方文档） - Trace LangGraph applications - LangChain Docs（Messages View 技术集成说明） - X @hwchase17 (2026-09-02)（功能首发公告） - X @GitMaxd (2026-09-02)（Beta 灰度用户实操反馈）