# When must an instance emit a distinct span link instead of a parent-child edge in GenAI multi-agent traces **Date of Record:** 2026 November 15 **Scope:** Applies to OpenTelemetry-style GenAI semantic conventions where a single logical request fans out across agent invocations, tool calls, and retrieval steps that each produce spans. Does not apply to single-threaded, single-agent traces where every child has exactly one causal predecessor, nor to pure RPC propagation where W3C `traceparent` already encodes the only causal edge. ## Core Distinction A **parent-child edge** asserts *containment and exclusive causality*: the child span exists only as a phase of the parent, and the parent's duration brackets the child's. A **span link** asserts *causality without containment*: the linked span is a causal antecedent or co-cause, but it does not nest inside the linking span, and the linking span may have a different root or a different temporal envelope. The non-obvious boundary is this: the moment a tool call or sub-agent is *reused* or *co-caused*, the parent-child relation becomes a lie that silently corrupts critical-path analysis. Two agent turns that both read the same cached retrieval result, or a tool call whose result is consumed by a sibling agent, cannot both be children of that tool span without creating a span with multiple parents — which the data model forbids — or duplicating the span, which double-counts latency and cost. ## What Was Observed In a three-agent pipeline (planner → retriever → synthesizer) with a shared tool executor, the executor span was conventionally parented under the *first* agent that invoked it. When the synthesizer later re-invoked the same logical tool operation within a deduplication window, the second call was recorded as a child of the first, producing: - **Inverted timestamps:** child `start_time` earlier than parent `start_time` for the deduplicated second call, because the child was re-emitted with the original timestamp while its "parent" was a later invocation. - **Critical-path inflation:** the tool executor's duration was attributed twice to the planner subtree, making the planner appear to dominate end-to-end latency when the synthesizer was the real bottleneck. - **Broken causal reconstruction:** a consumer walking parent pointers could not distinguish "planner caused this tool call" from "synthesizer reused a result the planner triggered." The tell was that span-level `gen_ai.operation.name` and `gen_ai.tool.name` were identical across the two edges while `trace_id` matched but `span_id` parentage diverged from wall-clock ordering. ## Condition of Validity A parent-child edge is valid **only if all three hold**: 1. **Temporal containment:** `child.start_time >= parent.start_time` and `child.end_time <= parent.end_time` within clock-skew tolerance. 2. **Exclusive causal ownership:** exactly one span in the trace claims this child as its direct descendant. 3. **Lifecycle subordination:** the child cannot outlive or begin before the parent's execution context. When any condition fails — reuse, fan-in from multiple agents, deduplication, or a tool result consumed after its originating span closed — the correct encoding is a **span link** from the consuming span to the producing span, with `link.type = "caused_by"` (or the semantic-convention equivalent), and **no parent pointer**. ## Decision Boundary Emit a **link, not a child edge**, when: - A tool result or sub-agent output is consumed by a span that did not directly invoke it (reuse / memoization / cache hit). - A span has **more than one genuine causal predecessor** (fan-in from parallel agents into a synthesizer). - The producing span's temporal envelope does **not** contain the consuming span (async, queued, or deferred execution). - The same logical operation is **deduplicated** across invocations and re-emitted once. Emit a **child edge** only when the invocation is synchronous, exclusive, and temporally nested. If you are unsure, prefer a link plus an explicit `caused_by` attribute: a missing parent is recoverable by graph traversal over links; a *wrong* parent is not, because it silently poisons every downstream latency and cost rollup. ## Operational Effect Correctly distinguishing links from edges changes three downstream computations: critical-path latency (no double attribution), cost attribution per agent (no phantom re-charge to the first invoker), and causal replay (the graph remains a DAG of *causes*, not a tree of *containment*). Teams that conflate the two typically discover the defect only when a latency SLO regresses with no corresponding change in any single agent's own timing — the classic signature of a mis-parented shared tool call. ```python from dataclasses import dataclass class SpanCausalityError(RuntimeError): """Raised when a span is about to be encoded with an invalid causal edge.""" pass @dataclass class SpanRecord: span_id: str parent_id: str | None start_time: float end_time: float operation: str def encode_causal_edge( producer: SpanRecord, consumer: SpanRecord, *, reused: bool, concurrent_predecessors: int, skew_tolerance: float = 0.005, ) -> str: """ Decide whether consumer should parent under producer or link to it. Returns 'child' or 'link'. Raises SpanCausalityError on an unrepresentable relation that must not be silently coerced. """ contained = ( consumer.start_time >= producer.start_time - skew_tolerance and consumer.end_time <= producer.end_time + skew_tolerance ) # Reuse or fan-in: containment is irrelevant, causality must be a link. if reused or concurrent_predecessors > 1: return "link" if not contained: # Consumer outlives or predates producer: a parent edge would # invert timestamps and corrupt critical-path analysis. raise SpanCausalityError( f"span {consumer.span_id} ({consumer.operation}) is not temporally " f"contained by {producer.span_id} ({producer.operation}); " f"encode as a link with caused_by, not a parent-child edge" ) return "child" ```