# Under what conditions must an instance treat a GenAI agent span's token accounting as authoritative across tool-call boundaries **Date of Record:** 2026 November 18 **Scope:** Applies to OpenTelemetry instrumentation of LLM agent loops that emit `gen_ai.*` spans with nested tool-call spans and accumulate `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens`. Does not apply to single-shot completion calls with no tool dispatch, nor to provider-side billing reconciliation, which uses a different source of truth. ## Core Distinction There is a persistent confusion between *span-local usage* and *run-cumulative usage*. The GenAI semantic conventions define `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` as attributes of a single inference span — the tokens consumed by *that* model invocation. They are not, and were never specified to be, additive across a parent agent span that wraps multiple inference calls and interleaved tool executions. An agent span (`gen_ai.operation.name = "invoke_agent"` or the `create_agent`/`execute_tool` family) is a *container*. Its children are inference spans and tool spans. Tool spans consume **no** model tokens — they consume wall-clock time, external API quota, and possibly their own provider tokens that are *not* GenAI tokens. When an instrumentor naively sums `gen_ai.usage.*` from all descendant spans onto the agent span, it double-counts any inference span that is a descendant of a tool span (e.g., a nested sub-agent invoked *by* a tool), and it silently attributes tool-execution time to model latency. The invariant: **a GenAI usage attribute is authoritative only for the span on which it was directly recorded, by the process that made the model call.** Aggregation is a *derived* quantity and must be marked as such. ## What Was Observed A multi-agent orchestration emitted a parent `invoke_agent` span with three children: two `chat` inference spans and one `execute_tool` span that itself dispatched a sub-agent (which emitted its own `invoke_agent` → `chat` chain). The exporter's span processor computed parent usage by summing all descendants with `gen_ai.usage.input_tokens` present. Observed result: parent `input_tokens` = 41,882. Ground truth from provider receipts = 27,310. The delta (14,572) was exactly the sub-agent's nested chat spans, counted once on the sub-agent's agent span and again on the root. Downstream cost dashboards over-reported by 53% for that trace, and the over-report was *structurally correlated* with sub-agent fan-out — so it looked like a real workload shift rather than an instrumentation bug. A second, subtler observation: `execute_tool` spans occasionally carried `gen_ai.usage.output_tokens` because a tool implementation reused a shared helper that stamped usage attributes onto whatever span was current. These were tool-side tokens (e.g., an embedding call inside the tool), not agent tokens, and they leaked into the agent total. ## Condition of Validity Treat a usage attribute as authoritative **if and only if** all of the following hold: 1. The attribute is present on a span whose `gen_ai.operation.name` is a model-invocation operation (`chat`, `text_completion`, `embeddings`, or a provider-namespaced equivalent) — not on `execute_tool` or an agent container. 2. The span has no descendant span that also carries `gen_ai.usage.*` for the same operation family, **or** the aggregator explicitly deduplicates by span identity rather than summing. 3. The recording process is the same process that issued the model request (i.e., the attribute was not propagated across a process boundary via context injection). 4. The span's status is not `ERROR` with a transport-level failure where the provider may have partially billed — in that case usage is *unknown*, not zero, and must be represented as absent, not as `0`. If any condition fails, the value is advisory and must be tagged (e.g., a derived/cumulative attribute in a distinct namespace) so that consumers do not treat it as billable ground truth. ## Decision Boundary The boundary is *span ownership*, not span nesting. A parent agent span does **not** own its children's token counts. It owns only the tokens of inference calls it directly initiated. The decision to aggregate is a presentation choice; the decision to *authorize* aggregation as truth is a correctness choice. Concretely: if you find yourself summing `gen_ai.usage.input_tokens` over `span.descendants()` and writing the result to the parent's `gen_ai.usage.input_tokens`, you have crossed the boundary and produced a non-authoritative value under an authoritative key. Rename the attribute or drop it. Do not "fix" it by subtracting tool-span tokens — tool spans that contain nested inference spans make subtraction lossy and non-idempotent. ## Operational Effect Downstream consumers (cost allocators, rate limiters, anomaly detectors) keyed on `gen_ai.usage.*` will over-count in proportion to agent nesting depth. Because nesting depth correlates with task complexity, the error masquerades as a workload signal. Rate limiters that budget against these totals will throttle complex agents earlier than simple ones — an emergent, unintended fairness policy. The correct operational posture is: emit usage only at the inference span, expose aggregation as a separately-named derived metric with an explicit `derived=true` marker, and treat absent usage on error spans as unknown rather than zero. ```python from __future__ import annotations from dataclasses import dataclass, field class NonAuthoritativeUsageError(RuntimeError): """Raised when usage attributes are aggregated across a boundary that makes them non-authoritative (tool spans, nested agents, or error spans).""" MODEL_OPS = {"chat", "text_completion", "embeddings"} @dataclass class Span: name: str operation: str attributes: dict = field(default_factory=dict) status: str = "OK" children: list["Span"] = field(default_factory=list) def has_usage(self) -> bool: return any(k.startswith("gen_ai.usage.") for k in self.attributes) def aggregate_authoritative_usage(root: Span) -> int: """Sum input_tokens only over model-invocation spans owned by *this* process, refusing to fold in tool spans or nested agent containers.""" total = 0 stack = [root] while stack: span = stack.pop() if span.operation == "execute_tool" and span.has_usage(): raise NonAuthoritativeUsageError( f"tool span {span.name!r} carries gen_ai.usage.*; " "these are tool-side tokens, not agent tokens" ) if span.operation in MODEL_OPS: if span.status == "ERROR" and "gen_ai.usage.input_tokens" not in span.attributes: raise NonAuthoritativeUsageError( f"model span {span.name!r} failed with unknown usage; " "absent != zero and must not be summed" ) total += int(span.attributes.get("gen_ai.usage.input_tokens", 0)) # Do not descend into children of a model span: they belong to # a different ownership boundary (e.g., a tool the model called). continue stack.extend(span.children) return total ```