chore(agents): tag ManagedAgent traffic with a +managed_agent version suffix

ManagedAgent and Gemini(use_interactions_api=True) both reach the Interactions
API and surface identically as tool_name=google-adk in Google's usage pipeline,
with no way to tell them apart. Thread an optional framework_label through
merge_tracking_headers / get_tracking_headers / get_client_labels /
_get_default_labels, and have ManagedAgent emit google-adk/<version>+managed_agent
on the per-request extra_headers it sends to interactions.create, so its traffic
is distinguishable via the tool_version dimension while tool_name stays
google-adk. The suffix is applied on the request-time header path because that is
what reaches the Interactions wire (the per-request extra_headers override the
genai client's construction-time headers; verified by live capture). An explicit
framework_label takes precedence over the Agent Engine (+remote_reasoning_engine)
suffix; all other callers of merge_tracking_headers keep the no-arg default and
are unchanged. Follow-up to the ManagedAgent tracking-headers change.

Co-authored-by: Haran Rajkumar <haranrk@google.com>
PiperOrigin-RevId: 947239702

Author: haranrk

src/google/adk/agents/_managed_agent.py

@@ -386,7 +386,9 @@ async def _run_async_impl(
         if run_config is not None and run_config.http_options is not None
         else None
     )
-    extra_headers = merge_tracking_headers(run_config_headers)
+    extra_headers = merge_tracking_headers(
+        run_config_headers, framework_label='managed_agent'
+    )
 
     logger.info(
         'Sending request via interactions API, agent: %s, stream: %s, '

src/google/adk/utils/_client_labels_utils.py

@@ -38,15 +38,24 @@
 )
 
 
-def _get_default_labels() -> List[str]:
-  """Returns a list of labels that are always added."""
-  framework_label = f"{_ADK_LABEL}/{version.__version__}"
-
-  if os.environ.get(_AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME):
-    framework_label = f"{framework_label}+{_AGENT_ENGINE_TELEMETRY_TAG}"
+def _get_default_labels(framework_label: str | None = None) -> List[str]:
+  """Returns a list of labels that are always added.
+
+  Args:
+    framework_label: Optional SemVer build-metadata suffix appended to the
+      google-adk framework token (e.g. "managed_agent" ->
+      "google-adk/<version>+managed_agent"). When provided, it takes precedence
+      over the Agent Engine (GOOGLE_CLOUD_AGENT_ENGINE_ID) suffix.
+  """
+  framework_token = f"{_ADK_LABEL}/{version.__version__}"
+
+  if framework_label:
+    framework_token = f"{framework_token}+{framework_label}"
+  elif os.environ.get(_AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME):
+    framework_token = f"{framework_token}+{_AGENT_ENGINE_TELEMETRY_TAG}"
 
   language_label = f"{_LANGUAGE_LABEL}/" + sys.version.split()[0]
-  return [framework_label, language_label]
+  return [framework_token, language_label]
 
 
 @contextmanager
@@ -68,9 +77,14 @@ def client_label_context(client_label: str) -> Iterator[None]:
     _LABEL_CONTEXT.reset(token)
 
 
-def get_client_labels() -> List[str]:
-  """Returns the current list of client labels that can be added to HTTP Headers."""
-  labels = _get_default_labels()
+def get_client_labels(framework_label: str | None = None) -> List[str]:
+  """Returns the current list of client labels that can be added to HTTP Headers.
+
+  Args:
+    framework_label: Optional SemVer build-metadata suffix for the google-adk
+      framework token (see _get_default_labels).
+  """
+  labels = _get_default_labels(framework_label=framework_label)
   current_client_label = _LABEL_CONTEXT.get()
 
   if current_client_label:

src/google/adk/utils/_google_client_headers.py

@@ -19,13 +19,18 @@
 from ._client_labels_utils import get_client_labels
 
 
-def get_tracking_headers() -> dict[str, str]:
+def get_tracking_headers(framework_label: str | None = None) -> dict[str, str]:
   """Returns a dictionary of HTTP headers for tracking API requests.
 
   These headers are used to identify HTTP calls made by ADK towards
    Vertex AI LLM APIs.
+
+  Args:
+    framework_label: Optional SemVer build-metadata suffix appended to the
+      google-adk framework token (e.g. "managed_agent"), used to distinguish a
+      specific ADK surface in Google's server-side usage pipeline.
   """
-  labels = get_client_labels()
+  labels = get_client_labels(framework_label=framework_label)
   header_value = " ".join(labels)
   return {
       "x-goog-api-client": header_value,
@@ -43,17 +48,24 @@ def get_tracking_http_options() -> types.HttpOptions:
   return types.HttpOptions(headers=get_tracking_headers())
 
 
-def merge_tracking_headers(headers: dict[str, str] | None) -> dict[str, str]:
+def merge_tracking_headers(
+    headers: dict[str, str] | None, framework_label: str | None = None
+) -> dict[str, str]:
   """Merge tracking headers to the given headers.
 
   Args:
     headers: headers to merge tracking headers into.
+    framework_label: Optional SemVer build-metadata suffix appended to the
+      google-adk framework token (e.g. "managed_agent"), used to distinguish a
+      specific ADK surface in Google's server-side usage pipeline.
 
   Returns:
     A dictionary of HTTP headers with tracking headers merged.
   """
   new_headers = (headers or {}).copy()
-  for key, tracking_header_value in get_tracking_headers().items():
+  for key, tracking_header_value in get_tracking_headers(
+      framework_label=framework_label
+  ).items():
     custom_value = new_headers.get(key, None)
     if not custom_value:
       new_headers[key] = tracking_header_value

tests/integration/test_managed_agent.py

@@ -23,6 +23,7 @@
 from __future__ import annotations
 
 import os
+import re
 
 from google.adk.agents import ManagedAgent
 from google.adk.runners import Runner
@@ -31,6 +32,7 @@
 from google.adk.tools import RemoteMcpServer
 from google.adk.utils.context_utils import Aclosing
 from google.genai import types
+import httpx
 import pytest
 
 _AGENT_ID = 'antigravity-preview-05-2026'
@@ -91,6 +93,86 @@ async def test_google_search_project_hail_mary():
   ), f'expected the grounded answer to contain "James Ortiz"; got: {answer!r}'
 
 
+@pytest.mark.asyncio
+async def test_interactions_request_carries_managed_agent_suffix(monkeypatch):
+  """The outgoing Interactions request must carry google-adk/<ver>+managed_agent.
+
+  Guards the per-request tracking suffix at runtime. Unit tests only prove ADK
+  builds the right extra_headers dict; this proves the suffix survives onto the
+  actual outgoing HTTP request. Hooks httpx.AsyncClient.send (the layer every
+  google-genai transport funnels through), runs a real ManagedAgent turn, and
+  inspects the first interaction request's headers. Runs on both backends by
+  default (see conftest llm_backend), covering the Gemini Developer API and
+  Vertex interaction endpoints.
+  """
+  captured: list[dict[str, str]] = []
+  orig_send = httpx.AsyncClient.send
+
+  async def _spy_send(self, request, **kwargs):
+    if 'interaction' in str(request.url).lower():
+      captured.append({
+          'x-goog-api-client': request.headers.get('x-goog-api-client', ''),
+          'user-agent': request.headers.get('user-agent', ''),
+      })
+    return await orig_send(self, request, **kwargs)
+
+  monkeypatch.setattr(httpx.AsyncClient, 'send', _spy_send)
+
+  agent = ManagedAgent(
+      name='managed_header_agent',
+      agent_id=_AGENT_ID,
+      environment={'type': 'remote'},
+      tools=[google_search],
+  )
+  session_service = InMemorySessionService()
+  runner = Runner(
+      app_name='managed_agent_it',
+      agent=agent,
+      session_service=session_service,
+  )
+  session = await session_service.create_session(
+      app_name='managed_agent_it', user_id='test_user'
+  )
+
+  # Request headers are set before any response is produced, so stop streaming
+  # as soon as an interaction request is captured. This keeps the test fast and
+  # independent of (non-deterministic) model output; any error after capture is
+  # irrelevant to the assertion.
+  run_error = None
+  try:
+    async with Aclosing(
+        runner.run_async(
+            user_id='test_user',
+            session_id=session.id,
+            new_message=types.Content(
+                role='user', parts=[types.Part.from_text(text='Say hi.')]
+            ),
+        )
+    ) as agen:
+      async for _ in agen:
+        if captured:
+          break
+  except Exception as e:  # noqa: BLE001 - header is captured before any later error
+    run_error = e
+
+  assert captured, (
+      'no Interactions request was observed on the wire; '
+      f'run raised: {run_error!r}'
+  )
+  api_client = captured[0]['x-goog-api-client']
+  user_agent = captured[0]['user-agent']
+  print('\n=== captured interaction request headers ===')
+  print('x-goog-api-client:', api_client)
+  print('user-agent:       ', user_agent)
+  assert re.search(r'google-adk/[^ ]*\+managed_agent', api_client), (
+      'expected google-adk/<version>+managed_agent in x-goog-api-client; '
+      f'got: {api_client!r}'
+  )
+  assert (
+      '+managed_agent' in user_agent
+  ), f'expected +managed_agent in user-agent; got: {user_agent!r}'
+
+
 @pytest.mark.asyncio
 async def test_code_execution_prime_sum():
   agent = ManagedAgent(

tests/unittests/agents/test_managed_agent.py

@@ -480,8 +480,8 @@ def test_run_async_merges_run_config_headers_into_extra_headers():
 
   extra_headers = client.aio.interactions.calls[0]['extra_headers']
   assert extra_headers['x-custom'] == 'v'
-  assert 'google-adk/' in extra_headers['x-goog-api-client']
-  assert 'google-adk/' in extra_headers['user-agent']
+  assert '+managed_agent' in extra_headers['x-goog-api-client']
+  assert '+managed_agent' in extra_headers['user-agent']
 
 
 def test_run_async_sends_tracking_headers_without_run_config_headers():
@@ -493,10 +493,9 @@ def test_run_async_sends_tracking_headers_without_run_config_headers():
 
   asyncio.run(_drain(agent._run_async_impl(ctx)))
 
-  assert (
-      client.aio.interactions.calls[0]['extra_headers']
-      == get_tracking_headers()
-  )
+  assert client.aio.interactions.calls[0][
+      'extra_headers'
+  ] == get_tracking_headers(framework_label='managed_agent')
 
 
 def test_run_async_sends_tracking_headers_when_http_options_has_no_headers():
@@ -509,10 +508,9 @@ def test_run_async_sends_tracking_headers_when_http_options_has_no_headers():
 
   asyncio.run(_drain(agent._run_async_impl(ctx)))
 
-  assert (
-      client.aio.interactions.calls[0]['extra_headers']
-      == get_tracking_headers()
-  )
+  assert client.aio.interactions.calls[0][
+      'extra_headers'
+  ] == get_tracking_headers(framework_label='managed_agent')
 
 
 def test_run_async_yields_multiple_events_in_order(monkeypatch):

tests/unittests/utils/test_client_labels_utils.py

@@ -66,3 +66,25 @@ def test_eval_client_label():
       f"google-adk-eval/{version.__version__}"
       == _client_labels_utils.EVAL_CLIENT_LABEL
   )
+
+
+def test_get_client_labels_with_framework_label():
+  """An explicit framework_label appends a +suffix to the google-adk token."""
+  labels = _client_labels_utils.get_client_labels(
+      framework_label="managed_agent"
+  )
+  assert len(labels) == 2
+  assert f"google-adk/{version.__version__}+managed_agent" == labels[0]
+  assert f"gl-python/{sys.version.split()[0]}" == labels[1]
+
+
+def test_framework_label_takes_precedence_over_agent_engine(monkeypatch):
+  """An explicit framework_label wins over the Agent Engine env-var suffix."""
+  monkeypatch.setenv(
+      _client_labels_utils._AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME,
+      "test-agent-id",
+  )
+  labels = _client_labels_utils.get_client_labels(
+      framework_label="managed_agent"
+  )
+  assert f"google-adk/{version.__version__}+managed_agent" == labels[0]

tests/unittests/utils/test_google_client_headers.py

@@ -86,3 +86,49 @@ def test_get_tracking_http_options():
       "x-goog-api-client": _EXPECTED_BASE_HEADER,
       "user-agent": _EXPECTED_BASE_HEADER,
   }
+
+
+def test_get_tracking_headers_with_framework_label():
+  """framework_label flows into both tracking header values."""
+  expected = (
+      f"google-adk/{version.__version__}+managed_agent"
+      f" gl-python/{sys.version.split()[0]}"
+  )
+  headers = _google_client_headers.get_tracking_headers(
+      framework_label="managed_agent"
+  )
+  assert headers == {
+      "x-goog-api-client": expected,
+      "user-agent": expected,
+  }
+
+
+def test_merge_tracking_headers_with_framework_label():
+  """framework_label flows into the merged tracking header values."""
+  expected = (
+      f"google-adk/{version.__version__}+managed_agent"
+      f" gl-python/{sys.version.split()[0]}"
+  )
+  headers = _google_client_headers.merge_tracking_headers(
+      None, framework_label="managed_agent"
+  )
+  assert headers == {
+      "x-goog-api-client": expected,
+      "user-agent": expected,
+  }
+
+
+def test_merge_tracking_headers_with_framework_label_preserves_custom_headers():
+  """The suffix is applied while unrelated custom headers pass through."""
+  expected = (
+      f"google-adk/{version.__version__}+managed_agent"
+      f" gl-python/{sys.version.split()[0]}"
+  )
+  headers = _google_client_headers.merge_tracking_headers(
+      {"x-custom": "v"}, framework_label="managed_agent"
+  )
+  assert headers == {
+      "x-goog-api-client": expected,
+      "user-agent": expected,
+      "x-custom": "v",
+  }