# How should an instance treat OpenTelemetry GenAI agent spans when tool-call children outlive their parent span **Date of Record:** 2026 November 16 **Scope:** Applies to services emitting OpenTelemetry `gen_ai.*` spans for agentic loops where a tool invocation is executed asynchronously or by a remote worker and may complete after the enclosing agent span has ended. Does not apply to synchronous in-process tool calls whose lifetime is strictly nested within the agent span. ## Core Distinction The GenAI semantic conventions model an agent turn as a parent span (`gen_ai.operation.name = "invoke_agent"`) with child spans for each tool call (`gen_ai.operation.name = "execute_tool"`). The invariant most implementers assume is *temporal nesting*: a child span cannot end after its parent. OpenTelemetry's span model does **not** enforce this — it only records start/end timestamps. A child span whose `end_time` exceeds the parent's `end_time` is structurally valid but semantically orphaned: exporters, backends, and token aggregators that roll up `gen_ai.usage.input_tokens` / `output_tokens` from children into the parent will either drop the late child or double-count it depending on flush ordering. The non-obvious boundary: **the agent span's end timestamp is a commit point for token accounting, but the tool span's end is a commit point for side effects.** These two commit points are not the same instant, and the semantic conventions do not tell you which one owns the token cost of the tool's own LLM calls (a tool that itself invokes a model emits a nested `gen_ai.client` span with its own usage attributes). ## What Was Observed A planner agent span ended at T+4200ms after emitting a final assistant message. One tool child — a `web_search` implementation that internally calls a summarizer model — was dispatched to a remote worker and did not close until T+9100ms. The summarizer's `gen_ai.client` span carried `gen_ai.usage.input_tokens = 3120`. Two failure modes appeared simultaneously: 1. The parent agent span's aggregated `gen_ai.usage.output_tokens` (computed at parent-end by summing completed children) excluded the summarizer's tokens, under-reporting cost by ~18%. 2. A second aggregator that scanned all descendants by `trace_id` *after* trace completion included the tokens but attributed them to the parent's end timestamp, producing a negative "tokens per second" for the window between T+4200 and T+9100 because no parent span was open. Neither aggregator was wrong per the spec. The spec is silent on late-closing children. ## Condition of Validity Temporal nesting holds only when: (a) all tool spans are synchronous and awaited before the agent span closes, **or** (b) the agent span is kept open until all dispatched tool futures resolve. Condition (b) is the only correct choice for async tool execution, but it conflicts with a common optimization: closing the agent span at final-message emission to reduce trace latency. That optimization is invalid whenever any child tool can emit its own `gen_ai.*` usage. A second validity condition: token roll-up is only sound if the aggregator uses **span-tree structure plus end-time ordering**, not end-time alone. Summing by timestamp window is unsound under late children. ## Decision Boundary Choose to **hold the agent span open** (await all tool futures, then close) when any of the following hold: - Any tool is dispatched to a remote worker or queue. - Any tool may itself emit `gen_ai.client` spans with usage attributes. - Downstream cost attribution requires per-agent totals. Choose to **close early and emit a synthetic `gen_ai.agent.turn_complete` event** only when tools are strictly synchronous and side-effect-free with respect to token accounting. In the early-close case, the tool spans must be re-parented to a `gen_ai.operation.name = "invoke_agent.continuation"` span, or the backend must be told (via a `gen_ai.late_child = true` attribute) to attribute usage to the trace, not the agent. ## Operational Effect Holding the agent span open increases trace wall-clock latency by the slowest tool's duration but makes token accounting exact and monotonic. It also prevents the negative-throughput artifact. The cost is a longer-lived span object in memory and a later flush; for agents with 30s+ tool timeouts this matters for exporter batch sizing. The mitigation is to emit a `gen_ai.agent.tool_dispatched` event at dispatch time so downstream consumers can compute provisional cost before the span closes, while treating the final close as authoritative. ```python import time from dataclasses import dataclass, field class LateToolChildError(RuntimeError): """Raised when a tool span closes after its enclosing agent span.""" pass @dataclass class Span: name: str operation: str start_ns: int end_ns: int | None = None usage_input: int = 0 usage_output: int = 0 children: list["Span"] = field(default_factory=list) def close(self, now_ns: int) -> None: self.end_ns = now_ns def validate_agent_span(agent: Span) -> None: if agent.operation != "invoke_agent": raise LateToolChildError(f"not an agent span: {agent.operation}") if agent.end_ns is None: raise LateToolChildError("agent span never closed; cannot validate") for child in agent.children: if child.end_ns is None: raise LateToolChildError( f"tool child {child.name!r} still open at agent close" ) if child.end_ns > agent.end_ns: raise LateToolChildError( f"tool child {child.name!r} closed {child.end_ns - agent.end_ns}ns " f"after parent agent span; token roll-up would be unsound" ) def aggregate_usage(agent: Span) -> tuple[int, int]: validate_agent_span(agent) total_in = agent.usage_input total_out = agent.usage_output for child in agent.children: total_in += child.usage_input total_out += child.usage_output return total_in, total_out # Correct pattern: await all dispatched tools before closing the agent span. def run_agent_turn(dispatch_tools, now_ns=lambda: time.monotonic_ns()) -> Span: agent = Span("agent.turn", "invoke_agent", start_ns=now_ns()) futures = dispatch_tools() for fut in futures: # hold the parent open until every child resolves child = fut.result() child.close(now_ns()) agent.children.append(child) agent.close(now_ns()) aggregate_usage(agent) # raises LateToolChildError if invariant broken return agent ```