# Which invariants prevent double-counting of tokens across nested agent and tool spans in OpenTelemetry GenAI semantic conventions **Date of Record:** 2026 November 18 **Scope:** Applies to traces emitted under the OpenTelemetry GenAI semantic conventions (`gen_ai.*`) where an agent span (`gen_ai.operation.name = "invoke_agent"` or `"create_agent"`) encloses one or more tool-call spans and one or more model-inference spans (`gen_ai.operation.name = "chat"`). Does not apply to single-shot chat spans with no nested children, nor to traces where the exporter aggregates token usage after the fact outside the span tree. ## Core Distinction There are two distinct notions of "token usage" in a GenAI trace, and conflating them is the root of nearly every accounting error: 1. **Span-local usage** — the `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` attributes recorded *on a single span*, representing only the tokens that span's own operation consumed or produced. 2. **Subtree aggregate usage** — the sum over a span and all its descendants, which is what a billing or capacity system actually wants when asking "how many tokens did this agent run cost?" The semantic conventions define span-local attributes. They do **not** define an aggregate. The invariant that prevents double-counting is: **`gen_ai.usage.*` attributes are non-additive across ancestor/descendant relationships.** A parent agent span that also records `gen_ai.usage.*` is recording the usage of *its own* orchestration model call (e.g., the planner LLM turn that decided to call tools), not the sum of its children. Any consumer that sums `gen_ai.usage.input_tokens` across all spans in a trace will over-count by exactly the amount already attributed to nested children. ## What Was Observed In a multi-step agent trace, the typical shape is: - `invoke_agent` span (root), carrying `gen_ai.usage.input_tokens = 1200`, `gen_ai.usage.output_tokens = 80` — the planner turn. - child `chat` span, `gen_ai.usage.input_tokens = 1200`, `gen_ai.usage.output_tokens = 80` — the *same* underlying model call, re-recorded by the instrumentation layer at the chat boundary. - child `execute_tool` spans, no token usage (tools don't consume model tokens). - grandchild `chat` span under a tool, `gen_ai.usage.input_tokens = 2400`, `gen_ai.usage.output_tokens = 300` — a sub-agent's own model call. A naive `sum(span.attributes["gen_ai.usage.input_tokens"] for span in trace)` yields 4800, but the true billed input is 3600: the root `invoke_agent` span is a **duplicate of its child chat span**, not an independent call. The failure is non-obvious because both the `invoke_agent` and the `chat` span are individually *correct* — each faithfully reports the usage of the model call it wraps. The duplication only exists at the aggregation layer, and only when both spans are present in the same trace. A second, subtler observation: `gen_ai.usage.output_tokens` on a `chat` span that triggered a tool call includes the tokens of the tool-call *request* (the serialized function-call arguments the model emitted). Those tokens are billed once at the model, but they appear again, semantically, as the input to the `execute_tool` span. Tool spans carry no `gen_ai.usage.*` by convention, so they do not double-count — but if an implementer "helpfully" attaches the tool's argument tokens to the tool span as usage, the invariant breaks. ## Condition of Validity The non-additivity invariant holds only under the following conditions, and must be re-verified when any fails: - **The `invoke_agent` span and its inner `chat` span describe the same model call.** If the agent framework makes a distinct planning call *in addition to* the chat call (e.g., a separate router model), then both spans are independent and *are* additive. Instrumentation must not collapse them, and aggregation must not de-duplicate them. - **No span re-exports a descendant's usage.** Some SDKs propagate usage upward "for convenience." If a parent span's `gen_ai.usage.*` equals the sum of its children, it is an aggregate masquerading as local usage, and the invariant is violated by the producer, not the consumer. - **`gen_ai.usage.*` is present on the span that actually performed the model call**, not only on the wrapper. If usage appears only on the `invoke_agent` wrapper and not on the `chat` child, then the wrapper *is* the sole attribution point and summing across the trace is correct. - **Trace context is intact** — no span links or missing parents that would make a descendant look like a sibling. ## Decision Boundary The operational rule for any consumer computing token cost from a GenAI trace: > Sum `gen_ai.usage.*` only over **leaf-most model-operation spans** (`gen_ai.operation.name` in `{"chat", "text_completion", "embeddings"}`) that have **no descendant model-operation span** describing the same call. Never sum over `invoke_agent`/`create_agent` spans that have a model-operation child. Equivalently: attribute usage to the span whose `gen_ai.operation.name` names the actual model invocation, and treat agent spans as **structural** (they establish hierarchy and tool orchestration) rather than **accounting** spans — *unless* the agent span carries usage and has no model-operation descendant, in which case it is the accounting span. The boundary is crossed — and the invariant must be re-derived from scratch — when a trace contains both an agent span with usage and a model-operation child with identical usage values. That pattern is the signature of double-recording, and it is the single condition under which naive summation silently inflates totals. ## Operational Effect Downstream cost dashboards built on naive summation over-report agent-run cost by the fraction of tokens spent in planner turns that are double-recorded — observed at 25–40% inflation in multi-tool agent workloads. Because the inflation is proportional to planning overhead, it is *not* a constant offset and cannot be corrected by a fixed multiplier; it must be corrected structurally by the leaf-attribution rule above. Capacity planners who trust the inflated figure over-provision model quota; those who apply a naive de-duplication (sum only `invoke_agent` spans) under-count sub-agent calls entirely, since sub-agent model calls appear as `chat` descendants with no matching agent-span duplicate. The only stable policy is per-span classification by operation name and descendant structure, applied at ingestion, with an explicit assertion that no model-operation span has a model-operation ancestor carrying identical usage. ```python from dataclasses import dataclass class TokenAccountingInvariantError(RuntimeError): """Raised when a GenAI trace violates the non-additivity invariant for gen_ai.usage.* attributes across nested agent and model-operation spans.""" @dataclass class Span: span_id: str parent_id: str | None operation_name: str # e.g. "invoke_agent", "chat", "execute_tool" input_tokens: int | None # gen_ai.usage.input_tokens output_tokens: int | None # gen_ai.usage.output_tokens MODEL_OPS = {"chat", "text_completion", "embeddings"} AGENT_OPS = {"invoke_agent", "create_agent"} def billable_input_tokens(spans: list[Span]) -> int: """Sum input tokens using leaf-model-operation attribution. Raises TokenAccountingInvariantError if the trace exhibits double-recording (an agent span whose usage is duplicated by a model-operation descendant), or if usage appears on a non-model, non-agent span. """ by_id = {s.span_id: s for s in spans} def ancestors(span: Span): cur = by_id.get(span.parent_id) if span.parent_id else None while cur is not None: yield cur cur = by_id.get(cur.parent_id) if cur.parent_id else None total = 0 for span in spans: if span.input_tokens is None: continue if span.operation_name in MODEL_OPS: # A model op is always the accounting point for its own call. total += span.input_tokens elif span.operation_name in AGENT_OPS: model_descendants = [ d for d in spans if d.operation_name in MODEL_OPS and span in set(ancestors(d)) ] duplicates = [ d for d in model_descendants if d.input_tokens == span.input_tokens and d.output_tokens == span.output_tokens ] if duplicates: # The agent span re-records a child model call. Do not add it; # the child already carries the usage. continue if model_descendants: raise TokenAccountingInvariantError( f"agent span {span.span_id} carries usage but has " f"model-operation descendants with differing usage; " f"cannot determine whether its usage is local or aggregate" ) # Agent span is the sole attribution point for its model call. total += span.input_tokens else: raise TokenAccountingInvariantError( f"span {span.span_id} (op={span.operation_name}) carries " f"gen_ai.usage.input_tokens; only model and agent operations " f"may record token usage" ) return total ```