Thread
Thread 只接受 metadata。使用 GET/PATCH/DELETE /v1/threads/{thread_id} 读取、替换 metadata 或删除;删除同时清理可用 checkpointer 中的 thread checkpoint。
状态接口:
Fork body 为 {"checkpoint_id":"...","values":{},"as_node":"..."};字段均可选。响应是新 lineage 的 runtime config。
创建 Run
无状态执行使用 POST /v1/runs,body 相同但不产生 thread checkpoint lineage。
Idempotency-Key 长度 1–255,在 tenant 内唯一。同 key + 同请求返回原 run;同 key + 不同请求返回 409 idempotency_conflict。
查询与等待
join 的 timeout 必须大于 0 且不超过 300 秒。尚未到达 terminal/paused 时返回 408 join_timeout,客户端可继续请求。
取消、恢复与 redrive
- cancel 是协作式请求,通常先返回
cancelling;节点和 provider 应响应 cancellation token;
- 只有
paused run 可 resume;响应是新 run,metadata.resumed_from_run_id 指向原 run;
- 只有
failed 或 dead_letter 可 redrive;保留原 input/config/version 并重新入队。
Redrive 不是“修改输入后重试”。业务输入或 graph version 改变时应创建新 run,并使用新的幂等键。