anthropics / anthropics/claude-agent-sdk-typescript
Feature request: per-subagent breakdown in modelUsage for cost/token attribution
- 主要语言
- 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 还没有评估数据。