refactor(governance): migrate OpenAI Agents adapter to factory-evaluator

Core PR #1761 dropped BaseAdapter + AdapterRegistry from uipath-core
(only EvaluatorProtocol remains), so the entry-point/adapter model no
longer compiles against current core. Migrate to the factory-evaluator
pattern used by the LangChain adapter (#899):

- governance/adapter.py: replace the BaseAdapter subclass (name/
  can_handle/attach/detach) with a module-level install_governance();
  keep GovernanceAgentHooks + the handoff-graph walk + chaining.
- runtime/factory.py: new_runtime reads `evaluator` from kwargs and
  calls install_governance on the resolved agent.
- governance/__init__.py: drop register_governance_adapter + the
  registry import; expose install_governance. No import-time side effects.
- pyproject.toml: remove the uipath.governance.adapters entry point.
- tests: drop can_handle/attach/detach tests; cover install_governance
  + factory wiring (evaluator present installs, absent skips).

ruff + mypy clean; 24 governance tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aditik0303

packages/uipath-openai-agents/pyproject.toml

@@ -31,9 +31,6 @@ register = "uipath_openai_agents.middlewares:register_middleware"
 [project.entry-points."uipath.runtime.factories"]
 openai-agents = "uipath_openai_agents.runtime:register_runtime_factory"
 
-[project.entry-points."uipath.governance.adapters"]
-openai-agents = "uipath_openai_agents.governance:register_governance_adapter"
-
 [project.urls]
 Homepage = "https://uipath.com"
 Repository = "https://github.com/UiPath/uipath-integrations-python"

packages/uipath-openai-agents/src/uipath_openai_agents/governance/__init__.py

@@ -1,51 +1,20 @@
 """Governance integration for ``uipath-openai-agents``.
 
-Registers :class:`OpenAIAgentsAdapter` with the adapter registry in
-``uipath.core.adapters`` so the governance host can attach the
-OpenAI-Agents-specific inner hooks (BEFORE_MODEL, AFTER_MODEL, TOOL_CALL,
-AFTER_TOOL) when it sees an OpenAI Agents 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 the OpenAI-Agents-specific inner
+hooks (BEFORE_MODEL, AFTER_MODEL, TOOL_CALL, AFTER_TOOL) onto an agent's native
+``hooks`` slot. Wired into a run by passing an ``evaluator`` to
+:class:`UiPathOpenAIAgentRuntimeFactory`; 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 GovernanceAgentHooks, OpenAIAgentsAdapter
-
-logger = logging.getLogger(__name__)
-
-_registered: bool = False
-
-
-def register_governance_adapter() -> None:
-    """Register :class:`OpenAIAgentsAdapter` with the global registry.
-
-    Idempotent — safe to call multiple times.
-    """
-    global _registered
-    if _registered:
-        return
-    registry = get_adapter_registry()
-    if any(a.name == "OpenAIAgents" for a in registry.get_all()):
-        _registered = True
-        return
-    registry.register(OpenAIAgentsAdapter())
-    _registered = True
-    logger.debug("Registered uipath-openai-agents governance adapter")
-
+from .adapter import GovernanceAgentHooks, install_governance
 
 __all__ = [
     "GovernanceAgentHooks",
-    "OpenAIAgentsAdapter",
-    "register_governance_adapter",
+    "install_governance",
 ]

packages/uipath-openai-agents/src/uipath_openai_agents/governance/adapter.py

@@ -30,9 +30,12 @@
 boundary evaluation. (The SDK's per-agent ``on_start`` / ``on_end`` are
 pass-through-only here for that reason.)
 
-Contracts and the evaluator protocol come from ``uipath-core``; this package
-contributes only the OpenAI-Agents-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 OpenAI-Agents-specific wiring. Governance is installed by the runtime
+factory: passing an ``evaluator`` to
+:class:`UiPathOpenAIAgentRuntimeFactory.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 hook only extracts the relevant
@@ -50,7 +53,7 @@
 from uuid import uuid4
 
 from agents import Agent, AgentHooks
-from uipath.core.adapters import BaseAdapter, EvaluatorProtocol
+from uipath.core.adapters import EvaluatorProtocol
 from uipath.core.governance.exceptions import GovernanceBlockException
 
 logger = logging.getLogger(__name__)
@@ -62,73 +65,46 @@
 # full prompt — see :func:`_latest_input_text`.
 _BEFORE_MODEL_TEXT_CAP = 64000
 
-# Marks an agent we have already governed so a double ``attach`` is a no-op and
-# ``detach`` can restore the hooks slot to whatever was there before.
-_PREV_HOOKS_ATTR = "_uipath_governance_prev_hooks"
 
+def install_governance(
+    agent: Agent,
+    evaluator: EvaluatorProtocol,
+    *,
+    agent_name: str,
+    session_id: str,
+) -> Agent:
+    """Install governance hooks on the agent graph (mutated in place).
 
-class OpenAIAgentsAdapter(BaseAdapter):
-    """Adapter for the OpenAI Agents SDK.
+    Walks every agent reachable through ``handoffs`` and installs a
+    :class:`GovernanceAgentHooks` on each one's ``hooks`` slot, chaining to any
+    pre-existing hooks. Returns the original ``agent`` — the ``Runner`` already
+    holds this reference, so in-place mutation is what wires governance into
+    execution. Idempotent: an already-governed agent is left untouched.
 
-    Detects ``agents.Agent`` instances and installs governance hooks on every
-    agent reachable through the ``handoffs`` graph.
+    Called by :class:`UiPathOpenAIAgentRuntimeFactory` when an ``evaluator``
+    is supplied to ``new_runtime``.
     """
-
-    @property
-    def name(self) -> str:
-        return "OpenAIAgents"
-
-    def can_handle(self, agent: Any) -> bool:
-        """Return True only for an OpenAI Agents ``Agent``."""
-        return isinstance(agent, Agent)
-
-    def attach(
-        self,
-        agent: Any,
-        agent_id: str,
-        session_id: str,
-        evaluator: EvaluatorProtocol,
-    ) -> Any:
-        """Install governance hooks on the agent graph (mutated in place).
-
-        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 the SDK's ``isinstance(agent, Agent)`` checks.
-        """
-        agents = _iter_agents(agent)
-        installed = 0
-        for node in agents:
-            if isinstance(getattr(node, "hooks", None), GovernanceAgentHooks):
-                continue  # idempotent — already governed
-            prev = getattr(node, "hooks", None)
-            hooks = GovernanceAgentHooks(
-                evaluator=evaluator,
-                agent_name=agent_id,
-                session_id=session_id,
-                inner=prev,
-            )
-            # Remember what was there so detach can restore it.
-            setattr(node, _PREV_HOOKS_ATTR, prev)
-            node.hooks = hooks
-            installed += 1
-        if not agents:
-            logger.warning(
-                "OpenAIAgentsAdapter found no Agent in %s — deep hooks will not fire",
-                type(agent).__name__,
-            )
-        else:
-            logger.debug("Installed governance hooks on %d OpenAI agent(s)", installed)
-        return agent
-
-    def detach(self, governed: Any) -> Any:
-        """Restore each agent's original ``hooks`` slot and return the graph."""
-        for node in _iter_agents(governed):
-            if isinstance(getattr(node, "hooks", None), GovernanceAgentHooks):
-                node.hooks = getattr(node, _PREV_HOOKS_ATTR, None)
-            if hasattr(node, _PREV_HOOKS_ATTR):
-                delattr(node, _PREV_HOOKS_ATTR)
-        return governed
+    agents = _iter_agents(agent)
+    installed = 0
+    for node in agents:
+        if isinstance(getattr(node, "hooks", None), GovernanceAgentHooks):
+            continue  # idempotent — already governed
+        prev = getattr(node, "hooks", None)
+        node.hooks = GovernanceAgentHooks(
+            evaluator=evaluator,
+            agent_name=agent_name,
+            session_id=session_id,
+            inner=prev,
+        )
+        installed += 1
+    if not agents:
+        logger.warning(
+            "install_governance found no Agent in %s — deep hooks will not fire",
+            type(agent).__name__,
+        )
+    else:
+        logger.debug("Installed governance hooks on %d OpenAI agent(s)", installed)
+    return agent
 
 
 def _iter_agents(root: Any) -> List[Any]:

packages/uipath-openai-agents/src/uipath_openai_agents/runtime/factory.py

@@ -5,6 +5,7 @@
 
 from agents import Agent
 from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
+from uipath.core.adapters import EvaluatorProtocol
 from uipath.runtime import (
     UiPathRuntimeContext,
     UiPathRuntimeFactorySettings,
@@ -13,6 +14,7 @@
 )
 from uipath.runtime.errors import UiPathErrorCategory
 
+from uipath_openai_agents.governance import install_governance
 from uipath_openai_agents.runtime.agent import OpenAiAgentLoader
 from uipath_openai_agents.runtime.config import OpenAiAgentsConfig
 from uipath_openai_agents.runtime.errors import (
@@ -201,6 +203,7 @@ async def _create_runtime_instance(
         agent: Agent,
         runtime_id: str,
         entrypoint: str,
+        evaluator: EvaluatorProtocol | None = None,
     ) -> UiPathRuntimeProtocol:
         """
         Create a runtime instance from an agent.
@@ -209,10 +212,20 @@ async def _create_runtime_instance(
             agent: The OpenAI Agent
             runtime_id: Unique identifier for the runtime instance
             entrypoint: Agent entrypoint name
+            evaluator: When supplied, governance hooks are installed on the
+                agent graph in place via :func:`install_governance`.
 
         Returns:
             Configured runtime instance
         """
+        if evaluator is not None:
+            install_governance(
+                agent,
+                evaluator,
+                agent_name=entrypoint,
+                session_id=runtime_id,
+            )
+
         return UiPathOpenAIAgentRuntime(
             agent=agent,
             runtime_id=runtime_id,
@@ -228,7 +241,9 @@ async def new_runtime(
         Args:
             entrypoint: Agent name from openai_agents.json
             runtime_id: Unique identifier for the runtime instance
-            **kwargs: Additional keyword arguments (unused)
+            **kwargs: Forwarded factory kwargs. Recognized: ``evaluator``
+                (``EvaluatorProtocol``) — when present, governance hooks are
+                installed on the agent via :func:`install_governance`.
 
         Returns:
             Configured runtime instance with agent
@@ -239,6 +254,7 @@ async def new_runtime(
             agent=agent,
             runtime_id=runtime_id,
             entrypoint=entrypoint,
+            evaluator=kwargs.get("evaluator"),
         )
 
     async def dispose(self) -> None: