父子智能体额度与结果

本页阅读位置

完成第一轮对话后，按当前业务需求深入。Spring 常规声明优先使用 RegistrationManifest 与注解；本页的底层 register / publish 或直连方法供协议细化与兼容集成参考。

根 Agent 的额度覆盖整个任务。子 Agent 执行时按自己的定义预留父级剩余额度，实际消耗同时记入全部祖先；结束后归还未用容量。可以分别限制字符处理、供应商 Token 和费用，并读取带执行身份的结构化子结果。

配置额度

在控制台“智能体”中新建或复制版本，在“执行额度与子调用限制”填写；已发布版本只读。SDK 注册时将以下对象放入 Agent definition 的 limits。

字段	默认	范围	含义
maxSteps	8	1–32	模型实际尝试总次数，切换候选也计数
maxToolCalls	16	0–64	模型返回的函数调用总次数，含 Tool、Agent、UI
maxAgentCalls	8	0–64	子调用次数，根入口不计；0 禁止委派
maxDepth	3	0–8	自身之下可委派层数，0 禁止继续委派
maxBudgetUnits	32000	256–1000000	序列化输入、工具描述和输出的字符处理保护量
timeoutSeconds	120	1–600	当前调用时限，与所有祖先取较早截止时间
maxProviderTokens	不限制	0–1000000000000	此调用及后代的供应商 Token 总额
maxCost	不限制	currency、amount	此调用及后代的金额上限，amount 为十进制字符串

maxTokens 是旧字符字段，保留读取兼容；新配置使用 maxBudgetUnits，两者不能同时设置。它们不是供应商计量，providerUsage 不会重复扣入字符额度。流式文本到达时立即消费字符量，越界停止继续输出或执行能力。

{
  "maxSteps": 8,
  "maxToolCalls": 16,
  "maxAgentCalls": 2,
  "maxDepth": 2,
  "maxBudgetUnits": 32000,
  "timeoutSeconds": 120,
  "maxProviderTokens": 100000,
  "maxCost": {"currency":"USD","amount":"1.00"}
}

子定义不会绕过根限制：根剩余 3 步而子定义允许 8 步时，最多预留 3 步。执行失败不返还已经消费的步数、字符或子调用计数。父调用仍需剩余容量处理子结果；根总步数应覆盖父模型、子模型和父模型总结。

供应商 Token 与费用

精确 Token/金额预留需要模型声明 capabilities.contextWindow；费用还需要完整、相同币种的 pricing。每次发送前按上下文窗口与最大输出上限保守预留，完整结束回执后按实际用量结算。配置 0 表示禁止发送。

根、祖先、当前子调用和应用配额在一个数据库事务内共同预留；任意一项不足都不会发送请求，调用账本保留 NOT_SENT。内部额度桶 period=RUN 固定为原任务周期，跨 UTC 日界不会恢复额度。runId 和 agentCallId 可用于关联查询 /quotas/usage；这些桶由系统创建，不通过公开配额策略编辑。

未知价格、上下文上限或币种不匹配会拒绝发送。已发送请求即使超时或回执丢失，也保留 UNKNOWN 预留；通过模型调用账本凭供应商证据核对，不能把未知消耗填为 0。供应商超出其声明、缓存折扣、税费或实际账单差额需核对，平台不能追回已经发生的外部费用。

SDK 示例

Java

var limits = AgentLimits.builder()
    .maxSteps(8).maxAgentCalls(2).maxBudgetUnits(32000)
    .maxProviderTokens(100000).maxCost("USD", "1.00")
    .timeoutSeconds(120).build();
var definition = Map.<String,Object>of(
    "systemPrompt", "按授权处理业务任务",
    "modelProfile", Map.of("id", "balanced", "version", "1.0.0"),
    "limits", limits.definition());
manager.register("agents", "main", "1.0.0", definition);
// USER 客户端读取自己的任务结果；子完成不会替代根任务终态。
var results = userClient.agentResults(runId, 0).toCompletableFuture().get();
for (AgentResult result : results) {
    System.out.println(result.agentId() + "@" + result.agentVersion());
    System.out.println(result.outputType()); // TEXT / JSON
    System.out.println(result.output());
    System.out.println(result.usage().get("modelInvocationIds"));
}

Kotlin

val limits = agentLimits {
    maxSteps = 8
    maxAgentCalls = 2
    maxBudgetUnits = 32000
    maxProviderTokens = 100000L
    timeoutSeconds = 120
    maxCost("USD", "1.00")
}
manager.register("agents", "main", "1.0.0") {
    field("systemPrompt", "按授权处理业务任务")
    reference("modelProfile", "balanced", "1.0.0")
    field("limits", limits.definition())
}.awaitResult()
val results = userClient.agentResultsSuspend(runId)

Java 示例说明：

注册只是创建草稿，仍需发布；委派还需要 allowedAgents 与 delegatedCapabilities 的授权上限。

前端 SDK

for await (const result of client.agentResults(runId)) {
  if (result.output.type === 'JSON') {
    console.log(result.output.value)
  }
  console.log(result.usage.modelInvocationIds)
}
// React/Vue 共用 ChatSession，成功结果会加入快照。
const snapshot = session.getSnapshot()
console.log(snapshot.agentResults)

结果携带 agentCallId、parentAgentCallId、depth、agentId、agentVersion、status、text、output、usage。TEXT 的 value 为文字；JSON 的 value 为通过 Model Profile 输出 Schema 校验的对象。身份、引用和用量由运行时生成，模型不能用同名 JSON 字段覆盖。引用列表去重、累计到祖先，模型调用编号和引用编号各最多 256 个，越界拒绝继续生成。

text 保留兼容，output 表达类型；向父模型传入完整结果而非只有字符串。结果可从授权事件读取，子文字不会追加进主回复 text.delta。前端和 Java SDK 会验证结果与完成事件身份一致并冻结快照。旧 agent.completed 没有 result 时仍可消费。

只用 message.completed 判断任务终态。子 Agent 失败/超时会让当前任务失败并保留证据；没有自动重放工具或整个任务。这里的额度支持原子分配，当前执行顺序仍为串行，不把它解释为并发子 Agent 执行。

管理页面查看结果

在“运行记录 → 详情”查看父子调用、精确版本、结构化输出、作用域用量和模型/引用编号。结果包含业务正文，读取仍受任务所有者身份及当前文档/业务权限校验；管理员凭据不能自动读取。面板允许输入运行所有者的应用凭据，此凭据只用于本次读取，提交后清空。无结果权限不影响管理员查看工具和模型事实账本。已超过事件保留窗口或归档的任务显示说明，不伪造历史结果。

在“配额与预算 → 周期使用量”中，RUN 桶显示为“智能体调用额度”，列出任务和调用编号，区别于应用 UTC 周期策略。费用未知仍保留预留，需在模型调用账本核对供应商事实。

验证与排障

现象	检查
BUDGET_EXCEEDED	当前 Agent 和全部祖先额度、应用预留、模型尝试次数
QUOTA_PRICE_UNKNOWN	金额限制要求完整价目，不能把未知当免费
QUOTA_TOKEN_BOUND_UNKNOWN	补齐模型上下文窗口，再发布新模型版本
QUOTA_CURRENCY_MISMATCH	所有当前生效金额预算须与模型币种一致
AGENT_TIMED_OUT	子调用独立时限和祖先截止时间；网络与审批同样受限
CONFIRMATION_EXPIRED	子调用已超时，审批不能继续执行危险操作

实际隔离平台已通过 SDK 注册父子 Agent、JSON 子结果、3 次供应商调用/45 Token 的根汇总、费用结算及零额度发送前拒绝。单元测试覆盖并发预留不超发、嵌套回收、局部耗尽、引用上限和较早截止时间；HTTP 测试覆盖无额度、子步骤不足、子超时与唯一任务结束。

状态：已确认；日期：2026-09-30；责任人：SparkTide 维护者；关联任务：R04；来源：AgentBudgets、ExecutionEngine、Quotas、AgentBudgetCompatibilityTest；证据：本地构建、HTTP 与 SDK 隔离实例验证。真实厂商计费与生产容量需按部署环境验证。