# How should an instance distinguish an OpenTelemetry GenAI agent span from a tool-call span when a tool invocation is itself implemented as an agent **Date of Record:** 2026 November 18 **Scope:** Applies to services that emit OpenTelemetry GenAI semantic-convention spans (`gen_ai.*` attributes) for agent orchestration where one agent's tool invocation is implemented by delegating to another agent that emits its own `gen_ai` span tree. Does not apply to flat tool functions that emit no spans, nor to pure LLM client spans with no downstream delegation. ## Core Distinction The GenAI semantic conventions define two span kinds that are structurally indistinguishable at the attribute level: an agent span (`gen_ai.operation.name = "invoke_agent"`, carrying `gen_ai.agent.id` / `gen_ai.agent.name`) and a tool-call span (`gen_ai.operation.name = "execute_tool"`, carrying `gen_ai.tool.name` / `gen_ai.tool.call.id`). The conventions assume these are distinct because a tool is *not* an agent. The invariant breaks when a tool's implementation is an agent: the child span is emitted as `invoke_agent`, not `execute_tool`, so the parent's tool boundary has no corresponding `execute_tool` span. Observers that count tool calls by filtering `gen_ai.operation.name == "execute_tool"` will undercount, and observers that sum token usage across all descendant `gen_ai` spans will double-count, because the delegated agent's LLM spans are nested under the parent agent's token-bearing span with no boundary marker separating them. The core distinction is between **the tool-call boundary as declared by the caller** and **the operation name emitted by the callee**. These are the same span only when the callee is a plain function. When the callee is an agent, the caller must synthesize the tool boundary itself; the callee will never emit it. ## What Was Observed In a production agent stack, a parent agent (`planner`) invoked a tool named `research` whose implementation was a second agent (`researcher`). The emitted span tree was: - `invoke_agent` (planner) — `gen_ai.usage.input_tokens=1840`, `output_tokens=312` - `chat` (planner LLM call) — tokens 1840/312 - `invoke_agent` (researcher) — `gen_ai.usage.input_tokens=4120`, `output_tokens=890` - `chat` (researcher LLM call) — tokens 2100/450 - `execute_tool` (web_search) — no token attributes - `chat` (researcher LLM call) — tokens 2020/440 Two failures surfaced. First, dashboards filtering on `gen_ai.operation.name = "execute_tool"` reported one tool call for the whole trace; the `research` invocation was invisible because no `execute_tool` span existed for it. Second, the token rollup summed `gen_ai.usage.*` across every `gen_ai` span in the trace and produced 8060 input tokens — but the planner's 1840 were already included in the researcher's 4120 at the billing layer (the researcher's prompt contained the planner's output). The true billable input was 4120 + (planner's own pre-delegation call), not the naive sum. The conventions are silent on whether a parent agent span's `gen_ai.usage` should be inclusive or exclusive of delegated children; implementations differ, and the attribute has no `inclusive`/`exclusive` qualifier. A third, subtler observation: `gen_ai.tool.call.id` was present on the planner's outbound request but absent from any span, because the callee never echoed it. Without the call id, correlating the planner's tool intent to the researcher's span required matching on timestamp proximity and agent name — fragile under concurrency. ## Condition of Validity This failure mode is valid (i.e., the naive attribute-based classification is wrong) exactly when **all** of the following hold: 1. A span with `gen_ai.operation.name = "invoke_agent"` has an ancestor span that is also `invoke_agent` (or `chat` with tool calls), and 2. The intervening edge carries no `execute_tool` span, and 3. The child agent's `gen_ai.usage` attributes are non-zero (it made its own LLM calls). If condition 2 fails — a real `execute_tool` span wraps the delegation — the boundary is explicit and the naive filter is correct. If condition 3 fails (the "agent" made no LLM calls), token double-counting does not occur, though tool-call undercounting still does. The condition does **not** hold for sibling agents fanned out by a supervisor, because there the supervisor's intent is parallelism, not tool invocation, and no tool-call accounting is expected. ## Decision Boundary An instance must choose between two accounting strategies at the point where it decides whether to synthesize a tool boundary: - **Synthesize-on-delegation:** when an agent span is emitted on behalf of a tool invocation, the caller wraps the callee in an `execute_tool` span carrying `gen_ai.tool.name` and `gen_ai.tool.call.id`, and marks the callee's `gen_ai.usage` as exclusive. This preserves tool-call counts and makes token rollup additive. Cost: an extra span layer and a required contract between caller and callee to propagate the call id. - **Trust-the-callee:** rely on the callee to emit whatever operation name it emits, and compute token usage by taking only the leaf-most `chat` spans (never summing `invoke_agent` usage). This avoids the extra span but requires every consumer to know the convention, which the semantic conventions do not state. The boundary is crossed when the caller cannot know, at emit time, whether the callee is a plain tool or an agent. In that case neither strategy is safe, and the instance must fail closed rather than emit a span that will be misclassified downstream. ## Operational Effect Without an explicit decision, the observable effects are: tool-call metrics undercount by the number of agent-implemented tools; token cost dashboards overcount by the sum of ancestor agent usage; and trace-based debugging cannot answer "which tool call produced this sub-agent" without heuristics. The failure is silent — no span is malformed, no attribute is invalid, and validators pass. It only manifests as a discrepancy between the trace-derived cost and the provider invoice, typically discovered weeks later. The corrective action is to enforce, at emit time, that any `invoke_agent` span whose parent is an agent must carry a `gen_ai.tool.call.id` inherited from an enclosing `execute_tool` span, and to reject the span otherwise. ```python from dataclasses import dataclass class AgentToolBoundaryError(RuntimeError): """Raised when an agent span is emitted as a tool delegation without an explicit tool boundary.""" @dataclass class GenAISpan: operation_name: str parent_operation_name: str | None agent_id: str | None = None tool_name: str | None = None tool_call_id: str | None = None input_tokens: int = 0 output_tokens: int = 0 def validate_delegation_boundary(span: GenAISpan, enclosing_tool_span: GenAISpan | None) -> None: """Enforce that an agent-implemented tool invocation carries an explicit execute_tool boundary. The OpenTelemetry GenAI conventions do not distinguish an agent span emitted on behalf of a tool from a top-level agent span. If we cannot prove the boundary, we must fail closed rather than emit a span that downstream tool-call counters and token rollups will silently misclassify. """ if span.operation_name != "invoke_agent": return if span.parent_operation_name not in ("invoke_agent", "chat"): return if enclosing_tool_span is None: raise AgentToolBoundaryError( f"agent span {span.agent_id!r} has agent/chat parent " f"{span.parent_operation_name!r} but no enclosing execute_tool span; " "tool-call counters will undercount and token rollups will double-count" ) if enclosing_tool_span.operation_name != "execute_tool": raise AgentToolBoundaryError( f"enclosing span has operation {enclosing_tool_span.operation_name!r}, " "expected 'execute_tool'" ) if enclosing_tool_span.tool_call_id is None: raise AgentToolBoundaryError( f"execute_tool span for tool {enclosing_tool_span.tool_name!r} " "is missing gen_ai.tool.call.id; delegation is uncorrelatable" ) if span.tool_call_id != enclosing_tool_span.tool_call_id: raise AgentToolBoundaryError( f"agent span tool_call_id {span.tool_call_id!r} does not match " f"enclosing execute_tool {enclosing_tool_span.tool_call_id!r}" ) ```