---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags: [langchain, langsmith, agent-server, runtime, persistence]
topic: Agent Server 运行时、状态、流式与并发语义
sources:
  - "https://docs.langchain.com/langsmith/agent-server"
  - "https://docs.langchain.com/langsmith/agent-server-distributed-tracing"
  - "https://docs.langchain.com/langsmith/agent-server-feedback"
  - "https://docs.langchain.com/langsmith/agent-server-scale"
  - "https://docs.langchain.com/langsmith/application-structure"
  - "https://docs.langchain.com/langsmith/assistants"
  - "https://docs.langchain.com/langsmith/cancel-run"
  - "https://docs.langchain.com/langsmith/configurable-headers"
  - "https://docs.langchain.com/langsmith/configurable-logs"
  - "https://docs.langchain.com/langsmith/configuration-cloud"
  - "https://docs.langchain.com/langsmith/configure-checkpointer"
  - "https://docs.langchain.com/langsmith/configure-ttl"
  - "https://docs.langchain.com/langsmith/cron-jobs"
  - "https://docs.langchain.com/langsmith/custom-checkpointer"
  - "https://docs.langchain.com/langsmith/custom-lifespan"
  - "https://docs.langchain.com/langsmith/custom-middleware"
  - "https://docs.langchain.com/langsmith/custom-routes"
  - "https://docs.langchain.com/langsmith/custom-store"
  - "https://docs.langchain.com/langsmith/double-texting"
  - "https://docs.langchain.com/langsmith/enqueue-concurrent"
  - "https://docs.langchain.com/langsmith/env-var-self-hosted"
  - "https://docs.langchain.com/langsmith/generative-ui-react"
  - "https://docs.langchain.com/langsmith/graph-rebuild"
  - "https://docs.langchain.com/langsmith/human-in-the-loop-time-travel"
  - "https://docs.langchain.com/langsmith/interrupt-concurrent"
  - "https://docs.langchain.com/langsmith/reject-concurrent"
  - "https://docs.langchain.com/langsmith/remote-graph"
  - "https://docs.langchain.com/langsmith/rollback-concurrent"
  - "https://docs.langchain.com/langsmith/runs"
  - "https://docs.langchain.com/langsmith/same-thread"
  - "https://docs.langchain.com/langsmith/self-hosted-agent-server-metrics"
  - "https://docs.langchain.com/langsmith/server-api-ref"
  - "https://docs.langchain.com/langsmith/stateless-runs"
  - "https://docs.langchain.com/langsmith/streaming"
  - "https://docs.langchain.com/langsmith/threads"
  - "https://docs.langchain.com/langsmith/use-threads"
  - "https://docs.langchain.com/langsmith/use-tools"
  - "https://docs.langchain.com/langsmith/use-webhooks"
last_verified: 2026-08-11
---

# Agent Server 运行时与状态语义

## 核心对象

```text
Graph（代码与拓扑）
  └─ Assistant（Graph + 可版本化配置）
       └─ Run（一次执行）
Thread（持久状态容器） ───────────┘
```

- Graph 从 `langgraph.json` 加载；每个 Graph 自动生成一个默认 Assistant。
- Assistant 将模型、Prompt、工具等运行配置与 Graph 结构分离，同一 Graph 可有多个版本化 Assistant。
- Thread 不绑定某个 Assistant，同一 Thread 可先后由不同 Assistant 运行；后一个会看到前一个写入的 checkpoint。
- Run 是 Assistant 的一次调用。不给 `thread_id` 时是 Stateless Run，不保存跨调用状态。
- 这些 Assistant/Thread/Run 概念属于 LangSmith Deployment，不是 LangGraph OSS 本身的服务端对象。

## 持久化分层

| 数据 | 默认后端 | 可替换性 | 重要边界 |
| --- | --- | --- | --- |
| Thread/Run/Assistant/Cron/Store 元数据 | PostgreSQL | PostgreSQL 始终必需 | 不能因切换 Checkpointer 就移除 PostgreSQL |
| Checkpoint/Graph state | PostgreSQL | MongoDB 或自定义 Checkpointer | Mongo 仅替代 checkpoint 存储 |
| 长期记忆 Store | PostgreSQL/pgvector | 自定义 BaseStore（alpha） | 自定义后端需自行实现搜索、TTL 等能力 |
| 队列、心跳、流事件 | Redis | 可换自管 Redis/Valkey | 是临时状态，但影响可用性 |

自定义 Checkpointer 和 Store 都通过异步上下文管理器交给 Server 管生命周期。两者处于 alpha，次版本可能破坏兼容；生产采用前必须跑 conformance suite、容量/恢复/TTL 验证，并准备回退到默认后端。

## Run 与“重复发消息”策略

同一 Thread 的前一个 Run 未完成时，新请求称为 double texting：

| 策略 | 第一个 Run | 第二个 Run | 数据语义 |
| --- | --- | --- | --- |
| `enqueue`（默认） | 完成 | 排队后执行 | 顺序最稳定，延迟更高 |
| `reject` | 继续 | 立即失败 | 适合严格单飞与客户端重试控制 |
| `interrupt` | 标记 `interrupted` | 从已保留进度继续 | Run/Checkpoint 仍可审计；需处理半完成 Tool Call |
| `rollback` | 完全删除且不可恢复 | 从回滚后的状态重新执行 | 破坏性最高，不适合需审计的流程 |

取消单个 Run 也有 `interrupt`、`rollback`、`wait` 三种行为。只允许取消 `pending` 或 `running`；批量取消可按 Thread/Run ID 或状态。前端断连自动取消要谨慎，因为后台任务可能本应继续。

## Streaming 与恢复

运行流支持 `updates`（节点增量）、`values`（完整状态）、LLM token、custom、events、debug、subgraph 等模式，可组合多个 mode。Thread stream 与 Run stream 不同：Thread stream 可跨 Run，断线后用最后 event ID 恢复；`RESUMABLE_STREAM_TTL_SECONDS` 决定事件可重放窗口。

- 长 Run 不应靠轮询；使用 `join`/`join_stream`。
- Cloud API 连接最长约 1 小时，但后台 Run 可以更久；客户端需重连 join stream。
- Distributed tracing 通过 `langsmith-trace` 与 `langsmith-project` 头传播。只把允许的头加入 `http.configurable_headers`，避免将 Cookie/Authorization 无差别注入 Graph config。
- Server 默认不记录请求头。仅显式 allowlist correlation/request ID；日志 `excludes` 优先于 `includes`。

## TTL 与删除

`langgraph.json` 可分别配置 Thread/Checkpoint 与 Store item TTL，并支持每 Thread/runtime override。`delete` 策略会删除 Thread 及相关 Run/Checkpoint；`keep_latest` 类策略则保留最近状态。上线前必须用测试 Thread 验证实际清理范围。

高吞吐删除可启用延迟 Checkpoint 删除队列，但当前仅支持默认 PostgreSQL Checkpointer。回滚配置时先用 worker-only 模式排空队列，避免遗留删除任务。

## 容量模型

- Request concurrency：API Server 异步处理 HTTP，主要靠 API 副本水平扩展。
- Run concurrency：`queue_workers × N_JOBS_PER_WORKER`；模型/工具是 I/O 密集时可更高，CPU/内存密集时必须下调。
- `BG_JOB_ISOLATED_LOOPS` 只能把同步阻塞移出 API event loop，并没有消除阻塞；根治应使用 async SDK/driver 或精确 `to_thread`。
- 启用 isolated loop 后，每个 Worker 有独立 PostgreSQL pool，单 Worker pool 约为 `LANGGRAPH_POSTGRES_POOL_MAX_SIZE / N_JOBS_PER_WORKER`；调大并发却不扩 DB 连接会制造连接饥饿。
- 读负载优先过滤、分页、TTL 与 join；写负载减少冗余 checkpoint，并让 Queue Worker 独立扩展。

自托管可从 `/metrics` 导出 OTel/Prometheus 指标，也可推送 Datadog。监控至少覆盖 queue wait、Run duration/status/retry、stream disconnect、API latency/error、PostgreSQL pool、Redis connection 和 sweeper requeue。

## 扩展 HTTP 运行时

- Custom route：Python 可挂 Starlette/FastAPI，TypeScript 可挂 Hono；不要遮蔽内置 `/threads`、`/runs` 等路径。
- Middleware：Python 需要 `langgraph-api>=0.0.26`；默认先于认证执行，API Server `>=0.4.35` 可设 `auth_first`。鉴权后才能使用用户身份的逻辑应选择后者。
- Lifespan：目前仅 Python，用于初始化/关闭连接池等资源；启动失败要 fail fast，关闭需可重复。
- Graph rebuild：`ServerRuntime` 允许按 Run 重新构图，但一般优先在节点内按 config 分支，减少难测的动态拓扑。
- Generative UI：组件与 Graph 共置并流式发送 UI 消息；客户端仍需把组件输入当不可信数据，不能让 Agent 生成任意可执行脚本。

## 定时、回调与反馈

- Cron 使用 UTC，既可绑定 Thread 也可 Stateless；不用的 Cron 必须删除，否则会持续产生模型费用。Stateless Cron 若保留 Thread，要配合清理策略。
- Webhook 在 Run 完成时 POST。生产应使用 HTTPS、签名/自定义认证头、目标 allowlist 和幂等 event/run ID；不要允许用户提供任意内网 URL，以免 SSRF。
- `feedback_keys` 会返回预签名反馈 URL，前端可直接提交评分。URL 应短时使用、不要写日志；高基数原始反馈应归一成稳定 key。
- Playground Tool registry 是 Workspace 级复用资源；内置与自定义工具都需最小权限与人工审查，不能把 Playground 成功等同于生产授权完成。