anthropics / anthropics/claude-agent-sdk-typescript

Feature request: per-subagent breakdown in modelUsage for cost/token attribution

未关闭
#293 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
enhancement
主要语言
Shell
星标
1.8k
派生
226
PR 合并指标
30 天内没有已合并 PR

描述

When running subagents via `options.agents` and `AgentDefinition`, `tool_use` / `tool_result` events correctly carry `parent_tool_use_id`, so per-subagent **activity** (call counts, errors, latency) is observable on the consumer side. But `SDKResultMessage.modelUsage` is keyed by model ID only, so when parent and subagent share a model (the default with `model: "inherit"`), their token/cost usage collapses into a single bucket.

## Impact

We cannot answer basic operational questions on an SDK app that delegates to subagents:

- What % of token spend went to subagent X last week?
- Is subagent X worth its latency on a cost basis?
- Which subagent is the most expensive?

Only indirect answers (proxy via tool-call volume, or A/B replay) are possible today, which makes subagent-rollout decisions data-poor.

## Proposed shape

Add a `subagentUsage: Record` field on `SDKResultMessage` alongside the existing `modelUsage`, keyed by subagent name (or `"parent"` for work done at the top level). Inherits the same `ModelUsageEntry` shape (`inputTokens`, `outputTokens`, `cacheReadInputTokens`, `cacheCreationInputTokens`, `costUSD`, `contextWindow`).

## Alternatives considered

- **Force a different model per subagent so `modelUsage` proxies as per-subagent split.** Defeats the prompt-cache advantage of `"inherit"` and couples model choice to telemetry.
- **Consumer-side inference by timing `tool_use` events with `parent_tool_use_id`.** Cannot recover token counts or cost; only latency.
- **OpenTelemetry spans (see anthropics/claude-agent-sdk-python#452).** A broader solution but orthogonal and much larger scope. Per-subagent `modelUsage` is the targeted fix.

## Repro

Any SDK app using `options.agents` with the default `model: "inherit"`: `result.modelUsage` has one entry per model used, not per subagent.

## Docs note

The [Subagents in the SDK](https://code.claude.com/docs/en/agent-sdk/subagents) page lists the benefits of context isolation, parallelization, and tool restrictions — but makes no mention of how to attribute cost/tokens to a subagent. Adding this field would make that story complete.

## Related

- #112 — `usage` vs. `modelUsage` discrepancy.
- #139 (closed) — added `contextWindowUsage` to `ModelUsage`. Precedent that this shape is the right place to add fields.

贡献指南

这个仓库没有索引到贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。