学习笔记 · Obsidian
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 当全批成功。