Skip to main content
如果你正在构建对话代理或任何多轮应用，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:
    ...

​
列出项目中的所有线程

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']}")
结果按最近活动时间排序：
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 / projectNamestring—项目名称。如果未设置 project_id，则此项为必填。
project_id / projectIdstring—项目 ID。如果未设置 project_name，则此项为必填。
limitint全部要返回的最大线程数。
offsetint0要跳过的线程数（用于分页）。
filterstring—获取运行时应用的过滤表达式，使用 LangSmith 追踪查询语法。
start_time / startTimedatetime / Date1 天前仅包含在此时间之后开始的运行。扩大此时间窗口以显示更早的线程。

​
返回值

一个线程对象列表，每个对象包含：
字段类型描述
thread_idstring线程标识符。
runs[Run](https://reference.langchain.com/python/langsmith/schemas/Run)[]此线程中的根运行，按时间顺序排序（最早在前）。
countint此线程中的运行数量。
min_start_timestring | null最早运行的 ISO 时间戳。
max_start_timestring | 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)
与 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 / threadIdstring—必填。 要查询的线程。
project_name / projectNamestring—项目名称。如果未设置 project_id，则此项为必填。
project_id / projectIdstring | string[]—项目 ID 或 ID 列表。如果未设置 project_name，则此项为必填。
is_root / isRootbooltrue仅返回根运行。设置为 false 以包含子运行。
limitint全部要返回的最大运行数。
filterstring—附加过滤表达式（与线程过滤器组合）。
order"asc" | "desc""asc"排序顺序。"asc" 按时间升序返回运行（最早在前）。
selectstring[]所有字段要返回的特定运行字段，以减小响应大小。

​
返回值

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

​
示例

​
按运行属性过滤线程

传递过滤表达式以使用 LangSmith 追踪查询语法缩小结果范围。例如，仅显示包含至少一个失败运行的线程： 
threads = client.list_threads(
    project_name="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),
)

​
重建对话

使用 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()
将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。