Add an opaque governance record reference for decision operations

changelog.d/368.enhancement.md

@@ -0,0 +1 @@
+Add `gen_ai.agent.decision.id`, `gen_ai.agent.decision.outcome`, and `gen_ai.agent.governance.ref` opt-in attributes for correlating agent spans with a producer-owned governance decision (policy, review, approval, or execution-context evaluation) without carrying that record's payload in telemetry.

model/gen-ai/registry.yaml

@@ -306,6 +306,65 @@ attributes:
     brief: The version of the GenAI agent.
     examples: ["1.0.0", "2025-05-01"]
     stability: development
+  - key: gen_ai.agent.decision.id
+    type: string
+    brief: >
+      Opaque, producer-defined identifier correlating telemetry with a single
+      governance decision point for the agent.
+    note: >
+      The value has no meaning to the convention beyond identity; consumers use it
+      only to join telemetry with the producer's own record of that decision. This
+      attribute exists only where a decision point was reached and an action was
+      attempted. It does not indicate, and MUST NOT be used to indicate, whether
+      any other action was or was not available to the agent.
+    examples: ["decision_01J8Z3K5G4QYX9V2XQ9K7YXTAM"]
+    stability: development
+  - key: gen_ai.agent.decision.outcome
+    type:
+      members:
+        - id: allow
+          value: "allow"
+          brief: "The attempted action was permitted."
+          stability: development
+        - id: block
+          value: "block"
+          brief: "The attempted action was denied."
+          stability: development
+        - id: review
+          value: "review"
+          brief: "The attempted action was routed to review."
+          stability: development
+        - id: escalate
+          value: "escalate"
+          brief: "The attempted action was escalated."
+          stability: development
+        - id: defer
+          value: "defer"
+          brief: "A decision on the attempted action was deferred."
+          stability: development
+    brief: >
+      The observed result of a governance decision on an action the agent
+      attempted.
+    note: >
+      This attribute describes the outcome of a resolved attempt only. Whether an
+      action was ever available to the agent in the first place is a separate
+      producer-side concern and is intentionally out of scope for this attribute
+      and this convention; this attribute has no such member.
+    examples: ["allow", "block", "review", "escalate", "defer"]
+    stability: development
+  - key: gen_ai.agent.governance.ref
+    type: string
+    brief: >
+      Opaque, producer-defined reference to producer-owned governance context for
+      a decision point, for example a policy, approval, or execution-context
+      record.
+    note: >
+      The referenced record's format, schema, lifecycle, and validation behavior
+      are implementation-defined and out of scope for this convention. This
+      attribute defines only a payload-free join surface; it does not carry the
+      referenced record's contents.
+    examples: ["ctx_7f3a9c"]
+    stability: development
   - key: gen_ai.tool.name
     type: string
     brief: Name of the tool utilized by the agent.

model/gen-ai/spans.yaml

@@ -136,6 +136,16 @@ attribute_groups:
         brief: The free-form description of the invoked GenAI agent.
         requirement_level:
           conditionally_required: When available.
+      # Producer-emitted governance decision join point. Opt-in: only emitted by
+      # instrumentations that sit at a governance decision point for the agent
+      # invocation (policy, review, approval, or execution-context evaluation).
+      - ref: gen_ai.agent.decision.id
+        requirement_level: opt_in
+      - ref: gen_ai.agent.decision.outcome
+        requirement_level:
+          recommended: If `gen_ai.agent.decision.id` is set.
+      - ref: gen_ai.agent.governance.ref
+        requirement_level: opt_in
 
 
   - id: attributes.gen_ai.execute_tool.common

reference/README.md

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

reference/reports/execute-tool-span.md

@@ -6,8 +6,8 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.operation.name | [agent-framework], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
-| gen_ai.tool.name | [agent-framework], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
+| gen_ai.operation.name | [agent-framework], [agent-governance], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
+| gen_ai.tool.name | [agent-framework], [agent-governance], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
 
 ## Conditionally Required
 
@@ -21,16 +21,17 @@
 | --- | --- |
 | gen_ai.tool.call.id | [agent-framework], [autogen], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
 | gen_ai.tool.description | [agent-framework], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
-| gen_ai.tool.type | [agent-framework], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
+| gen_ai.tool.type | [agent-framework], [agent-governance], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
 
 ## Opt-In
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.tool.call.arguments | [agent-framework], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
-| gen_ai.tool.call.result | [agent-framework], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
+| gen_ai.tool.call.arguments | [agent-framework], [agent-governance], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
+| gen_ai.tool.call.result | [agent-framework], [agent-governance], [autogen], [crewai], [google-adk], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [openai-assistants], [pydantic-ai] |
 
 [agent-framework]: ../scenarios/agent-framework/scenario.py
+[agent-governance]: ../scenarios/agent-governance/scenario.py
 [autogen]: ../scenarios/autogen/scenario.py
 [crewai]: ../scenarios/crewai/scenario.py
 [google-adk]: ../scenarios/google-adk/scenario.py

reference/reports/inference-span.md

@@ -6,8 +6,8 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.operation.name | [agent-framework], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
-| gen_ai.provider.name | [agent-framework], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
+| gen_ai.operation.name | [agent-framework], [agent-governance], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
+| gen_ai.provider.name | [agent-framework], [agent-governance], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
 
 ## Conditionally Required
 
@@ -18,11 +18,11 @@
 | gen_ai.prompt.name | [aws-bedrock], [openai] |
 | gen_ai.prompt.version | [aws-bedrock], [openai] |
 | gen_ai.request.choice.count | [agent-framework], [crewai], [google-adk], [llamaindex], [openai] |
-| gen_ai.request.model | [agent-framework], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
+| gen_ai.request.model | [agent-framework], [agent-governance], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
 | gen_ai.request.seed | [autogen], [crewai], [openai], [pydantic-ai] |
 | gen_ai.request.stream | [openai] |
 | gen_ai.request.top_k | [google-adk] |
-| server.port | [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [cohere], [crewai], [google-adk], [langchain], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai] |
+| server.port | [agent-governance], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [cohere], [crewai], [google-adk], [langchain], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai] |
 
 ## Recommended
 
@@ -36,28 +36,29 @@
 | gen_ai.request.stop_sequences | [autogen], [crewai], [google-adk], [openai], [pydantic-ai] |
 | gen_ai.request.temperature | [autogen], [crewai], [google-adk], [llamaindex], [openai], [pydantic-ai] |
 | gen_ai.request.top_p | [autogen], [crewai], [google-adk], [openai], [pydantic-ai] |
-| gen_ai.response.finish_reasons | [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [pydantic-ai], [vertexai] |
-| gen_ai.response.id | [agent-framework], [anthropic], [autogen], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai] |
-| gen_ai.response.model | [agent-framework], [anthropic], [autogen], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [crewai], [dspy], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai] |
+| gen_ai.response.finish_reasons | [agent-governance], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [pydantic-ai], [vertexai] |
+| gen_ai.response.id | [agent-framework], [agent-governance], [anthropic], [autogen], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai] |
+| gen_ai.response.model | [agent-framework], [agent-governance], [anthropic], [autogen], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [crewai], [dspy], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai] |
 | gen_ai.response.time_to_first_chunk | (none) |
 | gen_ai.usage.cache_creation.input_tokens | [anthropic] |
 | gen_ai.usage.cache_read.input_tokens | [agent-framework], [anthropic] |
-| gen_ai.usage.input_tokens | [agent-framework], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
-| gen_ai.usage.output_tokens | [agent-framework], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
+| gen_ai.usage.input_tokens | [agent-framework], [agent-governance], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
+| gen_ai.usage.output_tokens | [agent-framework], [agent-governance], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [claude-agent-sdk], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
 | gen_ai.usage.reasoning.output_tokens | [agent-framework] |
-| server.address | [agent-framework], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [cohere], [crewai], [google-adk], [langchain], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai] |
+| server.address | [agent-framework], [agent-governance], [anthropic], [autogen], [aws-bedrock], [azure-ai-inference], [azure-openai], [cohere], [crewai], [google-adk], [langchain], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai] |
 
 ## Opt-In
 
 | Attribute | Supporting Libraries |
 | --- | --- |
-| gen_ai.input.messages | [agent-framework], [anthropic], [autogen], [aws-bedrock], [claude-agent-sdk], [crewai], [dspy], [google-adk], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [pydantic-ai] |
-| gen_ai.output.messages | [agent-framework], [anthropic], [autogen], [aws-bedrock], [claude-agent-sdk], [crewai], [dspy], [google-adk], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [pydantic-ai] |
+| gen_ai.input.messages | [agent-framework], [agent-governance], [anthropic], [autogen], [aws-bedrock], [claude-agent-sdk], [crewai], [dspy], [google-adk], [groq], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [pydantic-ai] |
+| gen_ai.output.messages | [agent-framework], [agent-governance], [anthropic], [autogen], [aws-bedrock], [claude-agent-sdk], [crewai], [dspy], [google-adk], [instructor], [langchain], [litellm], [llamaindex], [mistralai], [openai], [pydantic-ai] |
 | gen_ai.prompt.variable | (none) |
 | gen_ai.system_instructions | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai], [pydantic-ai] |
 | gen_ai.tool.definitions | [autogen], [aws-bedrock], [azure-ai-inference], [cohere], [crewai], [dspy], [google-adk], [google-genai], [groq], [instructor], [litellm], [llamaindex], [mistralai], [openai], [openai-agents], [pydantic-ai], [vertexai] |
 
 [agent-framework]: ../scenarios/agent-framework/scenario.py
+[agent-governance]: ../scenarios/agent-governance/scenario.py
 [anthropic]: ../scenarios/anthropic/scenario.py
 [autogen]: ../scenarios/autogen/scenario.py
 [aws-bedrock]: ../scenarios/aws-bedrock/scenario.py