feat(telemetry): add new gen_ai.agent.version span attribute

Achuth17 · copybara-github · commit ffe97ec5ad72 · 2026-03-09T23:13:13.000-07:00
Link to Issue or Description of Change
1. Link to an existing issue (if applicable):

Closes: #issue_number
Related: #issue_number
2. Or, if no issue exists, describe the change:

Problem:
The agent's specific version wasn't being tracked in our telemetry data, limiting our ability to trace issues to specific agent versions. This change introduces the gen_ai.agent.version attribute to span context, defaulting to an empty string if omitted for backwards compatibility.

Solution:
We want to capture the specific version of an agent during execution by adding an optional version field to the base agent configurations (BaseAgent, BaseAgentConfig).

This solution was chosen because exposing this field directly to OpenTelemetry span attributes (gen_ai.agent.version) ensures the version is automatically recorded alongside other existing metadata (like name and description) during invocation. Defaulting the value to an empty string ensures backwards compatibility without breaking existing agent implementations that do not specify a version.

Testing Plan

- Added test_trace_agent_invocation_with_version to verify that the gen_ai.agent.version attribute is correctly captured when agent.version is populated.
- Updated existing telemetry span tests to ensure gen_ai.agent.version safely defaults to an empty string ('') when no version is provided.

Unit Tests:

- I have added or updated unit tests for my change.
- All unit tests pass locally.

Manual End-to-End (E2E) Tests:

- Tested on Agent Engine and in a local deployment.

Checklist
[x] I have read the CONTRIBUTING.md document.
[x] I have performed a self-review of my own code.
[x] I have commented my code, particularly in hard-to-understand areas.
[x] I have added tests that prove my fix is effective or that my feature works.
[x] New and existing unit tests pass locally with my changes.
[x] I have manually tested my changes end-to-end.
[x] Any dependent changes have been merged and published in downstream modules.

Additional context
Add any other context or screenshots about the feature request here.

Co-authored-by: Achuth Narayan Rajagopal &lt;achuthr@google.com&gt;
PiperOrigin-RevId: 881234134
diff --git a/src/google/adk/agents/base_agent.py b/src/google/adk/agents/base_agent.py
@@ -136,6 +136,12 @@ class MyAgent(BaseAgent):
   sub_agents: list[BaseAgent] = Field(default_factory=list)
   """The sub-agents of this agent."""
 
+  version: str = ''
+  """The agent's version.
+
+  Version of the agent being invoked. Used to identify the Agent involved in telemetry.
+  """
+
   before_agent_callback: Optional[BeforeAgentCallback] = None
   """Callback or list of callbacks to be invoked before the agent run.
 
@@ -680,6 +686,7 @@ def __create_kwargs(
 
     kwargs: Dict[str, Any] = {
         'name': config.name,
+        'version': config.version,
         'description': config.description,
     }
     if config.sub_agents:
diff --git a/src/google/adk/agents/base_agent_config.py b/src/google/adk/agents/base_agent_config.py
@@ -55,6 +55,10 @@ class BaseAgentConfig(BaseModel):
 
   name: str = Field(description='Required. The name of the agent.')
 
+  version: str = Field(
+      default='', description='Optional. The version of the agent.'
+  )
+
   description: str = Field(
       default='', description='Optional. The description of the agent.'
   )
diff --git a/src/google/adk/telemetry/tracing.py b/src/google/adk/telemetry/tracing.py
@@ -83,6 +83,8 @@
 
 USER_CONTENT_ELIDED = '<elided>'
 
+GEN_AI_AGENT_VERSION = 'gen_ai.agent.version'
+
 # Needed to avoid circular imports
 if TYPE_CHECKING:
   from ..agents.base_agent import BaseAgent
@@ -157,6 +159,7 @@ def trace_agent_invocation(
   span.set_attribute(GEN_AI_AGENT_DESCRIPTION, agent.description)
 
   span.set_attribute(GEN_AI_AGENT_NAME, agent.name)
+  span.set_attribute(GEN_AI_AGENT_VERSION, agent.version)
   span.set_attribute(GEN_AI_CONVERSATION_ID, ctx.session.id)
 
 
@@ -465,6 +468,7 @@ def use_generate_content_span(
       USER_ID: invocation_context.session.user_id,
       'gcp.vertex.agent.event_id': model_response_event.id,
       'gcp.vertex.agent.invocation_id': invocation_context.invocation_id,
+      GEN_AI_AGENT_VERSION: invocation_context.agent.version,
   }
   if (
       _is_gemini_agent(invocation_context.agent)
@@ -499,6 +503,7 @@ async def use_inference_span(
       USER_ID: invocation_context.session.user_id,
       'gcp.vertex.agent.event_id': model_response_event.id,
       'gcp.vertex.agent.invocation_id': invocation_context.invocation_id,
+      GEN_AI_AGENT_VERSION: invocation_context.agent.version,
   }
   if (
       _is_gemini_agent(invocation_context.agent)
diff --git a/tests/unittests/telemetry/test_spans.py b/tests/unittests/telemetry/test_spans.py
@@ -26,6 +26,7 @@
 from google.adk.models.llm_response import LlmResponse
 from google.adk.sessions.in_memory_session_service import InMemorySessionService
 from google.adk.telemetry.tracing import ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS
+from google.adk.telemetry.tracing import GEN_AI_AGENT_VERSION
 from google.adk.telemetry.tracing import trace_agent_invocation
 from google.adk.telemetry.tracing import trace_call_llm
 from google.adk.telemetry.tracing import trace_inference_result
@@ -121,6 +122,33 @@ async def test_trace_agent_invocation(mock_span_fixture):
       mock.call('gen_ai.operation.name', 'invoke_agent'),
       mock.call('gen_ai.agent.description', agent.description),
       mock.call('gen_ai.agent.name', agent.name),
+      mock.call(GEN_AI_AGENT_VERSION, ''),
+      mock.call(
+          'gen_ai.conversation.id',
+          invocation_context.session.id,
+      ),
+  ]
+  mock_span_fixture.set_attribute.assert_has_calls(
+      expected_calls, any_order=True
+  )
+  assert mock_span_fixture.set_attribute.call_count == len(expected_calls)
+
+
+@pytest.mark.asyncio
+async def test_trace_agent_invocation_with_version(mock_span_fixture):
+  """Test trace_agent_invocation sets span attributes correctly when version is provided."""
+  agent = LlmAgent(name='test_llm_agent', model='gemini-pro')
+  agent.description = 'Test agent description'
+  agent.version = '1.0.0'
+  invocation_context = await _create_invocation_context(agent)
+
+  trace_agent_invocation(mock_span_fixture, agent, invocation_context)
+
+  expected_calls = [
+      mock.call('gen_ai.operation.name', 'invoke_agent'),
+      mock.call('gen_ai.agent.description', agent.description),
+      mock.call('gen_ai.agent.name', agent.name),
+      mock.call(GEN_AI_AGENT_VERSION, agent.version),
       mock.call(
           'gen_ai.conversation.id',
           invocation_context.session.id,
@@ -769,6 +797,7 @@ async def test_generate_content_span(
 
   mock_span.set_attributes.assert_called_once_with({
       GEN_AI_AGENT_NAME: invocation_context.agent.name,
+      GEN_AI_AGENT_VERSION: '',
       GEN_AI_CONVERSATION_ID: invocation_context.session.id,
       USER_ID: invocation_context.session.user_id,
       'gcp.vertex.agent.event_id': 'event-123',
@@ -1089,6 +1118,7 @@ async def test_generate_content_span_with_experimental_semconv(
 
   mock_span.set_attributes.assert_called_once_with({
       GEN_AI_AGENT_NAME: invocation_context.agent.name,
+      GEN_AI_AGENT_VERSION: '',
       GEN_AI_CONVERSATION_ID: invocation_context.session.id,
       USER_ID: invocation_context.session.user_id,
       'gcp.vertex.agent.event_id': 'event-123',

Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,10 @@ class BaseAgentConfig(BaseModel):`
`55`	`55`
`56`	`56`	`name: str = Field(description='Required. The name of the agent.')`
`57`	`57`
	`58`	`+ version: str = Field(`
	`59`	`+ default='', description='Optional. The version of the agent.'`
	`60`	`+ )`
	`61`	`+`
`58`	`62`	`description: str = Field(`
`59`	`63`	`default='', description='Optional. The description of the agent.'`
`60`	`64`	`)`