feat(telemetry): add gen_ai.invoke_agent.{inference,tool}_calls metrics

Adds the two per-invocation call-count metrics from semconv #336
(open-telemetry/semantic-conventions-genai#336):

* gen_ai.invoke_agent.inference_calls: model calls in one invoke_agent span.
* gen_ai.invoke_agent.tool_calls: tool calls in one invoke_agent span.

Both are counted on the per-span TelemetryContext at the call sites
(record_inference_telemetry, record_tool_execution) and flushed in
record_agent_invocation, keyed by gen_ai.agent.name. One point per invoke_agent
span, so a multi-agent invocation does not double count. Failed calls still
count; only client-side tool calls count. Always emitted (a no-op without a
MeterProvider).

PiperOrigin-RevId: 940684383

Author: google-genai-bot

src/google/adk/agents/invocation_context.py

@@ -18,6 +18,7 @@
 from typing import Any
 from typing import cast
 from typing import Optional
+from typing import TYPE_CHECKING
 
 from google.adk.platform import uuid as platform_uuid
 from google.genai import types
@@ -47,6 +48,9 @@
 from .run_config import RunConfig
 from .transcription_entry import TranscriptionEntry
 
+if TYPE_CHECKING:
+  from google.adk.telemetry._instrumentation import TelemetryContext
+
 
 class LlmCallsLimitExceededError(Exception):
   """Error thrown when the number of LLM calls exceed the limit."""
@@ -270,6 +274,12 @@ class InvocationContext(BaseModel):
   of this invocation.
   """
 
+  _invoke_agent_telemetry_context: Optional[TelemetryContext] = PrivateAttr(
+      default=None
+  )
+  """TelemetryContext of the active ``invoke_agent`` span, if any.
+  """
+
   @property
   def is_resumable(self) -> bool:
     """Returns whether the current invocation is resumable."""

src/google/adk/telemetry/_instrumentation.py

@@ -27,11 +27,11 @@
 
 from . import _metrics
 from . import tracing
-from ..events import event as event_lib
 
 if TYPE_CHECKING:
   from ..agents.base_agent import BaseAgent
   from ..agents.invocation_context import InvocationContext
+  from ..events import event as event_lib
   from ..models.llm_request import LlmRequest
   from ..models.llm_response import LlmResponse
   from ..tools.base_tool import BaseTool
@@ -78,11 +78,31 @@ class TelemetryContext:
   error_type: str | None = None
   span: tracing.GenerateContentSpan | trace.Span | None = None
   _llm_responses: list[LlmResponse] = dataclasses.field(default_factory=list)
+  _inference_call_count: int = 0
+  _tool_call_count: int = 0
 
   @property
   def llm_responses(self) -> list[LlmResponse]:
     return self._llm_responses
 
+  @property
+  def inference_call_count(self) -> int:
+    """Number of model calls counted against this invoke_agent span."""
+    return self._inference_call_count
+
+  def increment_inference_calls(self) -> None:
+    """Counts one model call against this span (including calls that raised)."""
+    self._inference_call_count += 1
+
+  def increment_tool_calls(self) -> None:
+    """Counts one tool call against this invoke_agent span."""
+    self._tool_call_count += 1
+
+  @property
+  def tool_call_count(self) -> int:
+    """Number of tool calls counted against this invoke_agent span."""
+    return self._tool_call_count
+
   def record_llm_response(
       self, invocation_context: InvocationContext, response: LlmResponse
   ) -> None:
@@ -110,6 +130,30 @@ def _record_agent_metrics(
     logger.exception("Failed to record agent metrics for agent %s", agent_name)
 
 
+def _flush_invoke_agent_metrics(
+    tel_ctx: TelemetryContext, agent_name: str
+) -> None:
+  """Flushes this span's accumulated inference/tool-call metrics."""
+  _metrics.record_invoke_agent_inference_calls(
+      agent_name, tel_ctx.inference_call_count
+  )
+  _metrics.record_invoke_agent_tool_calls(agent_name, tel_ctx.tool_call_count)
+
+
+def _accumulate_invoke_agent_tool_call(ctx: InvocationContext) -> None:
+  """Counts one tool call against the active invoke_agent span."""
+  span_tel_ctx = ctx._invoke_agent_telemetry_context  # pylint: disable=protected-access
+  if span_tel_ctx is not None:
+    span_tel_ctx.increment_tool_calls()
+
+
+def _accumulate_invoke_agent_inference_call(ctx: InvocationContext) -> None:
+  """Counts one model call against the active invoke_agent span."""
+  span_tel_ctx = ctx._invoke_agent_telemetry_context  # pylint: disable=protected-access
+  if span_tel_ctx is not None:
+    span_tel_ctx.increment_inference_calls()
+
+
 @contextlib.asynccontextmanager
 async def record_agent_invocation(
     ctx: InvocationContext, agent: BaseAgent
@@ -119,11 +163,13 @@ async def record_agent_invocation(
   caught_error: Exception | None = None
   span: trace.Span | None = None
   span_name = f"invoke_agent {agent.name}"
+  tel_ctx = TelemetryContext()
   try:
     with tracing.tracer.start_as_current_span(span_name) as s:
       span = s
       tracing.trace_agent_invocation(span, agent, ctx)
-      tel_ctx = TelemetryContext(otel_context=context_api.get_current())
+      tel_ctx.otel_context = context_api.get_current()
+      ctx._invoke_agent_telemetry_context = tel_ctx  # pylint: disable=protected-access
       yield tel_ctx
   except Exception as e:
     caught_error = e
@@ -136,14 +182,15 @@ async def record_agent_invocation(
         getattr(getattr(ctx, "session", None), "events", []),
         caught_error,
     )
+    _flush_invoke_agent_metrics(tel_ctx, agent.name)
 
 
 @contextlib.asynccontextmanager
 async def record_tool_execution(
     tool: BaseTool,
     agent: BaseAgent,
     function_args: dict[str, object],
-    invocation_context: InvocationContext | None = None,
+    invocation_context: InvocationContext,
 ) -> AsyncIterator[TelemetryContext]:
   """Unified context manager for consolidated tool execution telemetry."""
   start_time = time.monotonic()
@@ -171,6 +218,7 @@ async def record_tool_execution(
             invocation_context=invocation_context,
             error_type=tel_ctx.error_type,
         )
+        _accumulate_invoke_agent_tool_call(invocation_context)
   finally:
     try:
       _metrics.record_tool_execution_duration(
@@ -205,6 +253,7 @@ async def record_inference_telemetry(
       yield tel_ctx
   finally:
     inference_error = sys.exc_info()[1]
+    _accumulate_invoke_agent_inference_call(invocation_context)
     agent = invocation_context.agent
     elapsed_s = _get_elapsed_s(tel_ctx.span, start_time)
     try:

src/google/adk/telemetry/_metrics.py

@@ -146,6 +146,44 @@
     gen_ai_metrics.create_gen_ai_client_operation_duration(meter)
 )
 _client_token_usage = gen_ai_metrics.create_gen_ai_client_token_usage(meter)
+_invoke_agent_inference_calls = meter.create_histogram(
+    "gen_ai.invoke_agent.inference_calls",
+    unit="1",
+    description="Number of inference (model) calls per agent invocation.",
+    explicit_bucket_boundaries_advisory=[
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        8,
+        12,
+        16,
+        24,
+        32,
+        64,
+    ],
+)
+_invoke_agent_tool_calls = meter.create_histogram(
+    "gen_ai.invoke_agent.tool_calls",
+    unit="1",
+    description="Number of tool calls per agent invocation.",
+    explicit_bucket_boundaries_advisory=[
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        8,
+        12,
+        16,
+        24,
+        32,
+        64,
+    ],
+)
 
 
 def record_agent_invocation_duration(
@@ -160,6 +198,18 @@ def record_agent_invocation_duration(
   _agent_invocation_duration.record(elapsed_s, attributes=attrs)
 
 
+def record_invoke_agent_inference_calls(agent_name: str, count: int):
+  """Records the number of inference (model) calls in an agent invocation."""
+  attrs = {gen_ai_attributes.GEN_AI_AGENT_NAME: agent_name}
+  _invoke_agent_inference_calls.record(count, attributes=attrs)
+
+
+def record_invoke_agent_tool_calls(agent_name: str, count: int):
+  """Records the number of tool calls in an agent invocation."""
+  attrs = {gen_ai_attributes.GEN_AI_AGENT_NAME: agent_name}
+  _invoke_agent_tool_calls.record(count, attributes=attrs)
+
+
 def record_agent_request_size(
     agent_name: str, user_content: types.Content | None
 ):

tests/unittests/telemetry/functional_node_test_cases.py

@@ -2900,6 +2900,12 @@
             value=NON_DETERMINISTIC,
         ),
     }),
+    "gen_ai.invoke_agent.inference_calls": frozenset({
+        MetricPoint(attributes={"gen_ai.agent.name": AGENT_NAME}, value=2),
+    }),
+    "gen_ai.invoke_agent.tool_calls": frozenset({
+        MetricPoint(attributes={"gen_ai.agent.name": AGENT_NAME}, value=1),
+    }),
 }
 
 
@@ -2947,6 +2953,12 @@
             value=NON_DETERMINISTIC,
         ),
     }),
+    "gen_ai.invoke_agent.inference_calls": frozenset({
+        MetricPoint(attributes={"gen_ai.agent.name": AGENT_NAME}, value=2),
+    }),
+    "gen_ai.invoke_agent.tool_calls": frozenset({
+        MetricPoint(attributes={"gen_ai.agent.name": AGENT_NAME}, value=1),
+    }),
 }
 
 

tests/unittests/telemetry/functional_test_cases.py

@@ -2294,6 +2294,12 @@
             value=NON_DETERMINISTIC,
         ),
     }),
+    "gen_ai.invoke_agent.inference_calls": frozenset({
+        MetricPoint(attributes={"gen_ai.agent.name": AGENT_NAME}, value=2),
+    }),
+    "gen_ai.invoke_agent.tool_calls": frozenset({
+        MetricPoint(attributes={"gen_ai.agent.name": AGENT_NAME}, value=1),
+    }),
 }
 
 
@@ -2341,6 +2347,12 @@
             value=NON_DETERMINISTIC,
         ),
     }),
+    "gen_ai.invoke_agent.inference_calls": frozenset({
+        MetricPoint(attributes={"gen_ai.agent.name": AGENT_NAME}, value=2),
+    }),
+    "gen_ai.invoke_agent.tool_calls": frozenset({
+        MetricPoint(attributes={"gen_ai.agent.name": AGENT_NAME}, value=1),
+    }),
 }
 
 

tests/unittests/telemetry/functional_test_helpers.py

@@ -339,6 +339,16 @@ class HistogramSpec(NamedTuple):
         attr="_client_token_usage",
         metric_name="gen_ai.client.token.usage",
     ),
+    HistogramSpec(
+        module=_metrics,
+        attr="_invoke_agent_inference_calls",
+        metric_name="gen_ai.invoke_agent.inference_calls",
+    ),
+    HistogramSpec(
+        module=_metrics,
+        attr="_invoke_agent_tool_calls",
+        metric_name="gen_ai.invoke_agent.tool_calls",
+    ),
 )
 
 

tests/unittests/telemetry/test_instrumentation.py

@@ -15,6 +15,7 @@
 # pylint: disable=protected-access
 
 import time
+import types
 from unittest import mock
 
 from google.adk.telemetry import _instrumentation
@@ -94,8 +95,8 @@ async def test_record_agent_invocation_tolerates_minimal_context():
   """
   agent = mock.MagicMock()
   agent.name = "test_agent"
-  # Bare object without `user_content` and without `session`.
-  bare_ctx = object()
+  # Context-like without `user_content` and without `session`.
+  bare_ctx = types.SimpleNamespace()
 
   with (
       mock.patch.object(