fix(genai-utils): address review comments on AgentInvocation

Author: etserend

docs/nitpick-exceptions.ini

@@ -47,7 +47,6 @@ py-class=
     fastapi.applications.FastAPI
     starlette.applications.Starlette
     _contextvars.Token
-    opentelemetry.util.genai.types._BaseAgent
 
 any=
     ; API

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_agent(provider, ...)` / `invoke_agent(provider, ...)` factory methods; `provider` is required per semconv, `response_id` removed (not in invoke_agent spec), `finish_reasons` deduced from `output_messages` when not explicitly set
+- 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`
   ([#4274](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4274))
 - Add support for workflow in genAI utils handler.
   ([https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4366](#4366))

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

@@ -14,41 +14,35 @@
 
 from __future__ import annotations
 
-from dataclasses import asdict
-from typing import Any, Union
+from typing import Any
 
 from opentelemetry._logs import Logger
 from opentelemetry.semconv._incubating.attributes import (
     gen_ai_attributes as GenAI,
 )
 from opentelemetry.semconv.attributes import server_attributes
 from opentelemetry.trace import SpanKind, Tracer
+from opentelemetry.util.genai._content import _get_content_attributes
 from opentelemetry.util.genai._invocation import Error, GenAIInvocation
 from opentelemetry.util.genai.metrics import InvocationMetricsRecorder
 from opentelemetry.util.genai.types import (
-    FunctionToolDefinition,
-    GenericToolDefinition,
     InputMessage,
     MessagePart,
     OutputMessage,
+    ToolDefinition,
 )
-from opentelemetry.util.genai.utils import (
-    ContentCapturingMode,
-    gen_ai_json_dumps,
-    get_content_capturing_mode,
-    is_experimental_mode,
-)
-
-ToolDefinition = Union[FunctionToolDefinition, GenericToolDefinition]
 
 
 class AgentInvocation(GenAIInvocation):
     """Represents a single agent invocation (invoke_agent span).
 
-    Use handler.start_agent() or the handler.invoke_agent() context manager
-    rather than constructing this directly.
+    Use handler.start_invoke_local_agent() / handler.start_invoke_remote_agent()
+    or the handler.invoke_local_agent() / handler.invoke_remote_agent() context
+    managers rather than constructing this directly.
 
-    Reference: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-span
+    Reference:
+        Client span: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-client-span
+        Internal span: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-internal-span
     """
 
     def __init__(
@@ -58,24 +52,22 @@ def __init__(
         logger: Logger,
         provider: str,
         *,
+        span_kind: SpanKind = SpanKind.INTERNAL,
         request_model: str | None = None,
         server_address: str | None = None,
         server_port: int | None = None,
-        agent_name: str | None = None,
         attributes: dict[str, Any] | None = None,
         metric_attributes: dict[str, Any] | None = None,
     ) -> None:
-        """Use handler.start_agent() or handler.invoke_agent() instead of calling this directly."""
+        """Use handler.start_invoke_local_agent() or handler.start_invoke_remote_agent() instead of calling this directly."""
         _operation_name = GenAI.GenAiOperationNameValues.INVOKE_AGENT.value
         super().__init__(
             tracer,
             metrics_recorder,
             logger,
             operation_name=_operation_name,
-            span_name=f"{_operation_name} {agent_name}"
-            if agent_name
-            else _operation_name,
-            span_kind=SpanKind.CLIENT,
+            span_name=_operation_name,
+            span_kind=span_kind,
             attributes=attributes,
             metric_attributes=metric_attributes,
         )
@@ -84,7 +76,7 @@ def __init__(
         self.server_address = server_address
         self.server_port = server_port
 
-        self.agent_name = agent_name
+        self.agent_name: str | None = None
         self.agent_id: str | None = None
         self.agent_description: str | None = None
         self.agent_version: str | None = None
@@ -102,8 +94,6 @@ def __init__(
         self.seed: int | None = None
         self.choice_count: int | None = None
 
-        self.finish_reasons: list[str] | None = None
-        self.response_model_name: str | None = None
         self.input_tokens: int | None = None
         self.output_tokens: int | None = None
         self.cache_creation_input_tokens: int | None = None
@@ -116,18 +106,6 @@ def __init__(
 
         self._start()
 
-    def _get_finish_reasons(self) -> list[str] | None:
-        if self.finish_reasons is not None:
-            return self.finish_reasons or None
-        if self.output_messages:
-            reasons = [
-                msg.finish_reason
-                for msg in self.output_messages
-                if msg.finish_reason
-            ]
-            return reasons or None
-        return None
-
     def _get_common_attributes(self) -> dict[str, Any]:
         optional_attrs = (
             (GenAI.GEN_AI_REQUEST_MODEL, self.request_model),
@@ -160,10 +138,8 @@ 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]:
+    def _get_usage_attributes(self) -> dict[str, Any]:
         optional_attrs = (
-            (GenAI.GEN_AI_RESPONSE_FINISH_REASONS, self._get_finish_reasons()),
-            (GenAI.GEN_AI_RESPONSE_MODEL, self.response_model_name),
             (GenAI.GEN_AI_USAGE_INPUT_TOKENS, self.input_tokens),
             (GenAI.GEN_AI_USAGE_OUTPUT_TOKENS, self.output_tokens),
             (
@@ -177,47 +153,19 @@ def _get_response_attributes(self) -> dict[str, Any]:
         )
         return {k: v for k, v in optional_attrs if v is not None}
 
-    def _get_messages_for_span(self) -> dict[str, Any]:
-        if not is_experimental_mode() or get_content_capturing_mode() not in (
-            ContentCapturingMode.SPAN_ONLY,
-            ContentCapturingMode.SPAN_AND_EVENT,
-        ):
-            return {}
-        optional_attrs = (
-            (
-                GenAI.GEN_AI_INPUT_MESSAGES,
-                gen_ai_json_dumps([asdict(m) for m in self.input_messages])
-                if self.input_messages
-                else None,
-            ),
-            (
-                GenAI.GEN_AI_OUTPUT_MESSAGES,
-                gen_ai_json_dumps([asdict(m) for m in self.output_messages])
-                if self.output_messages
-                else None,
-            ),
-            (
-                GenAI.GEN_AI_SYSTEM_INSTRUCTIONS,
-                gen_ai_json_dumps([asdict(p) for p in self.system_instruction])
-                if self.system_instruction
-                else None,
-            ),
-            (
-                GenAI.GEN_AI_TOOL_DEFINITIONS,
-                gen_ai_json_dumps([asdict(t) for t in self.tool_definitions])
-                if self.tool_definitions
-                else None,
-            ),
+    def _get_content_attributes_for_span(self) -> dict[str, Any]:
+        return _get_content_attributes(
+            input_messages=self.input_messages,
+            output_messages=self.output_messages,
+            system_instruction=self.system_instruction,
+            tool_definitions=self.tool_definitions,
+            for_span=True,
         )
-        return {
-            key: value for key, value in optional_attrs if value is not None
-        }
 
     def _get_metric_attributes(self) -> dict[str, Any]:
         optional_attrs = (
             (GenAI.GEN_AI_PROVIDER_NAME, self.provider),
             (GenAI.GEN_AI_REQUEST_MODEL, self.request_model),
-            (GenAI.GEN_AI_RESPONSE_MODEL, self.response_model_name),
             (server_attributes.SERVER_ADDRESS, self.server_address),
             (server_attributes.SERVER_PORT, self.server_port),
         )
@@ -249,8 +197,8 @@ 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_messages_for_span())
+        attributes.update(self._get_usage_attributes())
+        attributes.update(self._get_content_attributes_for_span())
         attributes.update(self.attributes)
         self.span.set_attributes(attributes)
         self._metrics_recorder.record(self)

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

@@ -0,0 +1,102 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared content serialization helpers for invocation types.
+
+This module provides shared logic for serializing input/output messages,
+system instructions, and tool definitions into span and event attributes.
+Used by both InferenceInvocation and AgentInvocation to avoid duplication.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any, Sequence
+
+from opentelemetry.semconv._incubating.attributes import (
+    gen_ai_attributes as GenAI,
+)
+from opentelemetry.util.genai.types import (
+    InputMessage,
+    MessagePart,
+    OutputMessage,
+    ToolDefinition,
+)
+from opentelemetry.util.genai.utils import (
+    ContentCapturingMode,
+    gen_ai_json_dumps,
+    get_content_capturing_mode,
+    is_experimental_mode,
+)
+
+
+def _get_content_attributes(
+    *,
+    input_messages: Sequence[InputMessage],
+    output_messages: Sequence[OutputMessage],
+    system_instruction: Sequence[MessagePart],
+    tool_definitions: Sequence[ToolDefinition] | None,
+    for_span: bool,
+) -> dict[str, Any]:
+    """Serialize messages, system instructions, and tool definitions into attributes.
+
+    Args:
+        input_messages: Input messages to serialize.
+        output_messages: Output messages to serialize.
+        system_instruction: System instructions to serialize.
+        tool_definitions: Tool definitions to serialize (may be None).
+        for_span: If True, serialize for span attributes (JSON string);
+                  if False, serialize for event attributes (list of dicts).
+    """
+    if not is_experimental_mode():
+        return {}
+
+    mode = get_content_capturing_mode()
+    allowed_modes = (
+        (
+            ContentCapturingMode.SPAN_ONLY,
+            ContentCapturingMode.SPAN_AND_EVENT,
+        )
+        if for_span
+        else (
+            ContentCapturingMode.EVENT_ONLY,
+            ContentCapturingMode.SPAN_AND_EVENT,
+        )
+    )
+    if mode not in allowed_modes:
+        return {}
+
+    def serialize(items: Sequence[Any]) -> Any:
+        dicts = [asdict(item) for item in items]
+        return gen_ai_json_dumps(dicts) if for_span else dicts
+
+    optional_attrs = (
+        (
+            GenAI.GEN_AI_INPUT_MESSAGES,
+            serialize(input_messages) if input_messages else None,
+        ),
+        (
+            GenAI.GEN_AI_OUTPUT_MESSAGES,
+            serialize(output_messages) if output_messages else None,
+        ),
+        (
+            GenAI.GEN_AI_SYSTEM_INSTRUCTIONS,
+            serialize(system_instruction) if system_instruction else None,
+        ),
+        (
+            GenAI.GEN_AI_TOOL_DEFINITIONS,
+            serialize(tool_definitions) if tool_definitions else None,
+        ),
+    )
+    return {key: value for key, value in optional_attrs if value is not None}