Agent 限流与并发调度——429、背压与多 Agent 公平性

1.1 请求次数#

请求次数限制通常以 RPM、RPD 或某个更短的滚动窗口表达。它约束的是“请求事件”的数量，而不是请求大小。

这意味着两种负载可能消耗相同的请求额度：

• 100 个每次只有 50 Token 的分类请求；
• 100 个每次携带 100K Token 上下文的代码分析请求。

但它们对 Token、延迟和成本的压力完全不同。因此，请求次数只能作为多维限制中的一个维度，不能单独代表系统容量。

短窗口行为尤其容易误导。Anthropic 文档提醒，标称 60 RPM 的限制可能以约 1 RPS 的粒度执行，短时突发仍然会产生 429；OpenAI 也说明，高密度突发可能先触及更短时间尺度的限制。²³

对调度器而言，请求次数桶至少应按以下键拆分：

1
(provider, model_family, organization/project, endpoint_class)

不能只维护一个“全局 RPM”。例如：

• 文本模型和嵌入模型可能使用不同配额；
• 搜索端点和普通 REST 端点可能使用不同配额；
• 同一 Provider 的多个模型可能共享一个限额组；
• GitHub core、search、graphql 等资源属于不同 Bucket。⁴

1.2 输入 Token#

输入 Token 是 Agent 最容易失控的资源，因为多轮历史、系统提示词、工具定义、代码文件和 Tool Result 都会持续进入下一次请求。

调度器在请求发送前需要估算：

如果等 Provider 返回 429 后才知道输入 Token 超额，队列就已经失去主动控制。因此，生产系统通常会在准入阶段预估 Token，并在响应的 Usage 数据到达后对账。

需要注意，缓存 Token 是否计入速率限制由 Provider 定义。Anthropic 当前文档说明，对大多数 Claude 模型，缓存命中的输入通常不计入 ITPM，而未缓存输入会计入；OpenAI 会在 Usage 中区分 cached_tokens，具体限流和计费语义应以对应模型及项目限制为准。²⁵

这意味着 Scheduler 不应该写死：

1
input_tokens = prompt_tokens

而应维护 Provider Adapter：

1
effective_input_load = provider.rateLimitAccounting(usage)

1.3 输出 Token#

输出 Token 与输入 Token 最大的区别是：发送请求时还不知道实际输出长度。

如果完全不预留，多个长输出请求可能同时进入系统，随后一起消耗 OTPM；如果一律按 max_output_tokens 全量预留，又会过度保守，使大量短回答请求无谓排队。

一个更实用的策略是分两阶段预留：

• $M_i$：请求声明的最大输出；
• $Q_p$：该模型、任务类型在历史分布中的高分位值，例如 P90 或 P95。

请求开始时预留 $R_i^{out}$，流式生成过程中按实际增量持续扣减；如果输出接近预留上限，再申请追加额度。这样既避免无预留超卖，也不会把所有请求都按最坏情况处理。

对于 Realtime 类接口，OpenAI 的事件模型会显式下发 rate_limits.updated，并说明创建 Response 时会先为输出 Token 做一定预留，完成后再调整。这个机制也说明：输出预算本质上是一个动态保留与结算过程。⁶

1.4 并发请求#

并发限制约束的不是单位时间内总请求量，而是“此刻有多少请求仍在执行”。流式模型请求可能持续数秒到数分钟，比普通 REST 调用更容易长期占住槽位。

根据 Little 定律，在稳态下：

其中：

• $L$ 是平均在途请求数；
• $\lambda$ 是到达率；
• $W$ 是平均服务时间。

如果平均服务时间从 5 秒升至 20 秒，即使请求到达率不变，在途并发也会放大 4 倍。因此，仅控制 RPM 并不能防止并发耗尽。

中央调度器应至少维护：

• Provider 级并发；
• 模型级并发；
• Session 级并发；
• Tenant 级并发；
• 工具类型并发。

并发槽还可以加权。例如，一个 200K Token 的长上下文请求不应与一个 200 Token 的分类请求等价占用一个槽，可使用 Weighted Semaphore：

其中 $K$ 是一个容量单位。

1.5 WebSocket 连接数#

WebSocket 限制与请求限制不是一回事。一条长连接可能承载多个请求，也可能长时间空闲；如果每个 Agent、每个 Turn、每个 Subagent 都独立建连，系统会在请求速率尚未达到上限时先耗尽连接、文件描述符、NAT 表项或服务端连接配额。

因此，WebSocket 需要单独的连接池策略：

• 连接复用粒度：Session、Provider、Tenant，还是 Turn；
• 最大空闲连接数；
• 最大连接寿命；
• 预热连接数；
• 空闲回收时间；
• 每条连接是否允许多路复用；
• 连接故障时是否回退到 HTTPS。

WebSocket Admission Control 应先检查：

1
provider_connection_slots
2
tenant_connection_slots
3
local_fd_budget
4
session_affinity_requirement

长连接池的目标不是“连接越多越快”，而是在握手成本、状态粘性、连接上限和故障隔离之间取平衡。

1.6 产品使用额度#

产品使用额度通常是月度使用层级、套餐额度、组织支出上限或项目预算。它与短窗口 Rate Limit 有本质区别：

• Rate Limit：等一段时间后会补充；
• Usage/Spend Limit：可能要等账期重置、提高套餐、修改预算或人工审批；
• 企业预算：可能要求立即停止，不能自动切换到更昂贵的路径。

OpenAI 明确区分 Rate Limit、批准的月度使用额度和可配置的 Spend Limit；Anthropic 也区分月度 Spend Limit 与 RPM/ITPM/OTPM Rate Limit。¹²

因此，“所有 429 都指数退避”是错误设计。Scheduler 应把错误归类为：

1
TEMPORARY_RATE_LIMIT
2
USAGE_QUOTA_EXHAUSTED
3
BILLING_REQUIRED
4
ENTERPRISE_BUDGET_BLOCKED

后三类通常不应自动重试。

1.7 MCP 和第三方 API 配额#

Agent 的吞吐由整条链路中最窄的资源决定。模型额度充足，不代表 GitHub、Slack、搜索服务、浏览器平台或企业内部 API 也充足。

GitHub 同时存在 Primary Rate Limit 和 Secondary Rate Limit。Secondary Limit 会受并发请求、端点点数、CPU 时间和内容创建频率等因素影响；官方建议避免并发请求、对写操作留出间隔，并优先使用 Webhook 代替轮询。⁷⁸

Slack 的限流按 API Method、Workspace 和 App 等维度生效；收到 HTTP 429 时，Retry-After 只限制对应 Workspace 中的对应 Method，其他 Method 或其他 Workspace 未必需要一起暂停。⁹

因此，第三方限流器的 Key 必须贴合服务端的真实作用域。例如：

1
GitHub:  (installation_id, resource_bucket)
2
Slack:   (workspace_id, method)
3
MCP:     (server_id, tool_name or capability_group)
4
Search:  (tenant_id, endpoint)

如果收到一个 GitHub Search 429，却冻结整个模型 Provider 队列，就会把局部故障放大成全局停摆。

2.1 扇出调用#

假设主 Agent 每轮派生 $b$ 个 Subagent，每个 Subagent 平均执行 $r$ 次模型调用，并产生 $t$ 次工具调用，那么单个用户任务的请求量近似为：

如果 Subagent 还可以递归派生下一层，则最大调用量近似为：

当 $b=4,d=3$ 时，理论节点数已经达到 85。哪怕每个节点只发两次模型请求，也会产生 170 次调用。

更危险的是，扇出通常发生在同一时间窗口：主 Agent 读完任务后一次性启动多个研究 Agent，它们又在相近时刻读取代码、调用 GitHub、提交模型请求，形成同步突发。

解决扇出问题，不能只在每个 Subagent 内设置并发上限，而要设置父任务共享预算：

1
max_subagents_per_turn
2
max_fanout_depth
3
max_model_requests_per_task
4
max_tool_calls_per_task
5
max_tokens_per_task

2.2 重试风暴#

重试会把失败流量重新注入系统。如果每一层都独立重试，放大倍数会迅速增长。AWS Builders’ Library 举例说明，多层调用栈中每层都进行多次重试，会把底层负载成倍放大；其建议是尽量只在一个明确层次重试，并通过 Token Bucket 限制重试流量。¹⁰

在一个 Agent 系统中，可能同时存在：

• SDK 内置重试；
• Provider Adapter 重试；
• Agent Turn 重试；
• Subagent 重试；
• MCP Client 重试；
• Workflow 编排器重试。

如果每层都允许 3 次尝试，五层最坏请求数量可能接近：

更糟的是，如果所有 Subagent 使用相同的固定等待时间，它们会在同一时刻再次醒来，形成第二轮尖峰。正确做法是：

1. 明确唯一重试所有者；
2. 对重试设置独立 Token Bucket；
3. 遵守 Retry-After；
4. 添加 Jitter；
5. 限制总尝试次数和总重试时长；
6. 把 429 作为减少并发的反馈，而不是只作为 sleep 信号。

OpenAI 当前官方 SDK 会对符合条件的临时限流错误自动重试，并遵守 Retry-After；如果业务层再套一层重试，必须把 SDK 已经消耗的尝试算入总 Retry Budget。¹¹

2.3 Token 预算失控#

Subagent 不只放大请求数，还会复制上下文。

如果主 Agent 的稳定前缀为 $S$ Token，每个 Subagent 又携带 $C_j$ Token 的任务上下文，则一次扇出的输入量为：

当系统提示词、工具定义和仓库摘要很长时，$bS$ 会成为主要成本。

常见失控模式包括：

• 每个 Subagent 都收到完整代码库摘要；
• 多个 Subagent 重复读取同一文件；
• Tool Result 原样复制到所有分支；
• Subagent 结果回收后，又被完整注入主 Agent；
• 每个分支都设置过大的输出上限。

中央调度器应在派生 Subagent 前做预算分配：

如果父任务没有足够预算，就应该减少分支数量、降低模型等级、缩小上下文或改为串行探索，而不是先启动再等待 429。

2.4 工具和模型同时拥塞#

Agent 不是单队列系统，而是一个闭环队列网络：

模型和工具会相互制造负载：

• 模型吞吐越高，产生的 Tool Call 越快；
• 工具返回越快，下一轮模型请求越快；
• 工具变慢时，模型槽位可能空闲，但 Session 数不断堆积；
• 模型变慢时，工具结果会在聚合区等待，内存和上下文膨胀；
• 消息平台变慢时，最终输出和中间进度会积压。

这类系统不能用一个“最大并发 = 50”解决。需要为每个阶段单独限流，并让背压向上游传播。

3.1 每 Provider 请求队列#

每个 Provider 必须独立排队，因为它们的限流维度、Header、恢复时间和故障域不同。

错误设计：

1
一个全局 FIFO 队列 → 所有模型、GitHub、MCP 和消息平台

正确方向：

1
Provider Queue
2
  ├─ Model Family / Endpoint Queue
3
  │    ├─ Tenant Fair Queue
4
  │    │    └─ Session Queue

每级队列承担不同职责：

• Provider：隔离故障域；
• Model/Endpoint：匹配独立配额组；
• Tenant：保证组织公平；
• Session：防止一个长任务独占；
• Priority：区分前台和后台。

队列应是有界的。Google SRE 指出，过长队列会持续增加等待时间和内存占用，而且很多请求在真正执行前就已经失去价值；在过载状态下，尽早、低成本地拒绝或降级，通常比无限排队更安全。¹²

3.2 Token Bucket#

Token Bucket 适合表达可补充的速率额度。设：

• 桶容量为 $C$；
• 补充速率为 $r$ Token/秒；
• 上次更新时间为 $t_0$；
• 当前余额为 $B(t_0)$。

则时刻 $t$ 的余额为：

请求成本为 $c_i$，只有当：

才允许执行，并更新：

Agent 通常需要多个并行 Token Bucket：

1
request_bucket.consume(1)
2
input_token_bucket.consume(estimated_input)
3
output_token_bucket.reserve(reserved_output)
4
cost_bucket.reserve(estimated_cost)
5
retry_bucket.consume(1)  // 仅重试请求

Anthropic 官方明确说明其 API 使用 Token Bucket 持续补充额度，而不是固定窗口瞬间重置。²

一个关键实践是：正常请求和重试请求分桶。即使正常流量还有额度，也不应允许重试无限抢占全部容量。

3.3 Concurrency Semaphore#

Token Bucket 控制“进入速率”，Semaphore 控制“在途数量”。两者缺一不可。

1
Token Bucket：每秒可以放进多少工作
2
Semaphore：同时可以有多少工作正在执行

请求准入需要同时满足：

1
rate_tokens_available && concurrency_permits_available

并发控制可分为：

• Provider Semaphore；
• Model Semaphore；
• Tenant Semaphore；
• Session Semaphore；
• Tool Semaphore；
• Connection Semaphore。

对长短任务混合场景，可使用加权 Semaphore 或分池：

1
interactive-short:  20 slots
2
interactive-long:    8 slots
3
background:          4 slots
4
batch:               separate path

这样可以防止少量长上下文请求占满全部槽位，导致轻量交互也无法进入。

3.4 优先级队列#

常见优先级可以设计为：

但纯优先级队列会导致低优先级饥饿，需要加入 Aging：

等待越久，实际优先级逐渐提高。

还应结合 Deadline：如果请求在排队期间已经超过用户可接受时限，应直接取消或降级，而不是继续消耗下游资源。

3.5 Per-session Budget#

Session Budget 防止一个长任务吃光整个系统。

每个 Session 至少应跟踪：

1
model_requests_used
2
input_tokens_used
3
output_tokens_used
4
tool_calls_used
5
subagents_active
6
cost_used
7
wall_time_used

预算既可以是硬上限，也可以是软上限：

• 软上限：触发压缩、降级模型、减少 Subagent；
• 硬上限：停止继续派生，要求用户确认或结束任务。

父任务创建 Subagent 时应先“划拨预算”，而不是让所有子任务共享一个无锁全局计数器：

1
parent_budget = self_budget + child_allocations + emergency_reserve

Emergency Reserve 用于收尾：即使任务接近预算上限，也要保留足够额度生成最终总结，而不是在完成 95% 后因预算耗尽无法向用户交付结果。

3.6 Per-user 和 Per-tenant 配额#

Provider 的组织级配额并不会自动保证应用内部公平。OpenAI 官方建议应用自行设置用户级使用上限，以防自动化和高流量访问占满组织资源；Anthropic 允许在组织额度之下设置 Workspace 限额，以保护其他 Workspace。¹²

推荐使用分层配额：

1
Organization
2
  └─ Tenant / Workspace
3
       └─ User
4
            └─ Session
5
                 └─ Turn / Subagent

一个请求必须逐层获得许可：

公平调度可以采用 Weighted Deficit Round Robin：

1. 每个 Tenant 获得一个权重；
2. 调度轮次中为每个 Tenant 增加 Deficit；
3. 请求成本小于 Deficit 时才能发出；
4. 未用完的 Deficit 可有限结转；
5. 大请求不会永久阻塞小请求，低权重租户也不会完全饿死。

下面是一段简化的准入伪代码：

1
async function admit(req: RequestEnvelope): Promise<Permit> {
2
  const path = quotaHierarchy(req);
3

4
  // 1. 预算与公平性检查
5
  for (const quota of path) {
6
    if (!quota.canReserve(req)) {
7
      throw new QueueOrReject(quota.nextAvailableAt(req));
8
    }
9
  }
10

11
  // 2. 速率额度
12
  await providerRequestBucket(req).take(1, req.deadlineAt);
13
  await inputTokenBucket(req).take(req.estimatedInputTokens, req.deadlineAt);
14
  await outputTokenBucket(req).reserve(req.reservedOutputTokens, req.deadlineAt);
15

16
  // 3. 并发槽
17
  const concurrencyPermit = await semaphore(req).acquire(
18
    req.concurrencyWeight,
19
    req.deadlineAt,
20
  );
21

22
  // 4. 原子提交所有预留
23
  reserveHierarchy(path, req);
24

25
  return new Permit({
26
    onComplete: usage => reconcile(req, usage),
27
    onFailure: error => classifyAndFeedback(req, error),
28
    onRelease: () => concurrencyPermit.release(),
29
  });
30
}

生产实现必须保证多资源预留的原子性或补偿性，避免已经扣了 Token，却在拿并发槽时失败，造成额度泄漏。

4.1 短窗口限流#

特征：

• Retry-After 为较短秒数；
• Request Remaining 或 Token Remaining 临时为 0；
• Reset 时间明确；
• 账户与账单状态正常。

处理方式：

1. 暂停对应限流 Key，而不是暂停全局；
2. 等待至少 Retry-After；
3. 添加小幅 Jitter；
4. 重试请求重新进入原优先级队列；
5. 收缩该 Key 的并发上限；
6. 限制最大尝试次数和总等待时长。

OpenAI 当前文档明确要求把 Retry-After 视为最小等待值，并增加随机延迟以避免多个客户端同时重试。¹¹

4.2 Token 额度耗尽#

Token 限流与 Request 限流的处理不同。

如果 Request 额度仍有余量，但 Token 额度耗尽，继续发送更小请求可能仍然可行。调度器应：

• 等待 Token Reset；
• 优先放行小请求；
• 暂停大上下文请求；
• 启用上下文压缩；
• 降低输出预留；
• 使用 Prompt Cache；
• 将后台任务迁移到 Batch 或更高余量 Provider。

因此，队列排序不能只按到达时间，还可按成本做“可装箱调度”：当剩余 Token 不足以执行队头大请求时，在不破坏公平性的前提下允许小请求先行，避免 Head-of-Line Blocking。

4.3 并发连接过多#

并发或连接过多的症状可能是 429、连接拒绝、WebSocket 特定错误或 Provider 自定义错误。

处理方式不是等待 RPM Reset，而是：

• 立即降低 Semaphore 上限；
• 回收空闲连接；
• 停止连接预热；
• 合并同 Provider 的长连接；
• 暂停低优先级流；
• 必要时从 WebSocket 降级到 HTTPS；
• 观察在途请求完成后再缓慢恢复。

如果错误来自本地文件描述符或 NAT 端口耗尽，服务端 Retry-After 也无法直接解决，需要本地资源诊断。

4.4 产品套餐额度耗尽#

产品套餐或月度用量耗尽通常具有以下特征：

• 错误正文包含 quota、plan、billing 或 usage limit；
• 没有短期有效的 Reset；
• Retry-After 缺失或无意义；
• 控制台显示账户额度不足。

处理方式：

• 标记为不可自动重试；
• 暂停该 Provider 的新请求；
• 通知管理员或用户；
• 按策略切换到备用 Provider/模型；
• 若没有被授权的降级路径，则快速失败。

OpenAI 文档特别指出，Retry-After 只适用于临时限流，不代表配额、账单或需要用户操作的问题能通过等待恢复。¹

4.5 企业预算达到上限#

企业预算是内部策略，不一定由 Provider 返回 429。企业 Gateway 可能返回：

• 402；
• 403；
• 429；
• 自定义错误码；
• 成功响应但拒绝高成本模型路由。

中央调度器应在请求发送前主动检查预算，而不是依赖 Gateway 拒绝：

当 projected spend 超过阈值时，可采用分级策略：

不要在达到预算上限后自动切换到另一个同样收费、甚至更昂贵的 Provider，除非企业策略明确允许。

4.6 Retry-After 和服务端重置时间#

RFC 9110 规定，Retry-After 可以是：

• 一个非负整数秒数；
• 一个 HTTP Date。¹⁴

解析逻辑应同时支持两者：

1
function parseRetryAfter(value: string, now: number): number | null {
2
  if (/^\d+$/.test(value)) {
3
    return now + Number(value) * 1000;
4
  }
5
  const ts = Date.parse(value);
6
  return Number.isFinite(ts) ? Math.max(ts, now) : null;
7
}

等待时间优先级建议为：

1
1. Provider 明确的 Retry-After
2
2. 对应维度的 reset header
3
3. 错误正文中的 resets_at
4
4. 指数退避 + Full Jitter

调度器还要记录限制作用域：

1
interface RateLimitDecision {
2
  kind:
3
    | "REQUEST_WINDOW"
4
    | "INPUT_TOKEN_WINDOW"
5
    | "OUTPUT_TOKEN_WINDOW"
6
    | "CONCURRENCY"
7
    | "PRODUCT_QUOTA"
8
    | "ENTERPRISE_BUDGET";
9
  scopeKey: string;
10
  retryable: boolean;
11
  retryAt?: number;
12
  reduceConcurrency?: boolean;
13
  requiresUserAction?: boolean;
14
}

GitHub 可能在 Primary 或 Secondary Limit 下返回 403 或 429。其官方文档要求：有 Retry-After 时等待指定秒数；若 x-ratelimit-remaining=0，等待到 x-ratelimit-reset；否则至少等待一分钟，并在持续失败时增加退避时间。继续轰炸可能导致集成被封禁。⁷

5.1 成功率反馈#

定义一个滑动窗口内的成功率：

成功率下降说明当前并发可能超过稳定容量，但不能只依赖成功率：

• 429 是明确拥塞；
• 5xx 可能是服务故障；
• 客户端取消不一定代表 Provider 过载；
• 内容安全拒绝不应影响并发判断。

因此，需要按错误类型计算 Capacity-related Failure Rate：

只有容量相关错误才进入并发控制反馈。

5.2 延迟反馈#

429 通常是滞后信号。很多服务在真正返回 429 前，会先出现排队和尾延迟上升。

可以维护：

• EWMA Latency；
• P50、P90、P95、P99；
• TTFT；
• Stream Event Gap；
• Queue Wait Time；
• Tool Round-trip Time。

若：

即使还没有 429，也可以提前停止增加并发。

Envoy 的 Adaptive Concurrency Filter 也是通过延迟采样和控制回路调整并发上限，并要求控制器能够真正掌控目标集群的全部请求并发，否则反馈会失真。¹⁵

5.3 429 比例反馈#

429 比例是最直接的容量信号：

但不能把不同作用域的 429 混在一起：

• OpenAI 模型 A 的 Token 429；
• GitHub Search Secondary Limit；
• Slack 某 Workspace 的 chat.update 429；
• 企业预算拒绝。

它们需要不同的 Controller。正确的反馈 Key 类似：

1
(provider, account/project, model_or_endpoint, limit_dimension)

5.4 动态收缩和恢复#

一个简单、稳定的控制器可以采用 AIMD：

发生拥塞时乘性减小：

稳定窗口内加性增加：

示例：

1
α = 1
2
β = 0.7
3
stable_window = 60s
4
cooldown = max(Retry-After, 15s)

控制器应加入：

• Hysteresis：避免在阈值附近来回振荡；
• Cooldown：收缩后等待观察；
• Min Samples：样本不足不调参；
• Max Step：单次不能增长过快；
• Separate Controller：短请求与长请求分开；
• Emergency Brake：高 429 或超时率时快速降至安全值。

关键原则是：恢复要慢，收缩要快。 这与拥塞控制中“谨慎探测容量、快速退出过载区”的思路一致。

6.1 模型连接到事件队列#

模型流可能快速产生：

• 文本 Delta；
• Reasoning Delta；
• Tool Call 参数 Delta；
• Usage 事件；
• Rate Limit 事件；
• Completion 事件；
• Error 事件。

这些事件不能一视同仁：

如果消费端变慢，应优先合并文本 Delta，而不是让每个 Token 形成一个对象堆在内存里。

6.2 事件队列到 Agent Loop#

Agent Loop 通常是状态机，必须按事件顺序更新当前响应、工具参数和终止状态。事件队列过长会导致：

• UI 看似卡顿；
• Tool Call 已完成但迟迟未调度；
• 用户取消指令排在大量低价值 Delta 之后；
• Completion 事件延迟，连接槽无法释放。

因此，控制事件和数据事件应分通道：

1
control_channel: cancel / error / completed / permission
2
stream_channel:  text / reasoning / tool delta

控制通道优先消费，避免关键状态被普通 Delta 淹没。

6.3 Agent Loop 到 Tool Queue#

Tool Queue 应按工具资源拆分：

• 本地只读；
• 本地写操作；
• Shell；
• GitHub；
• MCP Server；
• 浏览器；
• 搜索；
• 消息平台。

每类工具有独立并发和限流器。不能因为本地 grep 很快，就允许同样的并发度打向 GitHub Search。

当 Tool Queue 达到高水位时，Agent Loop 应：

• 暂停启动新的 Subagent；
• 不再向模型暴露更多并行 Tool Call 预算；
• 合并相似读取；
• 优先执行能解除关键路径阻塞的 Tool Call；
• 将后台工具降级或取消。

6.4 Tool Result 到下一轮模型请求#

最常见的放大器是：每完成一个 Tool Result，就立即发起一次新模型请求。

假设同一轮有 8 个并行工具，若每个工具完成都触发模型请求，会产生 8 次采样；如果等待一个短聚合窗口，可以只发 1 次。

可以设计 Debounce/Barrier：

1
触发下一轮模型请求的条件：
2
1. 所有关键 Tool Call 完成；或
3
2. 聚合窗口到期；或
4
3. 已有足够信息满足 early-continue 条件；或
5
4. 用户输入/取消要求立即推进。

聚合窗口不能无限等待慢工具。可设置：

1
min_results = 1
2
coalesce_window = 100~500ms
3
critical_tool_deadline = task-specific

Tool Result 进入模型前还应裁剪和归一化，避免工具吞吐转换成 Token 拥塞。

6.5 Agent 输出到 UI 或消息平台#

CLI 可以高频刷新，但消息平台通常对发送、编辑或特定 Method 有独立限制。Slack 明确按 Method 和 Workspace 限流，并通过 Retry-After 告知恢复时间。⁹

因此，输出层应区分：

• 最终结果：必须送达，最高优先级；
• 权限确认：必须及时送达；
• 错误与限流状态：需要送达；
• 流式文本：可合并为较低频率更新；
• 进度动画：可丢弃；
• Debug 日志：不应占用用户消息配额。

一种常见策略：

1
CLI：      20~60 Hz 局部刷新
2
IDE：       5~20 Hz 合并渲染
3
消息平台：  0.5~2 Hz 编辑同一条消息
4
最终结果：  立即进入高优先级发送队列

具体频率应由平台限制和用户体验测试决定，不能写死为跨平台标准。

7.1 Prompt Cache#

Prompt Cache 适合稳定、重复的前缀：

• System Prompt；
• 工具定义；
• 仓库固定说明；
• 长文档背景；
• 多轮会话的稳定历史前缀。

OpenAI Prompt Caching 对符合条件的近期模型自动生效，并要求精确前缀复用；Anthropic Prompt Caching 同样以可复用前缀为核心，并支持缓存 System、Tools、Messages 和 Tool Result 等内容。⁵¹⁶

要提高命中率：

1. 把稳定内容放前面；
2. 把时间戳、随机 ID 和用户动态内容放后面；
3. 保持工具顺序和 Schema 稳定；
4. 不要每轮重排 System Prompt；
5. 监控 Cache Read/Write Token；
6. 避免多个并行请求在首个缓存写入完成前同时冷启动。

Prompt Cache 通常减少重复处理成本和延迟，但是否减少某个 Provider 的 ITPM，要按 Provider 规则计算，不能仅看账单 Token。

7.2 上下文压缩#

上下文压缩通过摘要、裁剪、折叠和去重减少输入 Token，但它并非免费：

• 摘要本身可能需要额外模型调用；
• 过度压缩会损失决策信息；
• 频繁压缩会破坏 Prompt Cache；
• 压缩后的信息可能让模型重复调用工具。

压缩应满足收益条件：

工程上可在预计剩余 Turn 较多、历史工具输出很大、稳定前缀仍可保留时触发压缩。

7.3 工具结果裁剪#

工具结果经常比用户消息更大。建议按工具类型做结构化裁剪：

• 搜索：保留 Top-K 命中、文件路径和行号；
• 测试：保留失败摘要、首个根因和日志文件路径；
• GitHub：保留必要字段，不回填完整 JSON；
• 构建：保留错误块和统计，不回填全部 stdout；
• 网页：保留正文片段和来源，而非 DOM 全量；
• 大文件：返回路径与按需读取能力。

裁剪不只是省 Token，也能降低模型被噪声干扰的概率。

7.4 请求合并#

请求合并有三种常见形式：

1. 同端点合并：一次读取多个资源；
2. Tool Result 合并：并行工具完成后统一回填；
3. 相同查询去重：多个 Subagent 读取同一文件时共享结果。

可维护一个短 TTL 的 In-flight Request Map：

1
key = hash(provider, endpoint, normalized_parameters, auth_scope)

相同 Key 的请求复用同一 Future，而不是重复访问下游。

注意：认证作用域必须进入 Key，不能把不同租户的响应错误共享。

7.5 批处理#

批处理适合不要求即时响应的任务：

• 离线评测；
• 大规模分类；
• Embedding；
• 夜间仓库索引；
• 日志总结；
• 非实时报告。

OpenAI Batch API 使用独立的更高限流池，并以 24 小时完成窗口处理异步请求；Anthropic Message Batches 也提供异步批处理与独立的成本优势。¹⁷¹⁸

Batch 的本质是把工作从“低延迟交互队列”迁移到“高吞吐离线队列”。不要把用户正在等待的 Tool Call 塞进 24 小时 Batch 路径。

7.6 模型分级路由#

不是每个步骤都需要最强模型。可按任务等级路由：

分级路由可以减少 Token 成本和高端模型队列压力，但必须满足：

• 每个模型有独立容量控制；
• 路由器自身不能成为高成本调用；
• 有质量回退机制；
• 不能在企业预算受限时静默切到更贵模型；
• 记录实际路由结果用于评估。

7.7 限制 Subagent 扇出#

扇出限制应同时约束宽度、深度和总预算：

1
max_active_children_per_parent
2
max_total_children_per_task
3
max_depth
4
max_tokens_allocated_to_children
5
max_tool_calls_allocated_to_children

还可以采用 Progressive Fan-out：

1. 先启动 1~2 个探索 Agent；
2. 检查结果是否互补；
3. 只有信息增益足够时再扩展；
4. 一旦找到高置信度路径，取消剩余低价值分支。

可以定义边际信息增益：

当 $\Delta U_j$ 低于成本阈值时，不再派生新 Subagent。

8.1 场景#

系统同时收到 6 个仓库分析任务：

• 2 个前台修复任务，用户正在等待；
• 2 个代码审查任务；
• 2 个后台索引任务。

每个任务最多可以派生 4 个 Subagent。下游包括：

• Model Provider A：受 RPM、ITPM、OTPM 和并发限制；
• Model Provider B：备用模型，质量稍低、额度独立；
• GitHub API：Core、Search 和内容写入限制；
• MCP Server：最大 8 个并发 Tool Call；
• Slack：按 Workspace 和 Method 限流，用于进度与最终结果投递。

8.2 初始准入#

调度器先给任务分级：

如果直接按最大扇出，理论上会启动 24 个 Subagent。中央调度器只批准：

• 前台任务各 2 个；
• 审查任务各 1 个；
• 后台任务暂不启动。

首批共 6 个 Subagent，保留容量给用户后续交互和 Tool Result 回填。

8.3 模型队列调度#

每个模型请求在准入前估算输入/输出 Token并预留：

1
Provider A
2
  request_bucket:      还有容量
3
  input_token_bucket:  剩余偏低
4
  output_token_bucket: 充足
5
  concurrency:         6 / 8

调度器优先放行两个前台请求和关键 Tool Result 回填；代码审查请求排队，后台请求转移到 Batch 候选队列。

8.4 GitHub Secondary Rate Limit 出现#

多个 Subagent 同时执行代码搜索，GitHub Search 返回 Secondary Rate Limit，并带 Retry-After。

错误处理：

1. 只冻结 (GitHub installation, search) Bucket；
2. Core 读取和已有缓存仍可使用；
3. 创建 PR 等写操作进入独立队列；
4. 搜索请求等待到 Retry-After + jitter；
5. GitHub Search Semaphore 从 8 收缩到 3；
6. 相同查询通过 In-flight Map 合并；
7. 新 Subagent 扇出暂停。

不应做的事：

• 暂停全部 GitHub 流量；
• 暂停模型请求；
• 让每个 Subagent 自己独立重试；
• 忽略 Retry-After 继续搜索。

8.5 模型 Token 429 出现#

随后 Provider A 返回输入 Token 429，响应 Header 表明 Request 数仍有余量，但 Token Reset 需要等待。

调度器执行：

1. 冻结 Provider A 的大上下文请求；
2. 小请求可在剩余 Token 足够时继续；
3. 并发上限从 8 降至 5；
4. 代码审查请求路由到 Provider B；
5. 前台修复任务保留在 Provider A，等待短 Reset；
6. 后台索引进入 Batch；
7. 对下一轮上下文执行 Tool Result 裁剪和压缩；
8. 不增加业务层重试，因为 SDK 已经处理标准临时重试。

8.6 Tool Queue 与模型队列协同#

GitHub Search 等待期间，本地文件读取和测试仍可运行。调度器不会让所有 Session 空转，而是重排工作：

1
可执行：本地 Read / Grep / Test
2
等待：GitHub Search
3
延迟：非关键模型总结
4
暂停：新 Subagent
5
取消：重复搜索与低价值后台分支

多个 Tool Result 在 300ms 聚合窗口内合并，只触发一次下一轮模型请求，避免工具恢复后形成模型请求尖峰。

8.7 消息平台限流#

前台任务持续产生进度更新，Slack chat.update 返回 429。

调度器只暂停：

1
(workspace_id, chat.update)

同时：

• 中间 Token Delta 不再逐条编辑；
• 只保留最新进度快照；
• 权限请求和错误通知走更高优先级；
• 最终结果进入可靠的高优先级投递队列；
• 其他 Workspace 不受影响；
• 到 Retry-After 后合并发送一次最新状态。

8.8 最终执行顺序#

8.9 公平性结果#

最终系统实现了：

• 前台任务没有被后台索引挤占；
• 一个 Tenant 不能用大量 Subagent 独占 Provider；
• GitHub Search 限流没有扩散到 GitHub Core、模型和本地工具；
• Provider A Token 429 没有引发全系统重试风暴；
• Provider B 只承接允许降级的非关键任务；
• Slack 限流只降低了中间更新频率，没有丢失最终结果；
• 后台工作被迁移到 Batch，而不是与交互请求竞争。

8.10 必须观测的调度指标#

按 Provider、Tenant、User、Session 和 Workload Class 切分：

1
admission_allowed_total
2
admission_rejected_total
3
queue_depth
4
queue_wait_ms
5
inflight_requests
6
reserved_input_tokens
7
reserved_output_tokens
8
actual_input_tokens
9
actual_output_tokens
10
budget_utilization
11
rate_limit_429_total
12
retry_after_ms
13
retry_attempts
14
adaptive_concurrency_limit
15
subagent_fanout
16
backpressure_high_watermark_total
17
coalesced_events_total
18
coalesced_tool_results_total
19
message_updates_dropped_total
20
final_delivery_delay_ms

只看“429 数量”远远不够。更重要的是：

• 429 前的队列等待是否已经上升；
• 哪个 Tenant 贡献了负载；
• 重试是否放大请求量；
• 自适应并发是否及时收缩；
• 低优先级请求是否饥饿；
• 最终交付是否受到背压影响。