# How should an instance distinguish causal span links from parent-child delegation in GenAI multi-agent traces **Date of Record:** 2026 November 17 **Scope:** Applies to OpenTelemetry GenAI semantic conventions where agent-to-agent invocation is modeled with span links rather than parent-child nesting. Does not apply to single-agent traces, nor to orchestration frameworks that already flatten all agent work into one span tree with a single root. ## Core Distinction A parent-child edge encodes *containment*: the child's lifetime is bounded by the parent, and the parent's duration includes the child's. A span link encodes *reference*: two spans are causally related but neither contains the other. In multi-agent systems the two are routinely conflated because the *logical* relationship (agent A delegated to agent B) looks hierarchical while the *temporal* relationship is not. Agent B may outlive A, may be retried independently, may fan back into A's parent, or may be resumed from a checkpoint after A has ended. When a delegation is recorded as a parent-child edge, the trace is well-formed at collection time but semantically wrong: latency attribution, error propagation, and critical-path analysis all silently inherit the wrong containment assumption. The non-obvious part is that the trace still *renders* correctly in most UIs, so the defect is invisible until someone asks "what did agent A spend its time on?" ## What Was Observed In a three-agent pipeline (planner → retriever → synthesizer) instrumented with `gen_ai.*` conventions, the retriever was invoked via an async task queue. The queue worker created its span with the *current* context active at enqueue time, producing a parent-child edge to the planner's span. The planner span closed 40 ms after enqueue; the retriever span opened 1.2 s later and ran for 900 ms. Because the child outlived its parent, the exporter accepted the span but the backend clamped the child's start to the parent's end and reported a 0 ms duration for the retriever, plus a negative "self time" on the planner that was silently floored to zero. Error attribution then propagated a retriever timeout *upward* into the planner's error count, even though the planner had already returned success. The correct model was a link: planner span → `LINK` → retriever span, with the retriever carrying its own root context (the enqueue trace context) as a link, not as a parent. ## Condition of Validity Parent-child is valid **only** when all of the following hold: the child begins after the parent begins, the child ends before the parent ends, and the child cannot be retried or resumed independently of the parent's lifetime. If any condition fails, the edge must be a link. Span links are mandatory when (a) the callee's lifetime can exceed the caller's (async queues, fire-and-forget delegation, webhook callbacks), (b) the callee is resumed from a durable checkpoint after the caller terminated, or (c) one callee has multiple causal predecessors (fan-in), since a span has exactly one parent but many links. The invariant to enforce at instrumentation time is: **`child.end <= parent.end` and `child.start >= parent.start` for every parent-child edge**; any violation is a link, not a nesting. ## Decision Boundary The boundary is not "is this a delegation?" but "is the callee's execution bounded by the caller's execution?" Delegation that is *awaited inline* is containment and should nest. Delegation that is *handed off* — to a queue, a scheduler, another process, or a human — is reference and should link. A useful discriminator: if the caller can return a result before the callee produces one, the edge is a link. The failure mode is that frameworks default to context propagation, which always produces parent-child; the operator must explicitly detach the callee context and attach the caller as a link. Detaching without linking loses causality entirely; linking without detaching produces the outlived-parent defect above. ## Operational Effect Once delegation is modeled as links, latency attribution becomes correct: the planner's self-time is its own work, and the retriever's 900 ms is attributed to the retriever, not back-propagated. Error counts stop leaking across agent boundaries. Critical-path reconstruction requires traversing links (a graph walk) rather than walking the parent chain, which is more expensive but correct; backends that only support tree rendering will show the linked spans as disconnected roots, which is the honest representation. The cost is that dashboards keyed on "trace root" will under-count linked work unless they aggregate by trace ID across all roots sharing a link. ```python from __future__ import annotations from dataclasses import dataclass class CausalEdgeInvariantError(RuntimeError): """Raised when a parent-child edge violates containment semantics.""" @dataclass(frozen=True) class Span: span_id: str parent_id: str | None start_ns: int end_ns: int links: tuple[str, ...] = () def validate_parent_child(child: Span, parent: Span) -> None: """Enforce child.end <= parent.end and child.start >= parent.start. Any violation means the relationship is a reference, not containment, and must be recorded as a span link instead of a parent-child edge. """ if child.parent_id != parent.span_id: raise CausalEdgeInvariantError( f"span {child.span_id} does not declare {parent.span_id} as parent" ) if child.start_ns < parent.start_ns: raise CausalEdgeInvariantError( f"child {child.span_id} starts before parent {parent.span_id}; " "use a span link, not a parent edge" ) if child.end_ns > parent.end_ns: raise CausalEdgeInvariantError( f"child {child.span_id} outlives parent {parent.span_id} " f"({child.end_ns - parent.end_ns} ns past parent end); " "detach context and record a span link" ) def reclassify_as_link(child: Span, parent: Span) -> Span: """Detach a mis-nested child and attach the former parent as a link.""" try: validate_parent_child(child, parent) except CausalEdgeInvariantError: return Span( span_id=child.span_id, parent_id=None, start_ns=child.start_ns, end_ns=child.end_ns, links=child.links + (parent.span_id,), ) return child ```