一个多 Agent 任务刚刚启动,负责人看到 ACTIVATION_LIMIT_REACHED,第一反应是模型接口并发不够。于是换 Key、调高预算、联系 API 服务方扩容。再次执行,错误依旧出现。
问题可能根本没有走到模型接口。
DeepSeek Harness 的子代理激活名额,与 DeepSeek、GLM、Claude、Gemini 的 API 配额,是两套不同的限制。前者决定运行时能否接纳更多子代理,后者决定模型服务如何接收请求。增加其中一项,不会自动解除另一项。
下面使用一段模拟故障记录说明该如何判断。所有容量数字都是演算输入,不是 Treerouter 或模型厂商的实测结果。技术资料核验日期为 2026 年 11 月 21 日,涉及的 Harness 行为需与实际安装版本核对。
第一次判断:错误发生在模型调用之前
假设团队在同一个根任务下安排多个子代理:有的阅读需求,有的生成实现建议,有的用另一款模型进行复核。当新的子代理无法启动时,日志出现了 ACTIVATION_LIMIT_REACHED。
根据官方 Subagent 运行时文档,maxActiveSubagents 控制同一子代理树内的激活容量,当前默认值为 8。根代理不占这个池中的名额;创建中的子代理、尚未清理完成的激活,以及部分仍有待处理工作的实例,会影响名额占用。达到容量后,新建或冷恢复会被拒绝,运行时不会在这里替你建立等待队列。
这意味着,界面里只看到几个正在输出的窗口,不能据此认定还有可用名额。“正在生成文字”与“仍占用激活容量”并不是同一个状态。
此时先找对应的子代理启动记录。如果拒绝发生在创建阶段,就没有理由仅凭这一条错误认定上游 DeepSeek 或 GLM 已经返回 HTTP 429。相关配置字段可以继续核对官方配置目录。
已有工作仍然需要完成时,优先复用能够继续接收任务的子代理,或等一部分工作结束并释放资源,再创建新的子代理。不要让父代理不断重复发起已经确定无法接纳的启动请求。
如果团队还不清楚任务在哪个阶段失败,可以先使用站内的Harness 轨迹视图排查方法,把“任务启动失败”和“已启动后的模型请求失败”分开记录。
第二次判断:把子代理上限调高,也不代表接口容量增加
假设本地激活问题解决后,更多子代理终于开始工作,但随后出现模型请求失败。这时才进入 API 容量层面的判断。
一个子代理可以先后调用模型多次,也可能长时间等待文件读取或工具结果。反过来,一个业务任务还可能包含根代理请求、辅助摘要请求或其他应用请求。因此,8 个子代理既不等于 8 次模型调用,也不是整个账号最多只有 8 条在途请求的保证。
先用下面这张表区分计数单位:
| 限制 | 它实际数什么 | 调整它不能解决什么 |
|---|---|---|
| Harness 激活容量 | 子代理树中的相关运行实例 | 上游账号的模型 API 配额 |
| API 并发连接 | 尚未结束的模型请求 | 一分钟内累计请求数过多 |
| RPM | 一段时间内的请求次数 | 单次长上下文带来的 Token 压力 |
| TPM | 一段时间内的 Token 使用量 | 子代理创建时的本地容量拒绝 |
| 任务预算 | 一个业务任务允许的总消耗 | 某个瞬间的连接拥塞 |
这些概念在不同厂商的产品中也有不同口径。DeepSeek 的限流说明按账号和具体模型说明并发规则,请求从发送到响应完成期间占用并发;同一账号增加 API Key,不会因此获得一份新的独立并发额度。
Gemini 的限流文档则列出了 RPM、输入 TPM、RPD 等维度,并说明限制按项目而非单个 Key 应用。Claude 的限流文档还区分速率限制与支出限制。企业不能用一张“并发数”表替代所有模型的配额说明。
通过 AI API 中转站调用时,还要确认所购通道实际提供的容量。厂商直连账号的公开上限,不等于某个中转账号、分组或共享通道能提供同样的额度。
对于已经运行 GLM 的团队,站内GLM API 容量规划文章可以作为单模型补充;这里关注的是多 Agent 工作流怎样把请求分配到不同模型通道。
一张任务账本,比“同时开几个 Agent”更有用
现在把模拟场景写得更具体:每分钟接收 6 个业务任务。每个任务平均需要 2 次 DeepSeek 调用和 1 次 GLM 调用。假设平均完整响应耗时分别是 15 秒和 10 秒。
按这个假设,DeepSeek 的请求到达率约为每分钟 12 次,GLM 约为每分钟 6 次。在流量相对平稳、系统没有持续积压的条件下,可以用下面的关系估算平均在途请求:
平均在途请求 ≈ 每分钟请求数 × 平均请求持续秒数 ÷ 60得到的平均值分别为 3 和 1。这不是应该直接购买的并发额度,因为真实任务可能同时到达,耗时也有长尾。它只是帮助你判断数量级,避免把“每分钟 6 个业务任务”误写成“只需要每分钟 6 次 API 请求”。
下面的 Python 示例只做本地演算,不发送模型请求:
from math import ceil
tasks_per_minute = 6
# 假设数据:请用你的观测值替换。
routes = {
"deepseek-route": {
"calls_per_task": 2,
"mean_seconds": 15,
"mean_input_tokens": 4000,
},
"glm-route": {
"calls_per_task": 1,
"mean_seconds": 10,
"mean_input_tokens": 2000,
},
}
for route, sample in routes.items():
rpm = tasks_per_minute * sample["calls_per_task"]
average_inflight = rpm * sample["mean_seconds"] / 60
input_tpm = rpm * sample["mean_input_tokens"]
print({
"route": route,
"estimated_rpm": rpm,
"average_inflight": round(average_inflight, 2),
"rounded_average_inflight": ceil(average_inflight),
"estimated_input_tpm": input_tpm,
})这里的 rounded_average_inflight 只是平均值向上取整,不能当作生产并发配置。代码也没有计入输出 Token、重试、辅助调用、突发请求及厂商特有的计量规则。
真实账本应该由任务记录反推:一个任务用了哪些模型,每个模型调用多少次,每次持续多久,哪些请求因为重试而增加。别先设定“最多三个 Agent”,再假设所有费用和吞吐都会自动落在预期范围内。
需要核算金额时,参考DeepSeek 网关计费核对文章,把使用量、所购通道价格和实际结算区分开。限制并发可以改变请求节奏,却不会凭空减少一个完整任务所需的 Token。
第三次判断:错误类型决定等待是否有意义
同样是请求失败,处理动作也可能完全不同。
| 观察到的证据 | 优先处理 | 不应直接采取的动作 |
|---|---|---|
本地 ACTIVATION_LIMIT_REACHED | 检查激活占用,复用或减少新建子代理 | 盲目轮换模型 API Key |
| 上游明确报告短时速率限制 | 按响应提示降低发送频率,安排有界重试 | 所有任务同时立即重试 |
| 余额、支出或产品权限限制 | 核对账号状态、预算和通道资格 | 假设等待一秒就能恢复 |
| 请求参数或模型 ID 错误 | 修复对应请求 | 增加并发额度 |
| 流已开始但迟迟未结束 | 区分有效进展、保活和真正超时 | 未核实原请求状态就重复提交 |
例如,Z.AI 的错误码文档将 HTTP 状态与业务错误码分开。同为 429,可能对应请求速率、服务繁忙、余额或套餐限制。中转服务还可能转换错误结构,因此要保留它实际返回的错误信息,不能只留下数字 429。
重试也会消耗容量。假设模型客户端、应用后端和业务任务系统分别具有自动重试机制,叠加之后可能远超你以为的“一次失败,再试一次”。至少明确由哪一层负责主重试策略,其他层的行为是什么,并记录每一次真实出站尝试。
对于 DeepSeek 的长连接,还要正确区分保活与模型输出。相关细节已经在DeepSeek API Keep-Alive 排查文章中说明,不需要靠增加子代理数量解决等待问题。
队列应该放在能够看到共享配额的位置
假设三个应用实例共同使用同一个模型账号,每个实例都把本地并发设为 4。如果它们同时发起请求,账号侧可能看到 12 条连接。本地限制没有失效,问题是限制的作用范围小于配额的作用范围。
因此,队列和限流器的分组键应当对应真实配额池,而不只是界面上的模型名称。两个模型别名如果共用同一通道容量,就不能各自获得一份完整额度。模型迁移后,也要重新确认这个映射。
Python 的 `asyncio.Semaphore`可用于单个异步进程内约束并发,但它不会自动协调多个进程或多台服务器。集中式队列、共享计数器或网关侧策略,需要在系统架构中单独安排。
如果调用采用流式响应,只有在流完成、关闭或取消得到妥善处理后,才能认为客户端的连接占用结束。客户端停止等待,也不等于上游已经立刻停止计算;这一边界需要实测和服务说明支持。
业务侧还需要一个等待上限。在线用户等候几秒与后台任务等待几分钟,是不同的产品要求。超时后应返回明确的排队或失败状态,避免用户连续点击,制造更多重复任务。
涉及部门、项目和凭证的隔离,可以继续阅读多模型 API 权限隔离指南。权限边界与配额边界可能有关联,但不能默认它们完全一致。
上线验收以完成任务为准
企业购买接口时,建议把“支持 DeepSeek、GLM、Claude、Gemini”进一步写成具体的验收条件:所需模型 ID 和协议可用;配额作用范围明确;错误可以分层识别;任务在规定时间内产生可用结果。
容量测试可以从一个根任务、一条模型路线开始,再逐步增加任务到达率。每一级都记录完成量、排队时间、完整耗时、错误原因及实际使用量。如果只看启动数量,就可能把一批同时等待的子代理误认为吞吐提升。
不要为了让演示好看,删除失败请求或只统计最快的样本。业务能否承受慢请求和失败恢复,往往比一次顺利演示更接近真实运行条件。站内企业级 API 中转站调用日志验收可以帮助保留这条证据链。
准备通过 Treerouter 接入时,先在模型目录确认目标路线,再注册并验证一个小规模工作流。把第一轮目标定为“解释清楚本地激活、模型请求和业务完成三个状态”,比一开始同时启用十几个子代理更容易获得可靠的扩容依据。
常见问题
把 `maxActiveSubagents` 从 8 调大,会直接提高模型 API 并发吗?
不会。它只改变对应子代理树的接纳容量。上游账号、所购通道以及其他共享请求的配额,仍然按各自规则执行。调大前应确认瓶颈确实发生在激活层。
达到激活容量后,Harness 会自动把新子代理排队吗?
当前官方运行时文档说明,这个接纳点会拒绝新建或冷恢复,不提供等待队列。应用如果需要排队,应另外设计任务调度,不要把重复创建请求当作队列。
把任务切到另一款模型,就一定能缓解拥塞吗?
只有另一条路线具有独立可用容量,并满足任务所需的输入、工具和输出能力时,才可能有帮助。切换后的质量与数据处理范围同样需要验收,不能只比较是否返回 HTTP 200。
限制并发能保证省 Token 吗?
不能。并发限制控制同一时刻进行多少工作,Token 总量取决于请求次数、上下文长度和生成内容。只有减少无效启动、重复请求或不必要的推理,才可能减少对应消耗,效果需要通过实际记录验证。






