Api Idempotency

幂等与重试

所有 mutating Capability 都需要 Idempotency-Key。客户端为一次用户意图生成随机 key；网络超时后以相同 key 重试，同一个 key 不可复用于另一项业务意图。

POST /api/v1/agent/runs
Authorization: Bearer sp_...
Idempotency-Key: 5f4b6f5e-7ae2-4a2b-a6b1-1b5b5295e62d
Content-Type: application/json

一般 /api/v1 写操作按“调用者 + key”缓存首次成功响应 24 小时；并发使用同一 key 时，后到请求收到 409 request.concurrent_request。当前通用幂等层不比较请求 body，因此客户端必须保证同一 key 只重试原始请求，不能把它用于另一项操作。

POST /api/v1/agent/runs 额外保存请求 hash：同 key 但参数不同返回 409 agent.idempotency_conflict。Partner API 也按 partner + key 缓存成功响应，不校验请求体。

客户端只在可安全重试的网络/5xx 情况下重试；4xx 必须由用户或调用方修正请求后产生新的业务意图和 key。