Add gen_ai.external_ref: an opaque reference to an out-of-band record

changelog.d/368.enhancement.md

@@ -0,0 +1,5 @@
+Add `gen_ai.external_ref`: an opaque, producer-defined identifier of an
+out-of-band record associated with an operation, recommended on the existing
+gen_ai client/internal spans when such a record exists. Consumers compare it
+for equality only; the referenced record's format, lifecycle, retrieval, and
+validation stay outside this specification.

model/gen-ai/registry.yaml

@@ -482,6 +482,26 @@ attributes:
     brief: The version of the GenAI agent.
     examples: ["1.0.0", "2025-05-01"]
     stability: development
+  - key: gen_ai.external_ref
+    type: string
+    brief: >
+      An opaque, producer-defined identifier of an out-of-band record
+      associated with the operation.
+    note: |
+      Consumers MUST compare this value for equality only and MUST NOT parse
+      it or infer meaning from its format.
+
+      The referenced record's format, lifecycle, retrieval, and validation
+      are outside this specification. This attribute defines only a
+      payload-free join surface between a span and that record; it does not
+      carry the record's contents.
+
+      Producers SHOULD keep the value stable for the record state that
+      governed the operation: if the referenced record is later revised, the
+      value SHOULD still identify the version or snapshot in effect at the
+      time of the operation.
+    examples: ["01J9Z2K3M4N5P6Q7R8S9T0V1W2"]
+    stability: development
   - key: gen_ai.tool.name
     type: string
     brief: Name of the tool utilized by the agent.

model/gen-ai/spans.yaml

@@ -24,6 +24,13 @@ attribute_groups:
       - ref: gen_ai.operation.name
         requirement_level: required
 
+  - id: attributes.gen_ai.external_ref
+    visibility: internal
+    attributes:
+      - ref: gen_ai.external_ref
+        requirement_level:
+          recommended: If an out-of-band record exists for the operation.
+
   - id: attributes.gen_ai.address_and_port
     visibility: internal
     attributes:
@@ -192,6 +199,7 @@ spans:
       - ref_group: attributes.gen_ai.usage.breakdown
       - ref_group: attributes.gen_ai.content
       - ref_group: attributes.gen_ai.error
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.request.max_tokens
         requirement_level: recommended
       - ref: gen_ai.request.choice.count
@@ -286,6 +294,7 @@ spans:
       - ref_group: attributes.gen_ai.common
       - ref_group: attributes.gen_ai.address_and_port
       - ref_group: attributes.gen_ai.error
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.provider.name
         requirement_level: required
         sampling_relevant: true
@@ -323,6 +332,7 @@ spans:
       - ref_group: attributes.gen_ai.common
       - ref_group: attributes.gen_ai.address_and_port
       - ref_group: attributes.gen_ai.error
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.retrieval.query.text
         requirement_level: opt_in
       - ref: gen_ai.retrieval.top_k
@@ -353,6 +363,7 @@ spans:
     attributes:
       - ref_group: attributes.gen_ai.address_and_port
       - ref_group: attributes.gen_ai.error
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.provider.name
         requirement_level: required
         sampling_relevant: true
@@ -435,6 +446,7 @@ spans:
         requirement_level: required
       - ref_group: attributes.gen_ai.address_and_port
       - ref_group: attributes.gen_ai.error
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.provider.name
         requirement_level:
           conditionally_required: If the operation is handled by a named external GenAI provider or service.
@@ -469,6 +481,7 @@ spans:
       - ref_group: attributes.gen_ai.common
       - ref_group: attributes.gen_ai.address_and_port
       - ref_group: attributes.gen_ai.error
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.provider.name
         requirement_level: required
         sampling_relevant: true
@@ -521,6 +534,7 @@ spans:
       - ref_group: attributes.gen_ai.invoke_agent.common
       - ref_group: attributes.gen_ai.usage.breakdown
       - ref_group: attributes.gen_ai.address_and_port
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.provider.name
         requirement_level: required
         sampling_relevant: true
@@ -563,6 +577,7 @@ spans:
     stability: development
     attributes:
       - ref_group: attributes.gen_ai.invoke_agent.common
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.operation.name
         sampling_relevant: true
       - ref: gen_ai.request.model
@@ -593,6 +608,7 @@ spans:
     attributes:
       - ref_group: attributes.gen_ai.error
       - ref_group: attributes.gen_ai.execute_tool.common
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.operation.name
         requirement_level: required
         sampling_relevant: true
@@ -652,6 +668,7 @@ spans:
     stability: development
     attributes:
       - ref_group: attributes.gen_ai.error
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.operation.name
         requirement_level: required
         sampling_relevant: true
@@ -691,6 +708,7 @@ spans:
     stability: development
     attributes:
       - ref_group: attributes.gen_ai.error
+      - ref_group: attributes.gen_ai.external_ref
       - ref: gen_ai.operation.name
         requirement_level: required
         sampling_relevant: true

reference/README.md

@@ -28,15 +28,15 @@ Run `uv run update-reports` to regenerate.
 | --- | --- |
 | [Create Agent](reports/create-agent-span.md) | anthropic, aws-bedrock-agent, azure-ai-foundry, google-genai, mistralai, openai-assistants |
 | [Invoke Agent Client](reports/invoke-agent-client-span.md) | aws-bedrock-agent, azure-ai-foundry, google-genai, openai-assistants |
-| [Invoke Agent Internal](reports/invoke-agent-internal-span.md) | agent-framework, autogen, crewai, google-adk, langchain, openai-agents, pydantic-ai |
+| [Invoke Agent Internal](reports/invoke-agent-internal-span.md) | agent-framework, autogen, crewai, external-ref, google-adk, langchain, openai-agents, pydantic-ai |
 | [Invoke Workflow](reports/invoke-workflow-span.md) | crewai, google-adk, langchain, openai-agents |
 | [Plan](reports/plan-span.md) | crewai, langchain |
 | [Inference](reports/inference-span.md) | agent-framework, anthropic, aws-bedrock, azure-ai-inference, azure-openai, claude-agent-sdk, cohere, google-genai, groq, litellm, mistralai, openai, vertexai |
 | [Embeddings](reports/embeddings-span.md) | aws-bedrock, azure-ai-inference, azure-openai, cohere, google-genai, litellm, mistralai, openai |
 | [Retrieval](reports/retrieval-span.md) | haystack, langchain, llamaindex |
 | [Fetch Response](reports/fetch-response-span.md) | openai |
 | [Memory](reports/memory-span.md) | aws-bedrock-agentcore, google-adk |
-| [Execute Tool](reports/execute-tool-span.md) | agent-framework, autogen, crewai, google-adk, google-genai, langchain, llamaindex, openai-agents, openai-assistants, pydantic-ai, vertexai |
+| [Execute Tool](reports/execute-tool-span.md) | agent-framework, autogen, crewai, external-ref, google-adk, google-genai, langchain, llamaindex, openai-agents, openai-assistants, pydantic-ai, vertexai |
 
 ### Events
 

reference/reports/create-agent-span.md

@@ -24,6 +24,7 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
+| gen_ai.external_ref | (none) |
 | server.address | [anthropic], [aws-bedrock-agent], [azure-ai-foundry], [mistralai], [openai-assistants] |
 
 ## Opt-In

reference/reports/embeddings-span.md

@@ -21,6 +21,7 @@
 | Attribute | Supporting Libraries |
 | --- | --- |
 | gen_ai.embeddings.dimension.count | [azure-openai], [google-genai], [openai] |
+| gen_ai.external_ref | (none) |
 | gen_ai.request.encoding_formats | [azure-openai], [openai] |
 | gen_ai.response.model | [azure-ai-inference], [azure-openai], [litellm], [mistralai], [openai] |
 | gen_ai.usage.input_tokens | [aws-bedrock], [azure-ai-inference], [azure-openai], [cohere], [litellm], [mistralai], [openai] |

reference/reports/execute-tool-span.md

@@ -6,34 +6,36 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.operation.name | [agent-framework], [autogen], [crewai], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
-| gen_ai.tool.name | [agent-framework], [autogen], [crewai], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
+| gen_ai.operation.name | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
+| gen_ai.tool.name | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
 
 ## Conditionally Required
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.agent.name | [google-adk], [openai-agents], [pydantic-ai] |
+| gen_ai.agent.name | [external-ref], [google-adk], [openai-agents], [pydantic-ai] |
 | gen_ai.conversation.id | [google-adk], [openai-assistants] |
 
 ## Recommended
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.tool.call.id | [agent-framework], [autogen], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
-| gen_ai.tool.description | [agent-framework], [autogen], [crewai], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
-| gen_ai.tool.type | [agent-framework], [autogen], [crewai], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
+| gen_ai.external_ref | (none) |
+| gen_ai.tool.call.id | [agent-framework], [autogen], [external-ref], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
+| gen_ai.tool.description | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
+| gen_ai.tool.type | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
 
 ## Opt-In
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.tool.call.arguments | [agent-framework], [autogen], [crewai], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
-| gen_ai.tool.call.result | [agent-framework], [autogen], [crewai], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
+| gen_ai.tool.call.arguments | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
+| gen_ai.tool.call.result | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [google-genai], [langchain], [llamaindex], [openai-agents], [openai-assistants], [pydantic-ai], [vertexai] |
 
 [agent-framework]: ../scenarios/agent-framework/scenario.py
 [autogen]: ../scenarios/autogen/scenario.py
 [crewai]: ../scenarios/crewai/scenario.py
+[external-ref]: ../scenarios/external-ref/scenario.py
 [google-adk]: ../scenarios/google-adk/scenario.py
 [google-genai]: ../scenarios/google-genai/scenario.py
 [langchain]: ../scenarios/langchain/scenario.py

reference/reports/fetch-response-span.md

@@ -21,6 +21,7 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
+| gen_ai.external_ref | (none) |
 | gen_ai.response.finish_reasons | [openai] |
 | gen_ai.response.model | [openai] |
 | gen_ai.response.status | [openai] |

reference/reports/gen-ai-client-inference-operation-details-event.md

@@ -29,6 +29,7 @@
 | Attribute | Supporting Libraries |
 | --- | --- |
 | gen_ai.conversation.compacted | [anthropic], [openai] |
+| gen_ai.external_ref | (none) |
 | gen_ai.request.frequency_penalty | (none) |
 | gen_ai.request.max_tokens | [anthropic] |
 | gen_ai.request.presence_penalty | (none) |

reference/reports/inference-span.md

@@ -29,6 +29,7 @@
 | Attribute | Supporting Libraries |
 | --- | --- |
 | gen_ai.conversation.compacted | [anthropic], [openai] |
+| gen_ai.external_ref | (none) |
 | gen_ai.request.frequency_penalty | [openai] |
 | gen_ai.request.max_tokens | [anthropic], [openai] |
 | gen_ai.request.presence_penalty | [openai] |

reference/reports/invoke-agent-client-span.md

@@ -28,6 +28,7 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
+| gen_ai.external_ref | (none) |
 | gen_ai.request.frequency_penalty | (none) |
 | gen_ai.request.max_tokens | [azure-ai-foundry], [openai-assistants] |
 | gen_ai.request.model | [azure-ai-foundry], [google-genai], [openai-assistants] |

reference/reports/invoke-agent-internal-span.md

@@ -6,14 +6,14 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.operation.name | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
+| gen_ai.operation.name | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
 
 ## Conditionally Required
 
 | Attribute | Supporting Libraries |
 | --- | --- |
 | gen_ai.agent.description | [agent-framework], [autogen] |
-| gen_ai.agent.name | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
+| gen_ai.agent.name | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
 | gen_ai.conversation.id | [google-adk] |
 | gen_ai.data_source.id | (none) |
 | gen_ai.output.type | (none) |
@@ -24,29 +24,31 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
+| gen_ai.external_ref | [external-ref] |
 | gen_ai.request.frequency_penalty | [agent-framework], [autogen], [crewai], [google-adk], [pydantic-ai] |
 | gen_ai.request.max_tokens | [agent-framework], [autogen], [crewai], [google-adk], [pydantic-ai] |
-| gen_ai.request.model | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
+| gen_ai.request.model | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
 | gen_ai.request.presence_penalty | [agent-framework], [autogen], [crewai], [google-adk], [pydantic-ai] |
 | gen_ai.request.stop_sequences | [agent-framework], [autogen], [crewai], [google-adk], [pydantic-ai] |
 | gen_ai.request.temperature | [agent-framework], [autogen], [crewai], [google-adk], [pydantic-ai] |
 | gen_ai.request.top_p | [agent-framework], [autogen], [crewai], [google-adk], [pydantic-ai] |
-| gen_ai.response.finish_reasons | [autogen], [crewai], [google-adk], [openai-agents], [pydantic-ai] |
-| gen_ai.usage.input_tokens | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
-| gen_ai.usage.output_tokens | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
+| gen_ai.response.finish_reasons | [autogen], [crewai], [external-ref], [google-adk], [openai-agents], [pydantic-ai] |
+| gen_ai.usage.input_tokens | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
+| gen_ai.usage.output_tokens | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
 
 ## Opt-In
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.input.messages | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
-| gen_ai.output.messages | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
+| gen_ai.input.messages | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
+| gen_ai.output.messages | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
 | gen_ai.system_instructions | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
-| gen_ai.tool.definitions | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
+| gen_ai.tool.definitions | [agent-framework], [autogen], [crewai], [external-ref], [google-adk], [langchain], [openai-agents], [pydantic-ai] |
 
 [agent-framework]: ../scenarios/agent-framework/scenario.py
 [autogen]: ../scenarios/autogen/scenario.py
 [crewai]: ../scenarios/crewai/scenario.py
+[external-ref]: ../scenarios/external-ref/scenario.py
 [google-adk]: ../scenarios/google-adk/scenario.py
 [langchain]: ../scenarios/langchain/scenario.py
 [openai-agents]: ../scenarios/openai-agents/scenario.py

reference/reports/invoke-workflow-span.md

@@ -15,6 +15,12 @@
 | gen_ai.conversation.id | [google-adk] |
 | gen_ai.workflow.name | [crewai], [google-adk], [langchain], [openai-agents] |
 
+## Recommended
+
+| Attribute | Supporting Libraries |
+| --- | --- |
+| gen_ai.external_ref | (none) |
+
 ## Opt-In
 
 | Attribute | Supporting Libraries |

reference/reports/memory-span.md

@@ -21,6 +21,7 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
+| gen_ai.external_ref | (none) |
 | gen_ai.memory.record.count | [aws-bedrock-agentcore], [google-adk] |
 | server.address | [aws-bedrock-agentcore] |
 

reference/reports/plan-span.md

@@ -14,5 +14,11 @@
 | --- | --- |
 | gen_ai.agent.name | [crewai] |
 
+## Recommended
+
+| Attribute | Supporting Libraries |
+| --- | --- |
+| gen_ai.external_ref | (none) |
+
 [crewai]: ../scenarios/crewai/scenario.py
 [langchain]: ../scenarios/langchain/scenario.py

reference/reports/retrieval-span.md

@@ -21,6 +21,7 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
+| gen_ai.external_ref | (none) |
 | gen_ai.retrieval.top_k | [haystack], [langchain], [llamaindex] |
 | server.address | [llamaindex] |
 

reference/scenarios/external-ref/README.md

@@ -0,0 +1,26 @@
+# external-ref
+
+This scenario exercises an opaque external reference on both allow and block
+paths through the OpenAI Agents SDK's input guardrail runtime. The SDK owns the
+agent run and tool execution, while the underlying `openai` client owns inference.
+
+| Operation | Should be instrumented here | Status |
+| --- | --- | --- |
+| inference (`chat`) | No — delegates to the `openai` client | ✅ Correctly not emitted |
+| invoke_agent (internal) | Yes — `Runner.run` evaluates the input guardrail and invokes the agent | ✅ Implemented |
+| execute_tool | Yes — the SDK runs the function tool | ✅ Implemented |
+
+The reference is returned by the guardrail in its `output_info` and copied onto the `invoke_agent` span on both runs.
+
+## Capture limitation
+
+The scenario's own guardrail creates the reference values and the `record_ref`
+dictionary key. The SDK exposes `GuardrailFunctionOutput.output_info` as arbitrary
+output information; it does not define that key or its record semantics.
+Generic SDK instrumentation therefore cannot infer an external record reference
+from this example without an application-specific mapping.
+
+The emitted attribute demonstrates the proposed join shape, not native SDK
+support for `gen_ai.external_ref`. The example also does not exercise a stored
+record or demonstrate that its referent remains stable. A real producer's
+runtime record identifier is still needed to substantiate this convention.

reference/scenarios/external-ref/conformance.yaml

@@ -0,0 +1,13 @@
+runner: genai-conformance
+instrumented_library: external-ref
+instrumentation_library: reference
+
+server:
+  run: genai-mock-server --host 127.0.0.1 --port ${PORT}
+
+env:
+  MOCK_LLM_URL: ${MOCK_SERVER_URL}
+
+scenarios:
+  reference:
+    run: uv run --frozen --python 3.12 --project . python scenario.py