feat(tools): measure model consultation escalations, tokens, and cost

Each successful `ModelConsultTool` result reports the advisor tokens and latency of that one consultation, but nothing adds them up across turns and models or sets them against the executor's own usage, so there is no way to tell whether escalating to a stronger model pays off.

Add `ModelConsultObservabilityPlugin`, exported from `google.adk.tools.model_consult` and `google.adk.plugins`. For every invocation it counts `ModelConsultTool` calls by outcome, advisor and executor tokens per model, advisor and end-to-end latency, the escalation rate, and an estimated cost when a price table is supplied. Each invocation ends with a `ModelConsultReport` passed to an optional sync or async `on_report` hook. The plugin also keeps cumulative `ModelConsultStats`, which `summary()` formats and `reset()` returns and clears in one step, so exporters can publish fixed windows without gaps. Closing a runner leaves runs in flight and the totals intact, so one instance can serve several runners at once, and the plugin tracks at most 10,000 unfinished invocations.

The plugin works alongside `ForceEscalationPlugin` in either registration order and does not count the gated calls that plugin refuses. In live sessions it counts consultations but no executor calls.

`ModelConsultReport`, `ModelConsultStats`, and `ModelConsultUsage` are exported from `google.adk.tools.model_consult`. Also add the developer unit guide under `docs/guides/tools/model_consult/observability_plugin/`.

Co-authored-by: Yuhan Gao <gaoyuhan@google.com>
PiperOrigin-RevId: 1001085702

Author: Yuhan Gao

docs/guides/README.md

@@ -103,6 +103,7 @@ This directory contains specific developer guides for the ADK Python implementat
 
 ### Plugins
 * [ForceEscalationPlugin](tools/model_consult/force_escalation_plugin/index.md) - Enforcing deterministic first-turn, repeated-tool-call, and pre-tool gating escalations to ModelConsultTool.
+* [ModelConsultObservabilityPlugin](tools/model_consult/observability_plugin/index.md) - Measuring ModelConsultTool escalations, advisor and executor tokens, latency, and estimated cost for every invocation.
 * [ReflectAndRetryModelPlugin](plugins/reflect_retry_model_plugin/index.md) - Self-healing, concurrent-safe error recovery for model failures.
 * [ReflectAndRetryToolPlugin](plugins/reflect_retry_tool_plugin/index.md) - Self-healing, concurrent-safe error recovery for tool failures.
 * [ToolCallIntegrityPlugin](plugins/tool_call_integrity_plugin/index.md) - Optional HMAC integrity check for stored function call arguments.

docs/guides/tools/model_consult/observability_plugin/index.md

@@ -22,6 +22,7 @@
 
 if TYPE_CHECKING:
   from ..tools.model_consult._force_escalation_plugin import ForceEscalationPlugin
+  from ..tools.model_consult._observability_plugin import ModelConsultObservabilityPlugin
   from ._reflect_retry_model_plugin import ReflectAndRetryModelPlugin
   from ._tool_call_integrity_plugin import ToolCallIntegrityError
   from ._tool_call_integrity_plugin import ToolCallIntegrityPlugin
@@ -34,6 +35,7 @@
     "DebugLoggingPlugin",
     "ForceEscalationPlugin",
     "LoggingPlugin",
+    "ModelConsultObservabilityPlugin",
     "PluginManager",
     "ReflectAndRetryModelPlugin",
     "ReflectAndRetryToolPlugin",
@@ -45,6 +47,9 @@
     "DebugLoggingPlugin": "debug_logging_plugin",
     "ForceEscalationPlugin": "..tools.model_consult._force_escalation_plugin",
     "LoggingPlugin": "logging_plugin",
+    "ModelConsultObservabilityPlugin": (
+        "..tools.model_consult._observability_plugin"
+    ),
     "ReflectAndRetryModelPlugin": "_reflect_retry_model_plugin",
     "ReflectAndRetryToolPlugin": "reflect_retry_tool_plugin",
     "ToolCallIntegrityError": "_tool_call_integrity_plugin",

src/google/adk/plugins/__init__.py

@@ -17,9 +17,17 @@
 from ._context import ModelConsultContextConfig
 from ._force_escalation_plugin import ForceEscalationPlugin
 from ._model_consult_tool import ModelConsultTool
+from ._observability_plugin import ModelConsultObservabilityPlugin
+from ._observability_plugin import ModelConsultReport
+from ._observability_plugin import ModelConsultStats
+from ._observability_plugin import ModelConsultUsage
 
 __all__ = [
     'ForceEscalationPlugin',
     'ModelConsultContextConfig',
+    'ModelConsultObservabilityPlugin',
+    'ModelConsultReport',
+    'ModelConsultStats',
     'ModelConsultTool',
+    'ModelConsultUsage',
 ]