---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - agent-server
  - runs
  - streaming
topic: LangSmith Agent Server Stateful 与 Stateless Runs API
sources:
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/cancel-run
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/cancel-runs
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/create-background-run
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/create-run-stream-output
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/create-run-wait-for-output
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/delete-run
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/get-run
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/join-run
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/join-run-stream
  - https://docs.langchain.com/langsmith/agent-server-api/thread-runs/list-runs
  - https://docs.langchain.com/langsmith/agent-server-api/stateless-runs
  - https://docs.langchain.com/langsmith/agent-server-api/stateless-runs/create-background-run
  - https://docs.langchain.com/langsmith/agent-server-api/stateless-runs/create-run-batch
  - https://docs.langchain.com/langsmith/agent-server-api/stateless-runs/create-run-stream-output
  - https://docs.langchain.com/langsmith/agent-server-api/stateless-runs/create-run-wait-for-output
last_verified: 2026-08-11
---

# Stateful 与 Stateless Runs

Run 是一次 graph/Assistant 调用。Stateful Run 绑定 Thread 并更新其 state；Stateless Run 没有跨调用状态/记忆持久化。两者都提供 background、stream、wait 三种消费方式，不能把响应方式和持久化方式混为一谈。

## Stateful Run 端点

| 能力 | 方法与路径 | 语义 |
|---|---|---|
| 列表 | `GET /threads/{thread_id}/runs` | 根文档与 list 页同一操作 |
| Background | `POST /threads/{thread_id}/runs` | 立即返回 Run ID |
| Stream | `POST /threads/{thread_id}/runs/stream` | 创建并实时流式返回 |
| Wait | `POST /threads/{thread_id}/runs/wait` | 等到最终输出后返回 |
| 读取/删除 | `GET`、`DELETE /threads/{thread_id}/runs/{run_id}` | 200/404 |
| Join | `GET .../{run_id}/join` | 等已有 Run 完成 |
| Join stream | `GET .../{run_id}/stream` | 加入已有 Run 的输出流；resumable 时可从最后事件恢复 |
| 取消一个 | `POST .../{run_id}/cancel` | 请求取消 |
| 批量取消 | `POST /runs/cancel` | 成功 204；按状态或 thread+run IDs 二选一 |

## Stateless Run 端点

| 能力 | 方法与路径 | 语义 |
|---|---|---|
| Stream | `POST /runs/stream` | 根文档与 stream 页同操作 |
| Background | `POST /runs` | 立即返回 Run ID |
| Wait | `POST /runs/wait` | 等最终结果 |
| Batch | `POST /runs/batch` | 批量创建后立即返回 |

所有创建操作可能返回 Assistant/Thread 不存在 404、并发/重复 409、结构错误 422。网络超时后先用 Run ID、Thread 列表或业务幂等键核对，不能盲目重建。

## 创建请求的公共契约

必填 `assistant_id`（也可按文档允许的 graph 名称形态）；可传 input 或 `Command`、metadata、graph config、runtime context、webhook、interrupt before/after、stream mode、是否含 subgraphs、是否 resumable、feedback keys、延迟秒数与 durability。

stream modes 包括 values、messages/messages-tuple、tasks、checkpoints、updates、events、debug、custom。业务 UI 应只订阅需要的模式，避免 debug/完整 state 泄露内部数据。

Durability：

- `sync`：每步继续前同步持久化，恢复最强、延迟最高；
- `async`（默认）：与下一步并行持久化，折中；
- `exit`：Run 退出时持久化，吞吐优先、故障时可能丢失中间进度。

`checkpoint_during` 与 durability 共同影响中间 checkpoint；生产选择要由副作用可重放性、RPO 和延迟 SLO 决定。

## Stateful 并发策略

同一 Thread 已有 Run 时，`multitask_strategy` 决定新 Run：

- `reject`：拒绝新 Run；
- `enqueue`（默认）：排队；
- `interrupt`：中断已有 Run；
- `rollback`：回滚已有 Run 的写入后执行新 Run。

`if_not_exists` 为 `create` 或默认 `reject`，控制 Thread 不存在时是否自动创建。自动创建方便，但会绕开应用自己的 Thread metadata/owner 初始化；多租户系统通常应先显式创建并授权。

Stateless Run 有 `on_completion=delete|keep`，决定临时 Thread/执行记录的保留；它不等于完全无审计，Trace、Run 元数据和平台日志仍可能存在。

## Run 状态与取消

Run 状态：`pending`、`running`、`error`、`success`、`timeout`、`interrupted`。响应还带 run/thread/assistant IDs、时间、metadata、kwargs、多任务策略和可空的 LangSmith tracing project 名。

批量取消请求要么传 status（pending/running/all），要么同时传 thread ID 与 run IDs。取消是请求，不证明外部副作用已撤销；发送邮件、支付、写库等工具必须自己实现幂等/补偿。

## 流式、重连与可靠交付

- Background 适合任务队列；保存 Run ID，再用 get/join/stream 观察。
- Wait 简单但容易受到网关超时；只用于可控短任务。
- Stream 提升体验，但连接中断不代表 Run 停止；`stream_resumable=true` 后用最后事件 ID 加入已有流。
- webhook 必须签名验证、幂等消费、快速响应并异步处理；payload 不能成为越权回调或 SSRF 入口。
- batch 需要逐项状态、失败重放和并发配额，不能把 HTTP 200 当全批成功。