Circuit Breaker、降级与 HITL

1. 为什么这组知识要一起学

把 Timeout、Retry、Idempotency、限流、降级、HITL 与 Guardrails 组织成统一的运行时可靠性控制面。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

可靠性不是“所有失败都重试”，而是为每种失败定义 deadline、可重放性、恢复边界与人工介入策略。

Call → Deadline/Rate Policy → Execute → Classify Failure → Retry/Degrade/Interrupt/Fail → Persist Decision

3. 核心机制

Circuit Breaker

持续下游故障时 circuit breaker 快速失败；degradation 可用 cache/备用 provider/partial result/human input 保留部分价值。

Graceful Degradation

持续下游故障时 circuit breaker 快速失败；degradation 可用 cache/备用 provider/partial result/human input 保留部分价值。

Human-in-the-Loop

HITL 应持久化 pending action 与 RunState，进程可退出；resume 时把 approve/reject/edit 作为显式外部输入继续原 run。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

for attempt in retry_policy.attempts(error_class):
    try:
        return await asyncio.wait_for(operation(), timeout=attempt.timeout)
    except TransientError as exc:
        await retry_policy.backoff(attempt, exc)

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

TimeoutPolicy、RetryPolicy、IdempotencyStore、ApprovalPolicy、Guardrail 与 RunState 协作；HITL 通过 durable pause/resume 实现。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• deadline 是端到端预算
• retry 只用于 transient 且可安全重放
• 审批状态必须持久化
• guardrail 不等于 sandbox/security boundary

7. Failure Modes

7.1 固定重试 3 次套所有 Tool

当出现「固定重试 3 次套所有 Tool」时，先分类错误是否 transient、可安全重放、是否有副作用，再检查剩余 deadline、retry budget、idempotency 与 pending approval。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 等待审批时占住进程

当出现「等待审批时占住进程」时，先分类错误是否 transient、可安全重放、是否有副作用，再检查剩余 deadline、retry budget、idempotency 与 pending approval。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 interrupt 前重复副作用

当出现「interrupt 前重复副作用」时，先分类错误是否 transient、可安全重放、是否有副作用，再检查剩余 deadline、retry budget、idempotency 与 pending approval。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 parallel guardrail 以为一定能阻止昂贵模型已启动

当出现「parallel guardrail 以为一定能阻止昂贵模型已启动」时，先分类错误是否 transient、可安全重放、是否有副作用，再检查剩余 deadline、retry budget、idempotency 与 pending approval。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

fail-fast 保护资源但牺牲可用性；graceful degradation 保持部分价值；HITL 提升控制但增加等待和状态复杂度。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

故障注入 timeout/429/network reset/approval delay，验证 retry budget、idempotency、resume 与成本上限。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：Circuit Breaker 最容易被误解的点是什么？

持续下游故障时 circuit breaker 快速失败；degradation 可用 cache/备用 provider/partial result/human input 保留部分价值。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 Call → Deadline/Rate Policy → Execute → Classify Failure → Retry/Degrade/Interrupt/Fail → Persist Decision 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• OpenAI Agents SDK — Human-in-the-loop
• OpenAI Agents SDK — Guardrails
• LangGraph — Interrupts

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。