{
  "schema_version": "1.3.0",
  "slug": "why-does-an-instance-of-the-opentelemetry-genai-agent-span-silently-lose-tool-call-attribution-when-the-tool-invocation-outlives-the-enclosing-agent-s",
  "title": "Why does an instance of the OpenTelemetry GenAI agent span silently lose tool-call attribution when the tool invocation outlives the enclosing agent span",
  "date_of_record": "2026 November 17",
  "scope": "Applies to instrumentations emitting `gen_ai.*` spans per the OpenTelemetry GenAI semantic conventions where an agent span (`gen_ai.operation.name = \"invoke_agent\"`) encloses tool executions (`gen_ai.operation.name = \"execute_tool\"`). Does not apply to synchronous in-process tool calls that complete before the agent span ends, nor to backends that reconstruct causality from a separate trace propagation mechanism.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/why-does-an-instance-of-the-opentelemetry-genai-agent-span-silently-lose-tool-call-attribution-when-the-tool-invocation-outlives-the-enclosing-agent-s.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/why-does-an-instance-of-the-opentelemetry-genai-agent-span-silently-lose-tool-call-attribution-when-the-tool-invocation-outlives-the-enclosing-agent-s.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/why-does-an-instance-of-the-opentelemetry-genai-agent-span-silently-lose-tool-call-attribution-when-the-tool-invocation-outlives-the-enclosing-agent-s.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1525,
    "python_slice_tokens": 318,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The GenAI conventions define tool-call telemetry along two axes: spans (`execute_tool`) and attributes on the *agent* span summarizing the turn (`gen_ai.agent.tool_calls`, token counts, finish reasons). These are two distinct records of the same event, and they are joined only by parent-child span relationships and by attribute snapshots taken at span *end* ...",
    "what_was_observed": "Consider an agent span opened at turn start, with `gen_ai.agent.tool_calls` and `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` set as the model streams and requests tools. The agent then dispatches a tool call that is asynchronous or long-running (a web fetch, a code-execution sandbox, a human-in-the-loop approval). Two orderings occur in practice: 1. **Buffered/exported-at-end attributes.** Many SDKs sna...",
    "condition_of_validity": "The invariant \"the agent span's `gen_ai.agent.tool_calls` equals the number of `execute_tool` children, and `gen_ai.usage.*` equals the sum over model-call children\" holds **only if** every tool dispatched by the agent completes before the agent span ends, and every model call in the turn is parented to the agent span and ends before it. It is violated whene...",
    "decision_boundary": "The operational choice is where to close the agent span: - **Close at model-turn end** (common default): low latency to export, but aggregate attributes are provably incomplete for async tools. Acceptable only if no consumer reads agent-level `tool_calls`/`usage` as authoritative. - **Close at agent-loop end** (after all dispatched tools return and all follo...",
    "operational_effect": "The concrete effect is a stable, low-noise bias: fast tools are counted, slow and failing tools are systematically excluded from agent-level aggregates. Tool success rate computed from the agent rollup trends *upward* as failures get slower; cost dashboards undercount exactly the turns that ran the most tools. Because the bias is deterministic and correlated..."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "b95064413c61b2203c1bbd120f55628fbcefbadadb6a92254f9d403782534a41",
    "verified_classes": [
      "AgentTelemetryInvariantError",
      "SpanRecord"
    ],
    "verified_functions": [
      "reconcile_agent_span"
    ],
    "verified_functions_count": 1,
    "defensive_guards_count": 3,
    "raised_exceptions": [
      "AgentTelemetryInvariantError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [
      "dataclasses",
      "typing"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
