GenAI Utils | Agent Base Type and Creation Span

Author: etserend

util/opentelemetry-util-genai/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Add `AgentInvocation` type and agent invocation lifecycle support
+  ([#4274](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4274))
 - Add support for emitting inference events and enrich message types. ([#3994](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3994))
 - Add support for `server.address`, `server.port` on all signals and additional metric-only attributes
   ([#4069](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4069))

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

@@ -80,11 +80,18 @@
 )
 from opentelemetry.util.genai.metrics import InvocationMetricsRecorder
 from opentelemetry.util.genai.span_utils import (
+    _apply_agent_finish_attributes,
+    _apply_creation_finish_attributes,
     _apply_error_attributes,
     _apply_llm_finish_attributes,
     _maybe_emit_llm_event,
 )
-from opentelemetry.util.genai.types import Error, LLMInvocation
+from opentelemetry.util.genai.types import (
+    AgentCreation,
+    AgentInvocation,
+    Error,
+    LLMInvocation,
+)
 from opentelemetry.util.genai.version import __version__
 
 
@@ -208,6 +215,143 @@ def llm(
             raise
         self.stop_llm(invocation)
 
+    # ---- Agent invocation lifecycle ----
+
+    def start_agent(
+        self,
+        invocation: AgentInvocation,
+    ) -> AgentInvocation:
+        """Start an agent invocation and create a pending span entry."""
+        span_name = f"{invocation.operation_name} {invocation.agent_name}".strip()
+        kind = SpanKind.CLIENT if invocation.is_remote else SpanKind.INTERNAL
+        span = self._tracer.start_span(
+            name=span_name,
+            kind=kind,
+        )
+        invocation.monotonic_start_s = timeit.default_timer()
+        invocation.span = span
+        invocation.context_token = otel_context.attach(
+            set_span_in_context(span)
+        )
+        return invocation
+
+    def stop_agent(self, invocation: AgentInvocation) -> AgentInvocation:  # pylint: disable=no-self-use
+        """Finalize an agent invocation successfully and end its span."""
+        if invocation.context_token is None or invocation.span is None:
+            return invocation
+
+        span = invocation.span
+        _apply_agent_finish_attributes(span, invocation)
+        otel_context.detach(invocation.context_token)
+        span.end()
+        return invocation
+
+    def fail_agent(  # pylint: disable=no-self-use
+        self, invocation: AgentInvocation, error: Error
+    ) -> AgentInvocation:
+        """Fail an agent invocation and end its span with error status."""
+        if invocation.context_token is None or invocation.span is None:
+            return invocation
+
+        span = invocation.span
+        _apply_agent_finish_attributes(span, invocation)
+        _apply_error_attributes(span, error)
+        otel_context.detach(invocation.context_token)
+        span.end()
+        return invocation
+
+    @contextmanager
+    def agent(
+        self, invocation: AgentInvocation | None = None
+    ) -> Iterator[AgentInvocation]:
+        """Context manager for agent invocations.
+
+        Only set data attributes on the invocation object, do not modify the span or context.
+
+        Starts the span on entry. On normal exit, finalizes the invocation 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 invocation is None:
+            invocation = AgentInvocation()
+        self.start_agent(invocation)
+        try:
+            yield invocation
+        except Exception as exc:
+            self.fail_agent(
+                invocation, Error(message=str(exc), type=type(exc))
+            )
+            raise
+        self.stop_agent(invocation)
+
+    # ---- Agent creation lifecycle ----
+
+    def start_create_agent(
+        self,
+        creation: AgentCreation,
+    ) -> AgentCreation:
+        """Start an agent creation and create a pending span entry."""
+        span_name = f"{creation.operation_name} {creation.agent_name}".strip()
+        span = self._tracer.start_span(
+            name=span_name,
+            kind=SpanKind.CLIENT,
+        )
+        creation.monotonic_start_s = timeit.default_timer()
+        creation.span = span
+        creation.context_token = otel_context.attach(
+            set_span_in_context(span)
+        )
+        return creation
+
+    def stop_create_agent(self, creation: AgentCreation) -> AgentCreation:  # pylint: disable=no-self-use
+        """Finalize an agent creation successfully and end its span."""
+        if creation.context_token is None or creation.span is None:
+            return creation
+
+        span = creation.span
+        _apply_creation_finish_attributes(span, creation)
+        otel_context.detach(creation.context_token)
+        span.end()
+        return creation
+
+    def fail_create_agent(  # pylint: disable=no-self-use
+        self, creation: AgentCreation, error: Error
+    ) -> AgentCreation:
+        """Fail an agent creation and end its span with error status."""
+        if creation.context_token is None or creation.span is None:
+            return creation
+
+        span = creation.span
+        _apply_creation_finish_attributes(span, creation)
+        _apply_error_attributes(span, error)
+        otel_context.detach(creation.context_token)
+        span.end()
+        return creation
+
+    @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_create_agent(creation)
+        try:
+            yield creation
+        except Exception as exc:
+            self.fail_create_agent(
+                creation, Error(message=str(exc), type=type(exc))
+            )
+            raise
+        self.stop_create_agent(creation)
+
 
 def get_telemetry_handler(
     tracer_provider: TracerProvider | None = None,