---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - agent-server
  - threads
  - persistence
topic: LangSmith Agent Server Threads API
sources:
  - https://docs.langchain.com/langsmith/agent-server-api/threads
  - https://docs.langchain.com/langsmith/agent-server-api/threads/copy-thread
  - https://docs.langchain.com/langsmith/agent-server-api/threads/count-threads
  - https://docs.langchain.com/langsmith/agent-server-api/threads/create-thread
  - https://docs.langchain.com/langsmith/agent-server-api/threads/delete-thread
  - https://docs.langchain.com/langsmith/agent-server-api/threads/get-thread
  - https://docs.langchain.com/langsmith/agent-server-api/threads/get-thread-history
  - https://docs.langchain.com/langsmith/agent-server-api/threads/get-thread-history-post
  - https://docs.langchain.com/langsmith/agent-server-api/threads/get-thread-state
  - https://docs.langchain.com/langsmith/agent-server-api/threads/get-thread-state-at-checkpoint
  - https://docs.langchain.com/langsmith/agent-server-api/threads/get-thread-state-at-checkpoint-1
  - https://docs.langchain.com/langsmith/agent-server-api/threads/join-thread-stream
  - https://docs.langchain.com/langsmith/agent-server-api/threads/patch-thread
  - https://docs.langchain.com/langsmith/agent-server-api/threads/prune-threads
  - https://docs.langchain.com/langsmith/agent-server-api/threads/search-threads
  - https://docs.langchain.com/langsmith/agent-server-api/threads/update-thread-state
last_verified: 2026-08-11
---

# Threads：状态、Checkpoint 与生命周期

Thread 是一组 stateful Runs 的持久容器，保存累计 state、interrupts 与 checkpoint 历史。Assistant 描述“运行什么”，Thread 描述“这段会话执行到哪里”。

## 资源与查询端点

| 能力 | 方法与路径 | 说明 |
|---|---|---|
| 创建 | `POST /threads` | 200；自定义 ID 冲突 409；根文档与 create 页同操作 |
| 读取/删除 | `GET`、`DELETE /threads/{thread_id}` | 不存在 404 |
| Patch | `PATCH /threads/{thread_id}` | 更新 metadata 与 TTL |
| Copy | `POST /threads/{thread_id}/copy` | 复制 Thread，目标冲突 409 |
| 搜索/计数 | `POST /threads/search`、`POST /threads/count` | 按 ID、metadata、state values、status 过滤 |
| 批量 prune | `POST /threads/prune` | 对 thread IDs 应用 `delete` 或 `keep_latest` |
| Join thread stream | `GET /threads/{thread_id}/stream` | 加入 Thread 级事件流 |

`Thread` 状态枚举是 `idle`、`busy`、`interrupted`、`error`。返回还包含创建/更新时间、state 更新时间、metadata、config、values、interrupts；只有请求包含相应信息时才返回 TTL/extracted 等扩展字段。

## 创建、幂等与 TTL

`ThreadCreate` 可传 `thread_id`、metadata、TTL 和预置 supersteps。`if_exists` 为 `raise`（默认）或 `do_nothing`。supersteps 由一组 update 组成，可携带 values/command 和 `as_node`，属于状态导入能力，不能接受未校验的客户端任意节点名。

TTL 使用分钟数与策略：

- `delete`：到期删除 Thread；
- `keep_latest`：清理历史但保留最新状态。

Patch 可调整 metadata/TTL；prune 可对多个 Thread 立即应用相同策略。TTL 不是数据治理的完整替代：还要定义备份、审计、用户删除、legal hold 与 Store 中跨 Thread 数据的生命周期。

## State 与 checkpoint 端点

| 能力 | 方法与路径 | 差异 |
|---|---|---|
| 当前 state | `GET /threads/{id}/state` | 返回当前 values、next、tasks、checkpoint、interrupts |
| 按 checkpoint ID | `GET /threads/{id}/state/{checkpoint_id}` | URL 中直接指定 ID |
| 按 checkpoint config | `POST /threads/{id}/state/checkpoint` | body 带 thread/checkpoint namespace/ID/map，可请求 subgraphs |
| 历史简表 | `GET /threads/{id}/history` | 直接获取历史 |
| 历史查询 | `POST /threads/{id}/history` | `limit`、before、metadata、checkpoint 过滤 |
| 更新 state | `POST /threads/{id}/state` | values、目标 checkpoint、`as_node` |

`ThreadState` 的核心字段是 `values`、下一节点列表 `next`、tasks、checkpoint config、metadata、created_at、parent checkpoint 与 interrupts。checkpoint config 由 `thread_id`、`checkpoint_ns`、可选 checkpoint ID/map 组成。

`update state` 会“仿佛某个节点刚执行完”写入更新，服务端返回新 checkpoint。它不是普通 CRUD：reducer、下一节点与 time travel 都可能改变。生产后台必须限制可写字段和 `as_node`，并在写前记录旧 checkpoint，避免越权改写会话或跳过审批节点。

## Search 与投影

搜索支持 status、metadata、state values、IDs，分页默认 10；排序字段含 thread/status/created/updated/state_updated 时间。`select` 可裁剪返回字段。`extract` 最多定义 10 个 alias→JSONB path，路径必须从 values、metadata、config 或 interrupts 开始，例如抽取最后消息；它适合列表投影，不替代 schema 校验。

## 一致性与安全

- 一个 Thread 同时只有一种明确的多任务策略；不要让多个调用方绕过 Run 的并发控制直接更新 state。
- copy/time travel 产生分支后保存源 Thread、源 checkpoint 与新 Thread ID，防止审计链断裂。
- 恢复 interrupt 要从 checkpoint 继续，不要用新 HumanMessage 覆盖未完成 tool call。
- metadata/values 的过滤必须自动叠加租户/owner 条件，不能相信客户端传入 owner。
- 删除、prune、TTL 和 state mutation 均是高风险操作，应提供 dry-run/确认、审计和可恢复窗口。