apply general invoke methods and resolved merge conflict

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 `_BaseAgent`, `AgentCreation`, and `AgentInvocation` types with agent lifecycle support
+- Add `_BaseAgent` and `AgentInvocation` types with agent lifecycle support
   ([#4274](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4274))
 - Add EmbeddingInvocation span lifecycle support
   ([https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4219](#4219))

util/opentelemetry-util-genai/pyproject.toml

@@ -28,7 +28,7 @@ classifiers = [
 dependencies = [
   "opentelemetry-instrumentation ~= 0.60b0",
   "opentelemetry-semantic-conventions ~= 0.60b0",
-  "opentelemetry-api>=1.39",
+  "opentelemetry-api ~= 1.39",
 ]
 
 [project.entry-points.opentelemetry_genai_completion_hook]

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

@@ -81,23 +81,20 @@
 from opentelemetry.util.genai.metrics import InvocationMetricsRecorder
 from opentelemetry.util.genai.span_utils import (
     _apply_agent_finish_attributes,
-    _apply_creation_finish_attributes,
     _apply_embedding_finish_attributes,
     _apply_error_attributes,
     _apply_llm_finish_attributes,
-    _get_base_agent_span_name,
+    _get_agent_span_name,
     _get_embedding_span_name,
     _get_llm_span_name,
     _maybe_emit_llm_event,
 )
 from opentelemetry.util.genai.types import (
-    AgentCreation,
     AgentInvocation,
     EmbeddingInvocation,
     Error,
     GenAIInvocation,
     LLMInvocation,
-    _BaseAgent,
 )
 from opentelemetry.util.genai.version import __version__
 
@@ -169,10 +166,8 @@ def _start(self, invocation: _T) -> _T:
             span_name = _get_llm_span_name(invocation)
         elif isinstance(invocation, EmbeddingInvocation):
             span_name = _get_embedding_span_name(invocation)
-        elif isinstance(invocation, _BaseAgent):
-            span_name = _get_base_agent_span_name(invocation)
-            if isinstance(invocation, AgentInvocation) and not invocation.is_remote:
-                kind = SpanKind.INTERNAL
+        elif isinstance(invocation, AgentInvocation):
+            span_name = _get_agent_span_name(invocation)
         else:
             span_name = ""
         span = self._tracer.start_span(
@@ -205,8 +200,6 @@ def _stop(self, invocation: _T) -> _T:
                 self._record_embedding_metrics(invocation, span)
             elif isinstance(invocation, AgentInvocation):
                 _apply_agent_finish_attributes(span, invocation)
-            elif isinstance(invocation, AgentCreation):
-                _apply_creation_finish_attributes(span, invocation)
         finally:
             # Detach context and end span even if finishing fails
             otel_context.detach(invocation.context_token)
@@ -240,9 +233,6 @@ def _fail(self, invocation: _T, error: Error) -> _T:
             elif isinstance(invocation, AgentInvocation):
                 _apply_agent_finish_attributes(span, invocation)
                 _apply_error_attributes(span, error, error_type)
-            elif isinstance(invocation, AgentCreation):
-                _apply_creation_finish_attributes(span, invocation)
-                _apply_error_attributes(span, error, error_type)
         finally:
             # Detach context and end span even if finishing fails
             otel_context.detach(invocation.context_token)
@@ -326,9 +316,7 @@ def embedding(
         self.stop(invocation)
 
     # Agent-specific convenience methods
-    def start_agent(
-        self, invocation: AgentInvocation
-    ) -> AgentInvocation:
+    def start_agent(self, invocation: AgentInvocation) -> AgentInvocation:
         """Start an agent invocation and create a pending span entry."""
         return self._start(invocation)
 
@@ -364,28 +352,6 @@ def agent(
             raise
         self.stop(invocation)
 
-    @contextmanager
-    def create_agent(
-        self, creation: AgentCreation | None = None
-    ) -> Iterator[AgentCreation]:
-        """Context manager for agent creation.
-
-        Only set data attributes on the creation object, do not modify the span or context.
-
-        Starts the span on entry. On normal exit, finalizes the creation and ends the span.
-        If an exception occurs inside the context, marks the span as error, ends it, and
-        re-raises the original exception.
-        """
-        if creation is None:
-            creation = AgentCreation()
-        self.start(creation)
-        try:
-            yield creation
-        except Exception as exc:
-            self.fail(creation, Error(message=str(exc), type=type(exc)))
-            raise
-        self.stop(creation)
-
 
 def get_telemetry_handler(
     tracer_provider: TracerProvider | None = None,

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

@@ -40,7 +40,6 @@
     LLMInvocation,
     MessagePart,
     OutputMessage,
-    _BaseAgent,
 )
 from opentelemetry.util.genai.utils import (
     ContentCapturingMode,
@@ -390,51 +389,35 @@ def _get_embedding_response_attributes(
     return {key: value for key, value in optional_attrs if value is not None}
 
 
-def _get_base_agent_common_attributes(
-    agent: _BaseAgent,
-) -> dict[str, Any]:
-    """Get common attributes shared by all agent operations (invoke_agent, create_agent)."""
-    optional_attrs = (
-        (GenAI.GEN_AI_REQUEST_MODEL, agent.request_model),
-        (GenAI.GEN_AI_PROVIDER_NAME, agent.provider),
-        (GenAI.GEN_AI_AGENT_NAME, agent.agent_name),
-        (GenAI.GEN_AI_AGENT_ID, agent.agent_id),
-        (GenAI.GEN_AI_AGENT_DESCRIPTION, agent.agent_description),
-        (GenAI.GEN_AI_AGENT_VERSION, agent.agent_version),
-        (server_attributes.SERVER_ADDRESS, agent.server_address),
-        (server_attributes.SERVER_PORT, agent.server_port),
-    )
-
-    return {
-        GenAI.GEN_AI_OPERATION_NAME: agent.operation_name,
-        **{key: value for key, value in optional_attrs if value is not None},
-    }
-
-
-def _get_base_agent_span_name(agent: _BaseAgent) -> str:
-    """Get the span name for any agent operation."""
-    if agent.agent_name:
-        return f"{agent.operation_name} {agent.agent_name}"
-    return agent.operation_name
+def _get_agent_span_name(invocation: AgentInvocation) -> str:
+    """Get the span name for an agent invocation."""
+    if invocation.agent_name:
+        return f"{invocation.operation_name} {invocation.agent_name}"
+    return invocation.operation_name
 
 
 def _get_agent_common_attributes(
     invocation: AgentInvocation,
 ) -> dict[str, Any]:
     """Get common agent invocation attributes shared by finish() and error() paths."""
-    attrs = _get_base_agent_common_attributes(invocation)
-
-    # Invoke-specific conditionally required attributes
-    invoke_attrs = (
+    optional_attrs = (
+        (GenAI.GEN_AI_REQUEST_MODEL, invocation.request_model),
+        (GenAI.GEN_AI_AGENT_NAME, invocation.agent_name),
+        (GenAI.GEN_AI_AGENT_ID, invocation.agent_id),
+        (GenAI.GEN_AI_AGENT_DESCRIPTION, invocation.agent_description),
+        ("gen_ai.agent.version", invocation.agent_version),
         (GenAI.GEN_AI_CONVERSATION_ID, invocation.conversation_id),
         (GenAI.GEN_AI_DATA_SOURCE_ID, invocation.data_source_id),
         (GenAI.GEN_AI_OUTPUT_TYPE, invocation.output_type),
-    )
-    attrs.update(
-        {key: value for key, value in invoke_attrs if value is not None}
+        (server_attributes.SERVER_ADDRESS, invocation.server_address),
+        (server_attributes.SERVER_PORT, invocation.server_port),
     )
 
-    return attrs
+    return {
+        GenAI.GEN_AI_OPERATION_NAME: invocation.operation_name,
+        GenAI.GEN_AI_PROVIDER_NAME: invocation.provider,
+        **{key: value for key, value in optional_attrs if value is not None},
+    }
 
 
 def _get_agent_request_attributes(
@@ -485,11 +468,11 @@ def _get_agent_response_attributes(
         (GenAI.GEN_AI_USAGE_INPUT_TOKENS, invocation.input_tokens),
         (GenAI.GEN_AI_USAGE_OUTPUT_TOKENS, invocation.output_tokens),
         (
-            GenAI.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS,
+            "gen_ai.usage.cache_creation_input_tokens",
             invocation.cache_creation_input_tokens,
         ),
         (
-            GenAI.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS,
+            "gen_ai.usage.cache_read_input_tokens",
             invocation.cache_read_input_tokens,
         ),
     )
@@ -501,7 +484,7 @@ def _apply_agent_finish_attributes(
     span: Span, invocation: AgentInvocation
 ) -> None:
     """Apply attributes/messages common to agent finish() paths."""
-    span.update_name(_get_base_agent_span_name(invocation))
+    span.update_name(_get_agent_span_name(invocation))
 
     attributes: dict[str, Any] = {}
     attributes.update(_get_agent_common_attributes(invocation))
@@ -534,8 +517,7 @@ def _apply_agent_finish_attributes(
     "_get_embedding_request_attributes",
     "_get_embedding_response_attributes",
     "_get_embedding_span_name",
-    "_get_base_agent_common_attributes",
-    "_get_base_agent_span_name",
+    "_get_agent_span_name",
     "_apply_agent_finish_attributes",
     "_get_system_instructions_for_span",
     "_get_agent_common_attributes",

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

@@ -315,13 +315,6 @@ class EmbeddingInvocation(GenAIInvocation):
 class _BaseAgent(GenAIInvocation):
     """
     Shared base class for agent lifecycle types.
-
-    Contains fields common to all agent operations: identity, provider,
-    model, system instructions, server info, and telemetry plumbing.
-
-    Follows semconv for GenAI agent spans:
-    https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md
-
     Do not instantiate directly — use AgentInvocation.
     """
 
@@ -340,26 +333,13 @@ class _BaseAgent(GenAIInvocation):
     server_address: str | None = None
     server_port: int | None = None
 
-    attributes: dict[str, Any] = field(default_factory=_new_str_any_dict)
-    """
-    Additional attributes to set on spans and/or events.
-    """
-    # Monotonic start time in seconds (from timeit.default_timer) used
-    # for duration calculations to avoid mixing clock sources. This is
-    # populated by the TelemetryHandler when starting an invocation.
-    monotonic_start_s: float | None = None
-
 
 @dataclass
 class AgentInvocation(_BaseAgent):
     """
-    Represents an agent invocation (invoke_agent operation).
-
-    Follows semconv for GenAI agent spans:
-    https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-span
-
-    When creating an AgentInvocation object, only update the data attributes.
-    The span and context_token attributes are set by the TelemetryHandler.
+    Represents a single agent invocation. When creating an AgentInvocation object,
+    only update the data attributes. The span and context_token attributes are
+    set by the TelemetryHandler.
     """
 
     operation_name: str = GenAI.GenAiOperationNameValues.INVOKE_AGENT.value
@@ -392,6 +372,11 @@ class AgentInvocation(_BaseAgent):
     )
     tool_definitions: list[dict[str, Any]] | None = None
 
+    attributes: dict[str, Any] = field(default_factory=_new_str_any_dict)
+    """
+    Additional attributes to set on spans and/or events. These attributes
+    will not be set on metrics.
+    """
     metric_attributes: dict[str, Any] = field(
         default_factory=_new_str_any_dict
     )

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

@@ -63,7 +63,7 @@ def test_start_stop_creates_span(self) -> None:
 
     def test_span_kind_client_by_default(self) -> None:
         handler = self._make_handler()
-        invocation = AgentInvocation(agent_name="Agent")
+        invocation = AgentInvocation(agent_name="Agent", provider="openai")
         handler.start_agent(invocation)
         handler.stop_agent(invocation)
         self.assertEqual(
@@ -123,10 +123,8 @@ def test_cache_token_attributes(self) -> None:
 
         attrs = self.span_exporter.get_finished_spans()[0].attributes
         self.assertEqual(attrs[GenAI.GEN_AI_USAGE_INPUT_TOKENS], 100)
-        self.assertEqual(
-            attrs[GenAI.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS], 25
-        )
-        self.assertEqual(attrs[GenAI.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS], 50)
+        self.assertEqual(attrs["gen_ai.usage.cache_creation_input_tokens"], 25)
+        self.assertEqual(attrs["gen_ai.usage.cache_read_input_tokens"], 50)
 
     def test_fail_sets_error_status(self) -> None:
         handler = self._make_handler()
@@ -157,7 +155,9 @@ def test_context_manager_success(self) -> None:
     def test_context_manager_error(self) -> None:
         handler = self._make_handler()
         with self.assertRaises(ValueError):
-            with handler.agent(AgentInvocation(agent_name="Agent")):
+            with handler.agent(
+                AgentInvocation(agent_name="Agent", provider="openai")
+            ):
                 raise ValueError("test error")
 
         self.assertEqual(