update base class

Author: etserend

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

@@ -213,47 +213,47 @@ def llm(
             raise
         self.stop_llm(invocation)
 
-    # ---- Agent creation lifecycle ----
+    # ---- Agent lifecycle ----
 
-    def start_create_agent(
+    def start_agent(
         self,
-        creation: AgentCreation,
+        agent: AgentCreation,
     ) -> AgentCreation:
-        """Start an agent creation and create a pending span entry."""
-        span_name = f"{creation.operation_name} {creation.agent_name}".strip()
+        """Start an agent operation (create or invoke) and create a pending span entry."""
+        span_name = f"{agent.operation_name} {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)
+        agent.monotonic_start_s = timeit.default_timer()
+        agent.span = span
+        agent.context_token = otel_context.attach(set_span_in_context(span))
+        return agent
+
+    def stop_agent(self, agent: AgentCreation) -> AgentCreation:  # pylint: disable=no-self-use
+        """Finalize an agent operation successfully and end its span."""
+        if agent.context_token is None or agent.span is None:
+            return agent
+
+        span = agent.span
+        _apply_creation_finish_attributes(span, agent)
+        otel_context.detach(agent.context_token)
         span.end()
-        return creation
+        return agent
 
-    def fail_create_agent(  # pylint: disable=no-self-use
-        self, creation: AgentCreation, error: Error
+    def fail_agent(  # pylint: disable=no-self-use
+        self, agent: 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
+        """Fail an agent operation and end its span with error status."""
+        if agent.context_token is None or agent.span is None:
+            return agent
 
-        span = creation.span
-        _apply_creation_finish_attributes(span, creation)
+        span = agent.span
+        _apply_creation_finish_attributes(span, agent)
         _apply_error_attributes(span, error)
-        otel_context.detach(creation.context_token)
+        otel_context.detach(agent.context_token)
         span.end()
-        return creation
+        return agent
 
     @contextmanager
     def create_agent(
@@ -269,15 +269,13 @@ def create_agent(
         """
         if creation is None:
             creation = AgentCreation()
-        self.start_create_agent(creation)
+        self.start_agent(creation)
         try:
             yield creation
         except Exception as exc:
-            self.fail_create_agent(
-                creation, Error(message=str(exc), type=type(exc))
-            )
+            self.fail_agent(creation, Error(message=str(exc), type=type(exc)))
             raise
-        self.stop_create_agent(creation)
+        self.stop_agent(creation)
 
 
 def get_telemetry_handler(

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

@@ -301,12 +301,12 @@ def _get_base_agent_common_attributes(
 ) -> 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_REQUEST_MODEL, agent.model),
         (GenAI.GEN_AI_PROVIDER_NAME, agent.provider),
-        (_GEN_AI_AGENT_NAME, agent.agent_name),
+        (_GEN_AI_AGENT_NAME, agent.name),
         (_GEN_AI_AGENT_ID, agent.agent_id),
-        (_GEN_AI_AGENT_DESCRIPTION, agent.agent_description),
-        (_GEN_AI_AGENT_VERSION, agent.agent_version),
+        (_GEN_AI_AGENT_DESCRIPTION, agent.description),
+        (_GEN_AI_AGENT_VERSION, agent.version),
         (server_attributes.SERVER_ADDRESS, agent.server_address),
         (server_attributes.SERVER_PORT, agent.server_port),
     )
@@ -319,8 +319,8 @@ def _get_base_agent_common_attributes(
 
 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}"
+    if agent.name:
+        return f"{agent.operation_name} {agent.name}"
     return agent.operation_name
 
 
@@ -353,10 +353,10 @@ def _apply_creation_finish_attributes(
             ContentCapturingMode.SPAN_ONLY,
             ContentCapturingMode.SPAN_AND_EVENT,
         )
-        and creation.system_instruction
+        and creation.system_instructions
     ):
         attributes[GenAI.GEN_AI_SYSTEM_INSTRUCTIONS] = gen_ai_json_dumps(
-            [asdict(p) for p in creation.system_instruction]
+            [asdict(p) for p in creation.system_instructions]
         )
 
     attributes.update(creation.attributes)

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

@@ -238,33 +238,26 @@ class LLMInvocation(GenAIInvocation):
 
 @dataclass
 class _BaseAgent(GenAIInvocation):
-    """
-    Shared base class for agent lifecycle types (AgentInvocation, AgentCreation).
-
-    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 or AgentCreation.
+    """Shared base class for agent lifecycle types. Do not instantiate
+    directly — use AgentCreation (or AgentInvocation in future).
+    The span and context_token attributes are set by the TelemetryHandler.
     """
 
     # Agent identity
-    agent_name: str | None = None
+    name: str | None = None
     agent_id: str | None = None
-    agent_description: str | None = None
-    agent_version: str | None = None
+    description: str | None = None
+    version: str | None = None
 
     # Operation
     operation_name: str = ""
     provider: str | None = None
 
     # Request
-    request_model: str | None = None
+    model: str | None = None  # primary model if applicable
 
     # Content (Opt-In)
-    system_instruction: list[MessagePart] = field(
+    system_instructions: list[MessagePart] = field(
         default_factory=_new_system_instruction
     )
 
@@ -285,17 +278,13 @@ class _BaseAgent(GenAIInvocation):
 @dataclass
 class AgentCreation(_BaseAgent):
     """
-    Represents agent creation/initialization (create_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#create-agent-span
-
-    When creating an AgentCreation object, only update the data attributes.
-    The span and context_token attributes are set by the TelemetryHandler.
+    Represents an agent creation/initialization. When creating an AgentCreation
+    object, only update the data attributes. The span and context_token
+    attributes are set by the TelemetryHandler.
     """
 
     # Override default operation name
-    operation_name: str = "create_agent"
+    operation_name: str = GenAI.GenAiOperationNameValues.CREATE_AGENT.value
 
 
 @dataclass

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

@@ -40,13 +40,13 @@ def _make_handler(self) -> TelemetryHandler:
     def test_start_stop_create_agent(self) -> None:
         handler = self._make_handler()
         creation = AgentCreation(
-            agent_name="New Agent",
+            name="New Agent",
             agent_id="agent-new-1",
             provider="openai",
-            request_model="gpt-4",
+            model="gpt-4",
         )
-        handler.start_create_agent(creation)
-        handler.stop_create_agent(creation)
+        handler.start_agent(creation)
+        handler.stop_agent(creation)
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(len(spans), 1)
@@ -59,27 +59,27 @@ def test_start_stop_create_agent(self) -> None:
 
     def test_create_agent_span_kind_is_client(self) -> None:
         handler = self._make_handler()
-        creation = AgentCreation(agent_name="Client Agent")
-        handler.start_create_agent(creation)
-        handler.stop_create_agent(creation)
+        creation = AgentCreation(name="Client Agent")
+        handler.start_agent(creation)
+        handler.stop_agent(creation)
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(spans[0].kind, SpanKind.CLIENT)
 
     def test_create_agent_with_all_base_attributes(self) -> None:
         handler = self._make_handler()
         creation = AgentCreation(
-            agent_name="Full Agent",
+            name="Full Agent",
             agent_id="agent-123",
-            agent_description="A test agent",
-            agent_version="1.0.0",
+            description="A test agent",
+            version="1.0.0",
             provider="openai",
-            request_model="gpt-4",
+            model="gpt-4",
             server_address="api.openai.com",
             server_port=443,
         )
-        handler.start_create_agent(creation)
-        handler.stop_create_agent(creation)
+        handler.start_agent(creation)
+        handler.stop_agent(creation)
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(len(spans), 1)
@@ -94,10 +94,10 @@ def test_create_agent_with_all_base_attributes(self) -> None:
 
     def test_fail_create_agent(self) -> None:
         handler = self._make_handler()
-        creation = AgentCreation(agent_name="Bad Agent")
-        handler.start_create_agent(creation)
+        creation = AgentCreation(name="Bad Agent")
+        handler.start_agent(creation)
         error = Error(message="creation failed", type=RuntimeError)
-        handler.fail_create_agent(creation, error)
+        handler.fail_agent(creation, error)
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(len(spans), 1)
@@ -107,7 +107,7 @@ def test_fail_create_agent(self) -> None:
     def test_create_agent_context_manager(self) -> None:
         handler = self._make_handler()
         creation = AgentCreation(
-            agent_name="CM Agent",
+            name="CM Agent",
             provider="openai",
         )
         with handler.create_agent(creation) as c:
@@ -120,7 +120,7 @@ def test_create_agent_context_manager(self) -> None:
     def test_create_agent_context_manager_error(self) -> None:
         handler = self._make_handler()
         with self.assertRaises(TypeError):
-            with handler.create_agent(AgentCreation(agent_name="Err")):
+            with handler.create_agent(AgentCreation(name="Err")):
                 raise TypeError("bad type")
 
         spans = self.span_exporter.get_finished_spans()
@@ -130,24 +130,24 @@ def test_create_agent_context_manager_error(self) -> None:
     def test_create_agent_context_manager_default(self) -> None:
         handler = self._make_handler()
         with handler.create_agent() as c:
-            c.agent_name = "Dynamic Agent"
+            c.name = "Dynamic Agent"
             c.provider = "openai"
 
         spans = self.span_exporter.get_finished_spans()
         self.assertEqual(len(spans), 1)
 
-    def test_stop_create_agent_without_start_is_noop(self) -> None:
+    def test_stop_agent_without_start_is_noop(self) -> None:
         handler = self._make_handler()
-        creation = AgentCreation(agent_name="Not Started")
-        result = handler.stop_create_agent(creation)
+        creation = AgentCreation(name="Not Started")
+        result = handler.stop_agent(creation)
         self.assertIs(result, creation)
         self.assertEqual(len(self.span_exporter.get_finished_spans()), 0)
 
-    def test_fail_create_agent_without_start_is_noop(self) -> None:
+    def test_fail_agent_without_start_is_noop(self) -> None:
         handler = self._make_handler()
-        creation = AgentCreation(agent_name="Not Started")
+        creation = AgentCreation(name="Not Started")
         error = Error(message="boom", type=RuntimeError)
-        result = handler.fail_create_agent(creation, error)
+        result = handler.fail_agent(creation, error)
         self.assertIs(result, creation)
         self.assertEqual(len(self.span_exporter.get_finished_spans()), 0)
 
@@ -158,21 +158,21 @@ class TestAgentCreationTypes(TestCase):
     def test_agent_creation_defaults(self) -> None:
         creation = AgentCreation()
         self.assertEqual(creation.operation_name, "create_agent")
-        self.assertIsNone(creation.agent_name)
+        self.assertIsNone(creation.name)
         self.assertIsNone(creation.agent_id)
-        self.assertIsNone(creation.agent_description)
-        self.assertIsNone(creation.agent_version)
+        self.assertIsNone(creation.description)
+        self.assertIsNone(creation.version)
         self.assertIsNone(creation.provider)
-        self.assertIsNone(creation.request_model)
-        self.assertEqual(creation.system_instruction, [])
+        self.assertIsNone(creation.model)
+        self.assertEqual(creation.system_instructions, [])
         self.assertIsNone(creation.server_address)
         self.assertIsNone(creation.server_port)
         self.assertIsNone(creation.span)
         self.assertIsNone(creation.context_token)
 
     def test_agent_creation_custom_attributes(self) -> None:
         creation = AgentCreation(
-            agent_name="Custom",
+            name="Custom",
             attributes={"custom.key": "custom_value"},
         )
         self.assertEqual(creation.attributes["custom.key"], "custom_value")