Messages 视图集成

Messages 视图目前处于 测试阶段。

Messages 视图将智能体的追踪记录渲染为类似聊天的对话：用户提示、模型响应、工具调用和工具结果，按顺序排列。Messages 视图需要两条运行元数据来渲染主对话：

线程分组：每次运行中的 thread_id 告诉 LangSmith，一组运行属于同一个对话。
运行分类：在一次轮次的顶级运行上设置 ls_agent_type: "root" 会将该运行标记为主对话的一部分。标记为 subagent 的运行会作为子智能体操作显示在线程中，而标记为 middleware 或 compaction 的运行目前会被过滤掉。

对于大多数 LangSmith 集成，这两项都会自动为你设置。当你需要手动设置元数据时，以下示例涵盖了链式调用模式下的 OpenAI Responses API 以及标记自定义中间件或防护栏。

支持的集成

以下集成会自动设置 thread_id 和 ls_agent_type：

Claude Code
Claude Agent SDK
OpenAI Codex
Cursor
Pi
OpenCode
GitHub Copilot
Deep Agents
LangChain
LangGraph
OpenAI Chat Completions (wrap_openai)
OpenAI Responses API, 单次调用 (wrap_openai)

链式调用模式下的 OpenAI Responses API（previous_response_id）会自动设置 ls_agent_type，但你需要自己设置 thread_id。更多详情，请参阅链式调用模式下的 OpenAI Responses API 示例。有关 ls_agent_type 的完整 schema 以及官方集成在非根运行上设置的其他值（subagent、middleware、compaction），请参阅编码智能体元数据规范。有关底层的线程分组机制，请参阅配置线程。

链式调用模式下的 OpenAI Responses API

当你通过传递 previous_response_id 来链式调用 OpenAI Responses API 时，OpenAI 会在服务器端存储对话状态，而 LangSmith 的包装器没有自然键来将这些调用分组到一个线程中。你需要自己设置 thread_id，可以在每次调用时设置，也可以在包装器初始化时设置。

请为 thread_id 使用 UUID v7。LangSmith 的 SDK 导出了一个 uuid7 辅助函数，并且 UUID v7 按创建时间排序，因此线程在列表视图中能保持顺序。

每次调用时设置元数据

在每次调用时设置 thread_id。当一个包装好的客户端服务于多个线程时使用此方法（例如，每个进程一个客户端，多个并发对话）。

import openai
from langsmith import uuid7
from langsmith.wrappers import wrap_openai

client = wrap_openai(openai.Client())
thread_id = str(uuid7())

res1 = client.responses.create(
    model="gpt-5.6",
    input="What is the capital of France?",
    store=True,
    langsmith_extra={"metadata": {"thread_id": thread_id}},
)

res2 = client.responses.create(
    model="gpt-5.6",
    input="And its population?",
    previous_response_id=resp1.id,
    store=True,
    langsmith_extra={"metadata": {"thread_id": thread_id}},
)

import OpenAI from "openai";
import { uuid7 } from "langsmith";
import { wrapOpenAI } from "langsmith/wrappers";

const client = wrapOpenAI(new OpenAI());
const threadId = uuid7();

const res1 = await client.responses.create({
  model: "gpt-5.6",
  input: "What is the capital of France?",
  metadata: { thread_id: threadId },
  store: true,
});

const res2 = await client.responses.create({
  model: "gpt-5.6",
  input: "And its population?",
  previous_response_id: res1.id,
  metadata: { thread_id: threadId },
  store: true,
});

初始化时设置元数据

在包装客户端时设置一次 thread_id。通过此包装器进行的每次调用都会被标记上相同的线程。当一个包装好的客户端在其生命周期内恰好服务于一个线程时使用此方法（例如，每个对话一个工作者）。

import openai
from langsmith import uuid7
from langsmith.wrappers import wrap_openai

thread_id = str(uuid7())

client = wrap_openai(
    openai.Client(),
    tracing_extra={"metadata": {"thread_id": thread_id}},
)

res1 = client.responses.create(
    model="gpt-5.6",
    input="What is the capital of France?",
    store=True,
)

res2 = client.responses.create(
    model="gpt-5.6",
    input="And its population?",
    previous_response_id=resp1.id,
    store=True,
)

import OpenAI from "openai";
import { uuid7 } from "langsmith";
import { wrapOpenAI } from "langsmith/wrappers";

const threadId = uuid7();

const client = wrapOpenAI(new OpenAI(), { metadata: { thread_id: threadId } });

const res1 = await client.responses.create({
  model: "gpt-5.6",
  input: "What is the capital of France?",
  store: true,
});

const res2 = await client.responses.create({
  model: "gpt-5.6",
  input: "And its population?",
  previous_response_id: res1.id,
  store: true,
});

隐藏自定义中间件或防护栏

当你围绕 LLM 或工具调用编写自己的防护栏、策略检查或中间件函数时，用 @traceable 包装它，并在元数据中设置 ls_agent_type: "middleware"。Messages 视图会将这些运行从主对话中过滤掉。

from langsmith import traceable

@traceable(
    run_type="llm",
    metadata={"ls_agent_type": "middleware"},
)
def entry_guardrail(prompt: str) -> dict:
    # 你的防护栏逻辑
    return {"decision": "allow"}

import { traceable } from "langsmith/traceable";

const entryGuardrail = traceable(
  async (prompt: string) => {
    // 你的防护栏逻辑
    return { decision: "allow" };
  },
  { run_type: "llm", metadata: { ls_agent_type: "middleware" } },
);

从 Messages 视图中排除运行

在运行的元数据上设置 LS_MESSAGE_VIEW_EXCLUDE 会告诉 Messages 视图跳过该运行。关键在于键是否存在；True 是约定俗成的值。该过滤器在任何提取策略看到追踪记录之前运行，因此被排除的 LLM 或工具运行永远不会影响检测、消息提取或工具调用配对。 LS_MESSAGE_VIEW_EXCLUDE 是一个从 langsmith（Python 和 JS）导出的顶级常量，其值是字符串 "ls_message_view_exclude"。建议使用常量以避免拼写错误；字面量字符串仍然有效。对于不属于对话轮次的 LLM 子跨度，例如分类调用、嵌入查找、安全过滤器或路由/防护栏决策，可以使用它。你可能仍然希望这些运行在 LangSmith 的其他地方可见，但不希望它们干扰对话记录。

Python
TypeScript

1. 在 @traceable 装饰器上：排除整个函数的运行。

from langsmith import LS_MESSAGE_VIEW_EXCLUDE, traceable

@traceable(run_type="llm", metadata={LS_MESSAGE_VIEW_EXCLUDE: True})
def classify_intent(query: str) -> str:
    # 这个 LLM 调用是内部路由，不是聊天的一部分
    return llm.predict(f"Classify the intent of: {query}")

2. 通过 trace 上下文管理器：排除一个临时跨度。

from langsmith import LS_MESSAGE_VIEW_EXCLUDE, trace

with trace(
    "safety_check",
    run_type="llm",
    metadata={LS_MESSAGE_VIEW_EXCLUDE: True},
) as run:
    result = safety_model.score(text)
    run.end(outputs={"score": result})

3. 在正在运行的函数内部：在运行被修补之前的任何时刻，在当前运行树上设置该键。

from langsmith import LS_MESSAGE_VIEW_EXCLUDE, get_current_run_tree, traceable

@traceable(run_type="llm")
def maybe_internal(query: str) -> str:
    result = llm.predict(query)
    if _looks_like_routing(query):
        rt = get_current_run_tree()
        if rt is not None:
            rt.add_metadata({LS_MESSAGE_VIEW_EXCLUDE: True})
    return result

4. 使用 wrap_openai / wrap_anthropic 时每次调用设置：将 langsmith_extra 传递给包装好的客户端调用。

import openai
from langsmith import LS_MESSAGE_VIEW_EXCLUDE
from langsmith.wrappers import wrap_openai

client = wrap_openai(openai.Client())

resp = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "Classify: ..."}],
    langsmith_extra={"metadata": {LS_MESSAGE_VIEW_EXCLUDE: True}},
)

5. LangChain RunnableConfig：排除对链或聊天模型的单次调用。

from langchain_openai import ChatOpenAI
from langsmith import LS_MESSAGE_VIEW_EXCLUDE

llm = ChatOpenAI(model="gpt-5.6")
result = llm.invoke(
    "Classify this query",
    config={"metadata": {LS_MESSAGE_VIEW_EXCLUDE: True}},
)

1. 在 traceable 包装器上：排除整个函数的运行。

import { LS_MESSAGE_VIEW_EXCLUDE } from "langsmith";
import { traceable } from "langsmith/traceable";

const classifyIntent = traceable(
  async (query: string) => {
    return await llm.predict(`Classify the intent of: ${query}`);
  },
  {
    name: "classify_intent",
    run_type: "llm",
    metadata: { [LS_MESSAGE_VIEW_EXCLUDE]: true },
  },
);

2. 在正在运行的函数内部：修改当前运行树。

import { LS_MESSAGE_VIEW_EXCLUDE } from "langsmith";
import { traceable, getCurrentRunTree } from "langsmith/traceable";

const maybeInternal = traceable(
  async (query: string) => {
    const result = await llm.predict(query);
    if (looksLikeRouting(query)) {
      const rt = getCurrentRunTree();
      rt.extra = rt.extra ?? {};
      rt.extra.metadata = { ...rt.extra.metadata, [LS_MESSAGE_VIEW_EXCLUDE]: true };
    }
    return result;
  },
  { run_type: "llm" },
);

3. 使用 wrapOpenAI 时每次调用设置：在调用中传递 langsmithExtra。

import { LS_MESSAGE_VIEW_EXCLUDE } from "langsmith";
import { wrapOpenAI } from "langsmith/wrappers";
import OpenAI from "openai";

const client = wrapOpenAI(new OpenAI());

const resp = await client.chat.completions.create(
  {
    model: "gpt-5.6",
    messages: [{ role: "user", content: "Classify: ..." }],
  },
  { langsmithExtra: { metadata: { [LS_MESSAGE_VIEW_EXCLUDE]: true } } },
);

4. Vercel AI SDK 中间件：通过 wrapAISDK 上的 lsConfig.metadata 传递该键。中间件会将其合并到每个发出的 LLM 运行中。

import * as ai from "ai";
import { LS_MESSAGE_VIEW_EXCLUDE } from "langsmith";
import { wrapAISDK } from "langsmith/experimental/vercel";

const { generateText } = wrapAISDK(ai, {
  metadata: { [LS_MESSAGE_VIEW_EXCLUDE]: true },
});

若要仅排除某些调用而不排除其他调用，可以正常使用 wrapAISDK 包装，然后转为从调用 AI SDK 的父级 traceable 内部修改 getCurrentRunTree()，或使用带有 createChild({ extra: { metadata: { [LS_MESSAGE_VIEW_EXCLUDE]: true } } }) 的子 RunTree。5. 手动使用 RunTree.createChild：当你手动构建运行时。

import { LS_MESSAGE_VIEW_EXCLUDE } from "langsmith";
import { RunTree } from "langsmith/run_trees";

const parent = new RunTree({ name: "agent", run_type: "chain" });
const child = parent.createChild({
  name: "safety_check",
  run_type: "llm",
  extra: { metadata: { [LS_MESSAGE_VIEW_EXCLUDE]: true } },
});

注意事项

该过滤器检查的是 键是否存在，而不是其真值。{LS_MESSAGE_VIEW_EXCLUDE: false} 仍然会排除该运行。要包含运行，请完全省略该键。
在 @traceable（Python）或 traceable（JS）父级内执行的子运行，会通过共享的追踪上下文继承排除设置：Python 的 _METADATA ContextVar 和 JS 的 AsyncLocalStorage。子级自身的装饰器时元数据会层叠在继承的值之上。
被排除的运行仍然会出现在常规追踪视图、运行浏览器和指标中。只有 Messages 视图会将其过滤掉。

手动插桩

如果你使用的是支持的集成之外的包装器进行追踪（例如，通过 RunTree、REST API 或围绕提供商 SDK 的自定义包装器发出运行），请在每个 LLM 运行的元数据上设置 ls_message_format，以将追踪记录路由到正确的提取器：

追踪形状	设置的元数据
LangChain 消息 (构造函数信封)	`ls_message_format: "langchain"`
OpenAI Chat Completions	`ls_message_format: "completions"`
OpenAI Responses API	`ls_message_format: "responses"`
Anthropic Messages API	`ls_message_format: "anthropic"`

Viewing & managing traces

Bulk export trace data

Messages view

Data type reference

支持的集成

链式调用模式下的 OpenAI Responses API

每次调用时设置元数据

初始化时设置元数据

隐藏自定义中间件或防护栏

从 Messages 视图中排除运行

注意事项

手动插桩

相关内容

​支持的集成

​链式调用模式下的 OpenAI Responses API

​每次调用时设置元数据

​初始化时设置元数据

​隐藏自定义中间件或防护栏

​从 Messages 视图中排除运行

​注意事项

​手动插桩

​相关内容

支持的集成

链式调用模式下的 OpenAI Responses API

每次调用时设置元数据

初始化时设置元数据

隐藏自定义中间件或防护栏

从 Messages 视图中排除运行

注意事项

手动插桩

相关内容