feat(genai-utils): add finish_reasons to AgentInvocation per semconv

Author: etserend

util/opentelemetry-util-genai/CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
-- Add `AgentInvocation` type with `invoke_agent` span lifecycle via `start_invoke_local_agent` / `start_invoke_remote_agent` factory methods and `invoke_local_agent` / `invoke_remote_agent` context managers; add shared `_content.py` helper to deduplicate message serialization between `AgentInvocation` and `InferenceInvocation`; add `tool_definitions`, `cache_creation_input_tokens`, and `cache_read_input_tokens` to `InferenceInvocation`
+- Add `AgentInvocation` type with `invoke_agent` span lifecycle via `start_invoke_local_agent` / `start_invoke_remote_agent` factory methods and `invoke_local_agent` / `invoke_remote_agent` context managers; add `finish_reasons` field to `AgentInvocation` per semconv `gen_ai.response.finish_reasons` (Recommended); add shared `_content.py` helper to deduplicate message serialization between `AgentInvocation` and `InferenceInvocation`; add `tool_definitions`, `cache_creation_input_tokens`, and `cache_read_input_tokens` to `InferenceInvocation`; add `getattr` fallback for `GEN_AI_AGENT_VERSION` semconv constant
   ([#4274](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4274))
 - Add metrics support for EmbeddingInvocation
   ([#4377](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4377))

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_agent_invocation.py

@@ -35,16 +35,11 @@
     ToolDefinition,
 )
 
-_GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS: str = getattr(
-    GenAI,
-    "GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS",
-    "gen_ai.usage.cache_creation.input_tokens",
-)
-_GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS: str = getattr(
-    GenAI,
-    "GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS",
-    "gen_ai.usage.cache_read.input_tokens",
+_GEN_AI_AGENT_VERSION = "gen_ai.agent.version"
+_GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = (
+    "gen_ai.usage.cache_creation.input_tokens"
 )
+_GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens"
 
 
 class AgentInvocation(GenAIInvocation):
@@ -108,6 +103,8 @@ def __init__(
         self.seed: int | None = None
         self.choice_count: int | None = None
 
+        self.finish_reasons: list[str] | None = None
+
         self.input_tokens: int | None = None
         self.output_tokens: int | None = None
         self.cache_creation_input_tokens: int | None = None
@@ -128,7 +125,7 @@ def _get_common_attributes(self) -> dict[str, Any]:
             (GenAI.GEN_AI_AGENT_NAME, self.agent_name),
             (GenAI.GEN_AI_AGENT_ID, self.agent_id),
             (GenAI.GEN_AI_AGENT_DESCRIPTION, self.agent_description),
-            (GenAI.GEN_AI_AGENT_VERSION, self.agent_version),
+            (_GEN_AI_AGENT_VERSION, self.agent_version),
         )
         return {
             GenAI.GEN_AI_OPERATION_NAME: self._operation_name,
@@ -152,6 +149,11 @@ def _get_request_attributes(self) -> dict[str, Any]:
         )
         return {k: v for k, v in optional_attrs if v is not None}
 
+    def _get_response_attributes(self) -> dict[str, Any]:
+        if self.finish_reasons:
+            return {GenAI.GEN_AI_RESPONSE_FINISH_REASONS: self.finish_reasons}
+        return {}
+
     def _get_usage_attributes(self) -> dict[str, Any]:
         optional_attrs = (
             (GenAI.GEN_AI_USAGE_INPUT_TOKENS, self.input_tokens),
@@ -211,6 +213,7 @@ def _apply_finish(self, error: Error | None = None) -> None:
         attributes: dict[str, Any] = {}
         attributes.update(self._get_common_attributes())
         attributes.update(self._get_request_attributes())
+        attributes.update(self._get_response_attributes())
         attributes.update(self._get_usage_attributes())
         attributes.update(self._get_content_attributes_for_span())
         attributes.update(self.attributes)

util/opentelemetry-util-genai/tests/test_handler_agent.py

@@ -86,6 +86,7 @@ def test_all_attributes(self):
         invocation.stop_sequences = ["END", "STOP"]
         invocation.seed = 42
         invocation.choice_count = 3
+        invocation.finish_reasons = ["stop"]
         invocation.input_tokens = 100
         invocation.output_tokens = 200
         invocation.stop()
@@ -108,6 +109,24 @@ def test_all_attributes(self):
         assert attrs[GenAI.GEN_AI_REQUEST_STOP_SEQUENCES] == ("END", "STOP")
         assert attrs[GenAI.GEN_AI_REQUEST_SEED] == 42
         assert attrs[GenAI.GEN_AI_REQUEST_CHOICE_COUNT] == 3
+        assert attrs[GenAI.GEN_AI_RESPONSE_FINISH_REASONS] == ("stop",)
+
+    def test_finish_reasons_multiple(self):
+        invocation = self.handler.start_invoke_local_agent("openai")
+        invocation.finish_reasons = ["stop", "length"]
+        invocation.stop()
+        attrs = self.span_exporter.get_finished_spans()[0].attributes
+        assert attrs[GenAI.GEN_AI_RESPONSE_FINISH_REASONS] == (
+            "stop",
+            "length",
+        )
+
+    def test_finish_reasons_empty_list_omitted(self):
+        invocation = self.handler.start_invoke_local_agent("openai")
+        invocation.finish_reasons = []
+        invocation.stop()
+        attrs = self.span_exporter.get_finished_spans()[0].attributes
+        assert GenAI.GEN_AI_RESPONSE_FINISH_REASONS not in attrs
 
     def test_no_response_model_or_finish_reasons(self):
         invocation = self.handler.start_invoke_local_agent("openai")