重试
重试传输问题，不要重试契约真相
好的重试策略能帮助 runtime 穿过暂时性故障，但不会把校验或权限问题伪装成模型可以无限循环解决的事情。
Format: AI-first docs
Source: DocsAgentsRetriesPage
注意
恢复策略应该按 machine-readable type 分支。
当契约已经告诉你失败类型时，runtime 应该决定是重试、重配，还是停止。
重试设计支柱
让重试保持有边界、typed，并留在模型循环之外。
分类
先判断失败是暂时性的，还是终止性的。
- 对超时、部分 5xx 和限流谨慎重试。
- 不要对非法请求做无修改重试。
- 除非凭证已变，否则不要重试 auth 失败。
退避
让重试拥有有边界、可观测的延迟策略。
- 使用带 jitter 的指数退避。
- 服务端有 `Retry-After` 时优先尊重。
- 限制最大尝试次数，避免把失败藏起来。
隔离
把重试留在 runtime adapter，而不是交给推理循环。
- 模型不应该猜自己要不要重放同一请求。
- 重试耗尽后返回分类后的最终失败。
- 记录尝试次数和分支原因。
先把可重试失败和终止性失败分开
不是每一个失败调用都值得再试一次。runtime 应该先完成传输、限流、校验和权限类失败的分类。
- 把 validation 和 missing-field 视为 payload 工作。
- 把 permission 和 auth 视为能力配置工作。
- 只有在未来可能成功的失败，才应该进入重试。
让重试行为始终有边界、可检查
重试策略应该让系统更安全，而不是更神秘。这意味着明确的上限、日志和 typed branch 规则。
- 记录每次重试期间看到的 type 和 status。
- 达到上限后，把终止失败明确抛给运维层。
- 对同一 API 的多个工具保持一致策略。
重试对比
用这张表判断下一次尝试是否负责任。
| 失败类别 | 默认动作 | 原因 |
|---|---|---|
| 超时 / 瞬时 5xx | 使用有边界退避重试。 | 它未来可能在不改输入的前提下成功。 |
| Validation / 缺字段 | 停止并修正请求。 | 重复发送同一 payload 只会得到同样失败。 |
| Auth / Forbidden | 停止并重新配置 credentials 或 scopes。 | runtime 需要的是新能力，而不是下一次尝试。 |
决策矩阵
当线上请求失败时，可以按下面的方式选择恢复路径。
情况
收到 `rate_limit.exceeded`
动作
等待；如果有 `Retry-After` 就尊重它，再做有边界的退避重试。
原因
这种请求未来可能在不改输入的情况下成功。
情况
收到 validation 类型错误
动作
先停止，再修改 payload 或补齐字段。
原因
传输层重试无法修复一个坏请求。
情况
收到 auth 或 forbidden 类型错误
动作
把它视为 runtime 配置问题。
原因
凭证和 scopes 属于 runtime 边界，而不是模型。
代表性失败分支
让 runtime 按这些 typed envelope 安全控制重试。
可重试分支
1
{2
"error": "Rate limit exceeded",3
"type": "rate_limit.exceeded"4
}终止分支
1
{2
"error": "Missing required field: targetRole",3
"type": "career_prediction.missing_target_role"4
}下一步
重试清楚之后，再去设计异步续跑和端点级错误覆盖。