refactor(governance): migrate Google ADK adapter to factory-evaluator

aditik0303 · claude · aditik0303 · commit 39948ab30437 · 2026-06-30T20:34:53.000+05:30
Core PR #1761 removed BaseAdapter from uipath-core. Migrate to the
factory-evaluator pattern (matching #899):

- governance/adapter.py -&gt; callbacks.py: replace the BaseAdapter subclass
  (name/can_handle/attach/detach) with module-level install_governance()
  that installs governance on each LlmAgent's native *_callback slots
  (walking sub_agents); keep GovernanceCallbacks + the callback helpers;
  drop the detach-only _remove_callbacks. File named for its seam
  (callbacks), like LangChain's callbacks.py.
- runtime/factory.py: new_runtime reads `evaluator` from kwargs and
  calls install_governance before building the Runner.
- governance/__init__.py: drop register_governance_adapter + registry
  import; expose install_governance. No import-time side effects.
- pyproject.toml: remove the uipath.governance.adapters entry point.
- tests (test_adapter.py -&gt; test_callbacks.py): drop can_handle/attach/
  detach; cover install_governance + factory wiring.

ruff + mypy clean; 21 governance tests pass.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/packages/uipath-google-adk/pyproject.toml b/packages/uipath-google-adk/pyproject.toml
@@ -31,9 +31,6 @@ register = "uipath_google_adk.middlewares:register_middleware"
 [project.entry-points."uipath.runtime.factories"]
 google-adk = "uipath_google_adk.runtime:register_runtime_factory"
 
-[project.entry-points."uipath.governance.adapters"]
-google-adk = "uipath_google_adk.governance:register_governance_adapter"
-
 [project.urls]
 Homepage = "https://uipath.com"
 Repository = "https://github.com/UiPath/uipath-integrations-python"
diff --git a/packages/uipath-google-adk/src/uipath_google_adk/governance/__init__.py b/packages/uipath-google-adk/src/uipath_google_adk/governance/__init__.py
@@ -1,51 +1,20 @@
 """Governance integration for ``uipath-google-adk``.
 
-Registers :class:`GoogleADKAdapter` with the adapter registry in
-``uipath.core.adapters`` so the governance host can attach the ADK-specific
-inner hooks (BEFORE_MODEL, AFTER_MODEL, TOOL_CALL, AFTER_TOOL) when it sees a
-Google ADK agent.
-
-Registration is **idempotent**: calling :func:`register_governance_adapter`
-twice is a no-op on the second call.
-
-Wiring: the package exposes :func:`register_governance_adapter` as an entry
-point under ``uipath.governance.adapters``. The governance adapter discovery
-path calls it to register the adapter. Importing this module does not, by
-itself, mutate the global registry.
+Exposes :func:`install_governance` — installs governance callbacks
+(BEFORE_MODEL, AFTER_MODEL, TOOL_CALL, AFTER_TOOL) on every ``LlmAgent`` in an
+ADK agent tree's native ``*_callback`` slots. Wired into a run by passing an
+``evaluator`` to :class:`UiPathGoogleADKRuntimeFactory`; the factory calls
+:func:`install_governance` on the resolved agent.
+
+Importing this module has no side effects: no adapter is registered, no global
+state is mutated.
 """
 
 from __future__ import annotations
 
-import logging
-
-from uipath.core.adapters import get_adapter_registry
-
-from .adapter import GoogleADKAdapter, GovernanceCallbacks
-
-logger = logging.getLogger(__name__)
-
-_registered: bool = False
-
-
-def register_governance_adapter() -> None:
-    """Register :class:`GoogleADKAdapter` with the global registry.
-
-    Idempotent — safe to call multiple times.
-    """
-    global _registered
-    if _registered:
-        return
-    registry = get_adapter_registry()
-    if any(a.name == "GoogleADK" for a in registry.get_all()):
-        _registered = True
-        return
-    registry.register(GoogleADKAdapter())
-    _registered = True
-    logger.debug("Registered uipath-google-adk governance adapter")
-
+from .callbacks import GovernanceCallbacks, install_governance
 
 __all__ = [
-    "GoogleADKAdapter",
     "GovernanceCallbacks",
-    "register_governance_adapter",
-]
+    "install_governance",
+]
diff --git a/packages/uipath-google-adk/src/uipath_google_adk/governance/callbacks.py b/packages/uipath-google-adk/src/uipath_google_adk/governance/callbacks.py
@@ -1,20 +1,21 @@
-"""Google ADK adapter for UiPath governance.
+"""Google ADK governance callbacks for UiPath.
 
 Provides governance for Google ADK agents (``google.adk.agents.LlmAgent``
-and any ``BaseAgent`` tree containing them). Unlike the LangChain adapter
+and any ``BaseAgent`` tree containing them). Unlike the LangChain integration
 — which wraps a ``Runnable`` and intercepts ``invoke`` / ``ainvoke`` — ADK
 agents are executed by a ``Runner`` that holds its **own** reference to
 the agent object. Replacing ``runtime.agent`` with a proxy would never
-reach the ``Runner``. So this adapter installs governance directly onto
-each ``LlmAgent``'s native callback attributes, mutating them in place:
+reach the ``Runner``. So :func:`install_governance` installs governance
+directly onto each ``LlmAgent``'s native callback attributes, mutating them
+in place:
 
 - ``before_model_callback``  → BEFORE_MODEL
 - ``after_model_callback``   → AFTER_MODEL
 - ``before_tool_callback``   → TOOL_CALL
 - ``after_tool_callback``    → AFTER_TOOL
 
-Because the mutation is in place, :meth:`GoogleADKAdapter.attach` returns
-the **original agent** (hooks installed) rather than a wrapping proxy.
+Because the mutation is in place, :func:`install_governance` returns the
+**original agent** (hooks installed) rather than a wrapping proxy.
 Returning a proxy here would also break ADK's own ``isinstance(agent,
 LlmAgent)`` checks in output-schema / graph resolution, since ``LlmAgent``
 is a Pydantic model.
@@ -23,10 +24,11 @@
 *not* fired from here — they are owned by the governance host. Firing them
 here too would duplicate every boundary evaluation.
 
-Contracts and the evaluator protocol come from ``uipath-core``; this
-package contributes only the ADK-specific implementation and registers it
-with the adapter registry via the ``uipath.governance.adapters`` entry
-point.
+The evaluator protocol comes from ``uipath-core``; this package contributes
+only the ADK-specific wiring. Governance is installed by the runtime
+factory: passing an ``evaluator`` to ``new_runtime`` calls
+:func:`install_governance` on the resolved agent. No adapter registry, no
+entry point, no import-time side effects.
 
 Audit emission and enforcement (raising :class:`GovernanceBlockException`
 on DENY) are owned by the evaluator itself. Each callback only extracts
@@ -43,7 +45,7 @@
 from typing import Any, Dict, List
 from uuid import uuid4
 
-from uipath.core.adapters import BaseAdapter, EvaluatorProtocol
+from uipath.core.adapters import EvaluatorProtocol
 from uipath.core.governance.exceptions import GovernanceBlockException
 
 logger = logging.getLogger(__name__)
@@ -93,19 +95,6 @@ def _install_callback(agent: Any, attr: str, fn: Any) -> None:
     setattr(agent, attr, [fn, *handlers])
 
 
-def _remove_callbacks(agent: Any) -> None:
-    """Strip this adapter's governance callbacks from every managed slot."""
-    for attr in (_MODEL_BEFORE, _MODEL_AFTER, _TOOL_BEFORE, _TOOL_AFTER):
-        existing = getattr(agent, attr, None)
-        if existing is None:
-            continue
-        if isinstance(existing, list):
-            kept = [h for h in existing if not _is_governance_callable(h)]
-            setattr(agent, attr, kept or None)
-        elif _is_governance_callable(existing):
-            setattr(agent, attr, None)
-
-
 def _iter_llm_agents(root: Any) -> List[Any]:
     """Return every ``LlmAgent``-shaped node in the ``sub_agents`` tree.
 
@@ -132,67 +121,46 @@ def _iter_llm_agents(root: Any) -> List[Any]:
     return found
 
 
-class GoogleADKAdapter(BaseAdapter):
-    """Adapter for the Google ADK framework.
-
-    Detects ``google.adk`` agents and installs governance callbacks on
-    every ``LlmAgent`` reachable through the ``sub_agents`` tree.
-    """
+def install_governance(
+    agent: Any,
+    evaluator: EvaluatorProtocol,
+    *,
+    agent_name: str,
+    session_id: str,
+) -> Any:
+    """Install governance callbacks on the agent tree (mutated in place).
 
-    @property
-    def name(self) -> str:
-        return "GoogleADK"
-
-    def can_handle(self, agent: Any) -> bool:
-        """Return True only for a Google ADK ``BaseAgent`` (incl. LlmAgent trees)."""
-        try:
-            from google.adk.agents import BaseAgent
-        except ImportError:
-            return False
-        return isinstance(agent, BaseAgent)
-
-    def attach(
-        self,
-        agent: Any,
-        agent_id: str,
-        session_id: str,
-        evaluator: EvaluatorProtocol,
-    ) -> Any:
-        """Install governance callbacks on the agent (mutated in place).
+    Walks every ``LlmAgent`` reachable through ``sub_agents`` and prepends
+    governance to each model/tool callback slot, preserving existing handlers.
+    Returns the original ``agent`` — the ``Runner`` already holds this
+    reference, so in-place mutation is what wires governance into execution.
+    Idempotent: a slot that already carries a governance callback is skipped.
 
-        Returns the original ``agent`` — the ``Runner`` already holds this
-        reference, so in-place mutation is what actually wires governance
-        into execution. A wrapping proxy would not reach the ``Runner``
-        and would break ADK's ``isinstance(agent, LlmAgent)`` checks.
-        """
-        callbacks = GovernanceCallbacks(
-            evaluator=evaluator,
-            agent_name=agent_id,
-            session_id=session_id,
+    Called by :class:`UiPathGoogleADKRuntimeFactory` when an ``evaluator``
+    is supplied to ``new_runtime``.
+    """
+    callbacks = GovernanceCallbacks(
+        evaluator=evaluator,
+        agent_name=agent_name,
+        session_id=session_id,
+    )
+    llm_agents = _iter_llm_agents(agent)
+    for node in llm_agents:
+        _install_callback(node, _MODEL_BEFORE, callbacks.before_model)
+        _install_callback(node, _MODEL_AFTER, callbacks.after_model)
+        _install_callback(node, _TOOL_BEFORE, callbacks.before_tool)
+        _install_callback(node, _TOOL_AFTER, callbacks.after_tool)
+    if not llm_agents:
+        logger.warning(
+            "install_governance found no LlmAgent in %s — deep hooks will not fire",
+            type(agent).__name__,
         )
-        llm_agents = _iter_llm_agents(agent)
-        for node in llm_agents:
-            _install_callback(node, _MODEL_BEFORE, callbacks.before_model)
-            _install_callback(node, _MODEL_AFTER, callbacks.after_model)
-            _install_callback(node, _TOOL_BEFORE, callbacks.before_tool)
-            _install_callback(node, _TOOL_AFTER, callbacks.after_tool)
-        if not llm_agents:
-            logger.warning(
-                "GoogleADKAdapter found no LlmAgent in %s — deep hooks will not fire",
-                type(agent).__name__,
-            )
-        else:
-            logger.debug(
-                "Installed governance callbacks on %d ADK LlmAgent(s)",
-                len(llm_agents),
-            )
-        return agent
-
-    def detach(self, governed: Any) -> Any:
-        """Remove governance callbacks from the agent tree and return it."""
-        for node in _iter_llm_agents(governed):
-            _remove_callbacks(node)
-        return governed
+    else:
+        logger.debug(
+            "Installed governance callbacks on %d ADK LlmAgent(s)",
+            len(llm_agents),
+        )
+    return agent
 
 
 class GovernanceCallbacks:
diff --git a/packages/uipath-google-adk/src/uipath_google_adk/runtime/factory.py b/packages/uipath-google-adk/src/uipath_google_adk/runtime/factory.py
@@ -8,6 +8,7 @@
 from google.adk.runners import Runner
 from google.adk.sessions.sqlite_session_service import SqliteSessionService
 from openinference.instrumentation.google_adk import GoogleADKInstrumentor
+from uipath.core.adapters import EvaluatorProtocol
 from uipath.runtime import (
     UiPathRuntimeContext,
     UiPathRuntimeFactorySettings,
@@ -16,6 +17,7 @@
 )
 from uipath.runtime.errors import UiPathErrorCategory
 
+from uipath_google_adk.governance import install_governance
 from uipath_google_adk.runtime.config import GoogleADKConfig
 from uipath_google_adk.runtime.errors import (
     UiPathGoogleADKErrorCode,
@@ -209,6 +211,7 @@ async def _create_runtime_instance(
         agent: BaseAgent,
         runtime_id: str,
         entrypoint: str,
+        evaluator: EvaluatorProtocol | None = None,
     ) -> UiPathRuntimeProtocol:
         """
         Create a runtime instance from an agent.
@@ -217,7 +220,19 @@ async def _create_runtime_instance(
         retrieves or creates a session for the given runtime_id.
         Sessions persist across calls, enabling multi-turn conversations
         where only the current user message is sent each time.
+
+        When ``evaluator`` is supplied, governance callbacks are installed on
+        the agent tree in place via :func:`install_governance` before the
+        ``Runner`` is created.
         """
+        if evaluator is not None:
+            install_governance(
+                agent,
+                evaluator,
+                agent_name=entrypoint,
+                session_id=runtime_id,
+            )
+
         session_service = await self._get_session_service()
         runner = Runner(
             agent=agent,
@@ -256,7 +271,9 @@ async def new_runtime(
         Args:
             entrypoint: Agent name from google_adk.json
             runtime_id: Unique identifier for the runtime instance
-            **kwargs: Additional keyword arguments (unused)
+            **kwargs: Forwarded factory kwargs. Recognized: ``evaluator``
+                (``EvaluatorProtocol``) — when present, governance callbacks
+                are installed on the agent via :func:`install_governance`.
 
         Returns:
             Configured runtime instance with agent
@@ -267,6 +284,7 @@ async def new_runtime(
             agent=agent,
             runtime_id=runtime_id,
             entrypoint=entrypoint,
+            evaluator=kwargs.get("evaluator"),
         )
 
     async def dispose(self) -> None:
diff --git a/packages/uipath-google-adk/tests/governance/test_callbacks.py b/packages/uipath-google-adk/tests/governance/test_callbacks.py
diff --git a/packages/uipath-google-adk/uv.lock b/packages/uipath-google-adk/uv.lock
