使用 SDK 查询线程

如果你正在构建对话代理或任何多轮应用，LangSmith 会自动将你的运行分组为线程。查询线程可以让你重放完整对话、跨会话审计代理行为、构建关于对话长度和延迟的分析，并为微调和评估等下游工作流提供数据。 SDK 提供了两种处理线程的方法：

方法	使用场景
`list_threads` / `listThreads`	你想浏览项目中的所有线程
`read_thread` / `readThread`	你已知线程 ID 并需要其运行数据

线程的工作原理

你创建的每个运行都可以在其元数据中携带一个 thread_id。LangSmith 使用此 ID 将运行分组为线程。后端会在 metadata 中查找 thread_id（如果找不到，则回退到 session_id 或 conversation_id）。

我们建议使用 UUID v7 作为线程 ID。UUIDv7 嵌入了时间戳，这可以保持线程正确的时间顺序。LangSmith SDK 导出了一个 uuid7 辅助函数（Python v0.4.43+，JS v0.3.80+）：

Python: from langsmith import uuid7
JS/TS: import { uuid7 } from 'langsmith'

如果你使用的是追踪集成，请在运行元数据中传递 thread_id：

from langsmith import traceable, uuid7

THREAD_ID = str(uuid7())

@traceable(metadata={"thread_id": THREAD_ID})
def my_agent(user_message: str) -> str:
    ...

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

const THREAD_ID = uuid7();

const myAgent = traceable(
  async (userMessage: string) => {
    // ...
  },
  { metadata: { thread_id: THREAD_ID } }
);

列出项目中的所有线程

list_threads / listThreads 获取项目中的所有线程，并将它们的运行数据分组在一起。结果按最近活动时间排序。

from langsmith import Client

client = Client()

threads = client.list_threads(project_name="my-project")

for thread in threads:
    print(thread["thread_id"])
    print(f"  {thread['count']} runs")
    print(f"  last active: {thread['max_start_time']}")

import { Client } from "langsmith";

const client = new Client();

const threads = await client.listThreads({ projectName: "my-project" });

for (const thread of threads) {
  console.log(thread.thread_id);
  console.log(`  ${thread.count} runs`);
  console.log(`  last active: ${thread.max_start_time}`);
}

结果按最近活动时间排序：

Output

conv-abc123
  3 runs
  last active: 2026-02-25T10:05:42+00:00
conv-def456
  1 runs
  last active: 2026-02-25T09:30:00+00:00

参数

参数	类型	默认值	描述
`project_name` / `projectName`	`string`	—	项目名称。如果未设置 `project_id`，则此项为必填。
`project_id` / `projectId`	`string`	—	项目 ID。如果未设置 `project_name`，则此项为必填。
`limit`	`int`	全部	要返回的最大线程数。
`offset`	`int`	`0`	要跳过的线程数（用于分页）。
`filter`	`string`	—	获取运行时应用的过滤表达式，使用 LangSmith 追踪查询语法。
`start_time` / `startTime`	`datetime` / `Date`	1 天前	仅包含在此时间之后开始的运行。扩大此时间窗口以显示更早的线程。

返回值

一个线程对象列表，每个对象包含：

字段	类型	描述
`thread_id`	`string`	线程标识符。
`runs`	`[Run](https://reference.langchain.com/python/langsmith/schemas/Run)[]`	此线程中的根运行，按时间顺序排序（最早在前）。
`count`	`int`	此线程中的运行数量。
`min_start_time`	`string \| null`	最早运行的 ISO 时间戳。
`max_start_time`	`string \| null`	最近运行的 ISO 时间戳。

list_threads 始终只返回根运行。如果你需要子运行（例如，工具调用、子链），请改用 read_thread，它接受一个 is_root / isRoot 参数，你可以将其设置为 false。

读取单个线程的运行数据

当你已知 thread_id 时，使用 read_thread / readThread。它直接返回线程运行数据的迭代器，无需先获取所有线程。

from langsmith import Client

client = Client()

for run in client.read_thread(
    thread_id="conv-abc123",
    project_name="my-project",
):
    print(run.id, run.name, run.start_time)

import { Client } from "langsmith";

const client = new Client();

for await (const run of client.readThread({
  threadId: "conv-abc123",
  projectName: "my-project",
})) {
  console.log(run.id, run.name, run.start_time);
}

与 list_threads 不同，这里的每个项目都是一个 Run 对象本身——没有分组包装器。默认情况下，运行按时间升序返回。

Output

[
    Run(id=UUID("a1b2..."), name="my_agent", run_type="chain", status="success", start_time=datetime(2026, 2, 25, 10, 0, 0, tzinfo=utc), ...),
    Run(id=UUID("c3d4..."), name="my_agent", run_type="chain", status="success", start_time=datetime(2026, 2, 25, 10, 3, 11, tzinfo=utc), ...),
    Run(id=UUID("e5f6..."), name="my_agent", run_type="chain", status="error",   start_time=datetime(2026, 2, 25, 10, 5, 42, tzinfo=utc), ...),
]

参数

参数	类型	默认值	描述
`thread_id` / `threadId`	`string`	—	必填。要查询的线程。
`project_name` / `projectName`	`string`	—	项目名称。如果未设置 `project_id`，则此项为必填。
`project_id` / `projectId`	`string \| string[]`	—	项目 ID 或 ID 列表。如果未设置 `project_name`，则此项为必填。
`is_root` / `isRoot`	`bool`	`true`	仅返回根运行。设置为 `false` 以包含子运行。
`limit`	`int`	全部	要返回的最大运行数。
`filter`	`string`	—	附加过滤表达式（与线程过滤器组合）。
`order`	`"asc" \| "desc"`	`"asc"`	排序顺序。`"asc"` 按时间升序返回运行（最早在前）。
`select`	`string[]`	所有字段	要返回的特定运行字段，以减小响应大小。

返回值

一个 Run 对象的迭代器（Python）或异步迭代器（TypeScript）。

示例

按运行属性过滤线程

传递过滤表达式以使用 LangSmith 追踪查询语法缩小结果范围。例如，仅显示包含至少一个失败运行的线程：

threads = client.list_threads(
    project_name="my-project",
    filter='eq(status, "error")',
)

const threads = await client.listThreads({
  projectName: "my-project",
  filter: 'eq(status, "error")',
});

回溯超过 24 小时

默认情况下，list_threads 仅显示过去一天内有运行的线程。传递 start_time 以扩大时间窗口：

import datetime

threads = client.list_threads(
    project_name="my-project",
    start_time=datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=2),
)

const threads = await client.listThreads({
  projectName: "my-project",
  startTime: new Date(Date.now() - 2 * 24 * 60 * 60 * 1000),
});

重建对话

使用 read_thread 并设置 order="asc" 以逐轮重放对话：

runs = list(
    client.read_thread(
        thread_id="conv-abc123",
        project_name="my-project",
        order="asc",
    )
)

for run in runs:
    user_msg = run.inputs.get("messages", [{}])[-1].get("content", "")
    assistant_msg = (run.outputs or {}).get("content", "")
    print(f"User:      {user_msg}")
    print(f"Assistant: {assistant_msg}")
    print()

const runs: Run[] = [];
for await (const run of client.readThread({
  threadId: "conv-abc123",
  projectName: "my-project",
  order: "asc",
})) {
  runs.push(run);
}

for (const run of runs) {
  const messages = (run.inputs?.messages ?? []) as Array<Record<string, string>>;
  const userMsg = messages.at(-1)?.content ?? "";
  const assistantMsg = (run.outputs as Record<string, string>)?.content ?? "";
  console.log(`User:      ${userMsg}`);
  console.log(`Assistant: ${assistantMsg}`);
}

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

Tracing setup

Configuration & troubleshooting

Viewing & managing traces

Automations

Feedback & evaluation

Monitoring & alerting

Data type reference

线程的工作原理

列出项目中的所有线程

参数

返回值

读取单个线程的运行数据

参数

返回值

示例

按运行属性过滤线程

回溯超过 24 小时

重建对话

​线程的工作原理

​列出项目中的所有线程

​参数

​返回值

​读取单个线程的运行数据

​参数

​返回值

​示例

​按运行属性过滤线程

​回溯超过 24 小时

​重建对话

线程的工作原理

列出项目中的所有线程

参数

返回值

读取单个线程的运行数据

参数

返回值

示例

按运行属性过滤线程

回溯超过 24 小时

重建对话