# Under what conditions must an instance treat a GenAI agent span's tool-call child as non-retryable when the parent span reports `error.type=timeout` **Date of Record:** 2026 November 18 **Scope:** Applies to OpenTelemetry GenAI semantic conventions (as of the `gen_ai.*` attribute namespace, agent and tool invocation spans) emitted by an agent runtime that issues tool calls as child spans under an `execute_tool` / `invoke_agent` parent. Does not apply to plain HTTP client spans, to non-agent LLM completion spans, or to runtimes that do not emit `gen_ai.operation.name` on both parent and child. ## Core Distinction The failure is a *semantic conflation between the parent span's termination reason and the child span's retryability*. A parent `invoke_agent` span that ends with `error.type=timeout` and `otel.status_code=ERROR` tells you the *agent turn* exceeded its wall-clock budget. It does **not** tell you that the tool call beneath it failed in a retryable way. The child `execute_tool` span may have: 1. Completed successfully (`status=OK`, `gen_ai.tool.call.id` present) but the *aggregate* agent turn still timed out waiting on a *different* sibling or on model reasoning after the tool returned. 2. Been cancelled mid-flight by the parent's deadline (`status=UNSET` or `ERROR` with `error.type=cancelled`), meaning the tool may or may not have executed server-side — an at-most-once vs. at-least-once ambiguity. 3. Genuinely timed out (`error.type=timeout` on the child itself), which is the only case where naive retry logic is defensible. The non-obvious invariant: **the parent's `error.type` is not a valid inheritance source for the child's retry decision.** OTel does not define a propagation rule that copies `error.type` downward, and the spec explicitly scopes `error.type` to the span on which it is recorded. Any retry controller that reads the parent's `error.type` and applies it to all child tool calls will misclassify cases 1 and 2. ## What Was Observed In a traced agent run, the span tree looked like: ``` invoke_agent (status=ERROR, error.type=timeout, gen_ai.agent.name=planner) ├── execute_tool (status=OK, gen_ai.tool.name=search, gen_ai.tool.call.id=call_a1) ├── execute_tool (status=UNSET, gen_ai.tool.name=db_write, gen_ai.tool.call.id=call_b2) <- cancelled by parent deadline └── chat (model re-reasoning after tool returns) (status=ERROR, error.type=timeout) ``` The retry controller observed the root `error.type=timeout` and re-issued **both** tool calls. `call_a1` (search) was idempotent and harmless. `call_b2` (`db_write`) had *already committed server-side* before the cancellation signal arrived — the child span was `UNSET` precisely because the cancellation raced the write. The retry produced a duplicate write, and because `gen_ai.tool.call.id` was regenerated on retry (the runtime minted a fresh UUID), downstream deduplication keyed on call-id could not catch it. The tell was in the child spans all along: `call_a1` had `status=OK`, and `call_b2` had no `error.type` of its own and no `status=ERROR`. Neither child independently justified a retry. Only the parent did, and only for the *reasoning* step, not the tool steps. ## Condition of Validity The "do not retry the child" rule is valid **only** when all of the following hold: - The child `execute_tool` span carries its own `otel.status_code` that is not `ERROR`, **or** carries `ERROR` with `error.type` distinct from the parent's. - The child is not marked `retryable` by any explicit attribute (there is no standard `gen_ai.tool.retryable` attribute; if a vendor adds one, it overrides this heuristic). - The parent's `error.type=timeout` is attributable to the *agent turn deadline*, evidenced by the parent span's `end_time` exceeding the configured turn budget and by at least one sibling (`chat` or another tool) owning the actual timeout. - The tool is not declared idempotent by the runtime's tool registry. If the child itself carries `error.type=timeout` and `status=ERROR`, the rule does **not** hold — that child is a genuine tool-level timeout and is retryable subject to the tool's idempotency class. If the child is `UNSET` with no `error.type` and the parent timed out, the rule is *ambiguous*: the tool may have partially executed. Treat `UNSET`-under-cancelled-parent as **non-retryable without a server-side idempotency key**, because the ambiguity is exactly the at-least-once hazard. ## Decision Boundary The boundary is between *span-level error attribution* and *operation-level retry policy*. Concretely: - **Retry** the child iff `child.status_code == ERROR and child.error_type in {timeout, unavailable, rate_limited}` and the tool is idempotent or carries a caller-supplied idempotency key. - **Do not retry** the child iff `child.status_code in {OK, UNSET}` and the parent is the only span with `ERROR`, regardless of the parent's `error.type`. - **Escalate to human/manual reconciliation** iff `child.status_code == UNSET and parent.error_type == timeout and tool is not idempotent`. This is the dangerous quadrant. - **Never** propagate `error.type` from parent to child. OTel's `error.type` is a per-span attribute; the spec does not define downward inheritance, and relying on it is a category error. A useful invariant to encode: `retryable(child) = f(child.attributes)` only. The parent's attributes may inform *agent-turn* retry (re-planning), never *tool-call* retry. ## Operational Effect Runtimes that violate this boundary exhibit duplicate side effects on non-idempotent tools during agent-turn timeouts — the most common real-world instance being duplicate writes, duplicate emails, or duplicate payment captures when the agent's deadline fires while a tool call is in flight. The blast radius is bounded by the tool's side-effect class, but the *diagnosis* is hard because the trace shows a single root `error.type=timeout` and the duplicate is only visible downstream. Encoding the child-first retry predicate, and treating `UNSET`-under-cancelled-parent as a manual-reconciliation quadrant, eliminates the class. The cost is that some genuinely-retryable tool calls (those cancelled by an over-aggressive turn deadline) are surfaced for reconciliation rather than auto-retried — an acceptable trade against silent duplication. ```python class ToolRetryAmbiguityError(RuntimeError): """Raised when a tool-call child span's retryability cannot be decided from its own attributes, and the parent's error.type must not be inherited.""" RETRYABLE_CHILD_ERROR_TYPES = frozenset({"timeout", "unavailable", "rate_limited"}) def decide_tool_retry(child_span: dict, parent_span: dict, tool_is_idempotent: bool) -> bool: child_status = child_span.get("status_code") # "OK" | "ERROR" | "UNSET" child_error_type = child_span.get("error_type") parent_error_type = parent_span.get("error_type") # Child-level retryable error: trust the child, not the parent. if child_status == "ERROR" and child_error_type in RETRYABLE_CHILD_ERROR_TYPES: if tool_is_idempotent or child_span.get("idempotency_key"): return True raise ToolRetryAmbiguityError( f"tool {child_span.get('tool_name')} errored with {child_error_type} " f"but is non-idempotent and carries no idempotency key" ) # Child succeeded or was cancelled mid-flight. Parent timeout is irrelevant # to the child's retry decision. if child_status in ("OK", "UNSET"): if child_status == "UNSET" and parent_error_type == "timeout" and not tool_is_idempotent: raise ToolRetryAmbiguityError( f"tool {child_span.get('tool_name')} is UNSET under a timed-out parent; " f"execution state unknown, manual reconciliation required" ) return False # Child ERROR with a non-retryable error_type (e.g. invalid_argument). return False ```