Agent Server 运行时与状态语义

核心对象

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 成功等同于生产授权完成。