fix(agent-framework): address remaining review minors (page 5)

Follow-up to the #361 review pass — the earlier commit covered streaming
(stream_result_hook), try/finally, trace_id, counters, and the _stringify cap;
these are the rest:

- middleware.py:113 (walk gap — page-2 theme + minor 8) — _iter_agents now
  RECURSES through nested WorkflowAgents (workflow-of-workflows). Before it
  stopped one level down, so a nested workflow's inner agents ran ungoverned.
  Converted to an explicit stack walk with a _MAX_GRAPH_NODES cap that logs
  when it trips (was a silent inline `len(seen) < 1000`).
- middleware.py:326 (_coerce_args) — log a warning when model_dump() fails
  instead of silently dropping the tool args from governance visibility.
- middleware.py:135 (nit) — inverted the empty-targets check to a guard clause.

Tests: nested-workflow recursion + cycle-safety (self-referential executor);
streaming + AFTER_MODEL-on-error were added in the earlier pass. 141 pass.

Acknowledged, unchanged: latest-message-only scan (same documented tradeoff as
#899); cached-agent re-attach does not apply — this factory does not cache
agents (fresh per runtime) and trace_id is no longer held.

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

Author: aditik0303

packages/uipath-agent-framework/src/uipath_agent_framework/governance/middleware.py

@@ -64,6 +64,10 @@
 # prompt — see :meth:`GovernanceCallbacks._latest_message_text`.
 _BEFORE_MODEL_TEXT_CAP = 64000
 
+# Hard cap on how many nodes the workflow walk visits, guarding against cyclic
+# or pathologically deep (nested) workflows. Hitting it is logged, not silent.
+_MAX_GRAPH_NODES = 1000
+
 
 def install_governance(
     agent: Any,
@@ -87,6 +91,13 @@ def install_governance(
         evaluator=evaluator, agent_name=agent_name, session_id=session_id
     )
     targets = _iter_agents(agent)
+    if not targets:
+        logger.warning(
+            "install_governance found no agent in %s — hooks will not fire",
+            type(agent).__name__,
+        )
+        return agent
+
     installed = 0
     for node in targets:
         existing = list(getattr(node, "middleware", None) or [])
@@ -99,42 +110,48 @@ def install_governance(
             *existing,
         ]
         installed += 1
-    if not targets:
-        logger.warning(
-            "install_governance found no agent in %s — hooks will not fire",
-            type(agent).__name__,
-        )
-    else:
-        logger.debug("Installed governance middleware on %d agent(s)", installed)
+    logger.debug("Installed governance middleware on %d agent(s)", installed)
     return agent
 
 
 def _iter_agents(root: Any) -> List[Any]:
     """Return every agent node carrying a ``middleware`` slot.
 
     A plain ``Agent`` is itself the target. A ``WorkflowAgent`` exposes its
-    inner agents through ``workflow.executors[*]._agent`` (the same traversal
-    the breakpoint middleware uses), so a multi-agent app is governed end to
-    end. Cycles / pathological size are bounded by an id-visited set and a cap.
+    inner agents through ``workflow.executors[*]._agent``. Those inner agents
+    can themselves be ``WorkflowAgent``s (workflow-of-workflows), so the walk
+    **recurses** through nested workflows rather than stopping one level down —
+    otherwise a nested workflow's agents would run ungoverned. Cycles and
+    pathological depth are bounded by an id-visited set and a hard cap
+    (``_MAX_GRAPH_NODES``), which logs rather than silently truncating.
     """
     found: List[Any] = []
     seen: set[int] = set()
-
-    def _add(node: Any) -> None:
+    stack: List[Any] = [root]
+    capped = False
+    while stack:
+        if len(seen) >= _MAX_GRAPH_NODES:
+            capped = True
+            break
+        node = stack.pop()
         if node is None or id(node) in seen:
-            return
+            continue
         seen.add(id(node))
         if hasattr(node, "middleware"):
             found.append(node)
-
-    _add(root)
-    workflow = getattr(root, "workflow", None)
-    executors = getattr(workflow, "executors", None)
-    if isinstance(executors, Mapping):
-        for executor in list(executors.values()):
-            inner = getattr(executor, "_agent", None)
-            if inner is not None and len(seen) < 1000:
-                _add(inner)
+        workflow = getattr(node, "workflow", None)
+        executors = getattr(workflow, "executors", None)
+        if isinstance(executors, Mapping):
+            for executor in executors.values():
+                inner = getattr(executor, "_agent", None)
+                if inner is not None:
+                    stack.append(inner)
+    if capped:
+        logger.warning(
+            "install_governance stopped walking the agent graph at the %d-node "
+            "cap; agents beyond it will not be governed",
+            _MAX_GRAPH_NODES,
+        )
     return found
 
 
@@ -359,8 +376,15 @@ def _coerce_args(arguments: Any) -> Dict[str, Any]:
             dumped = model_dump()
             if isinstance(dumped, dict):
                 return dumped
-        except Exception:  # noqa: BLE001 - fall through to empty
-            pass
+        except Exception as e:  # noqa: BLE001
+            # Don't silently drop the args from governance visibility — surface
+            # that they couldn't be coerced.
+            logger.warning(
+                "governance: could not coerce %s tool args to a dict (%s); "
+                "TOOL_CALL will see empty args",
+                type(arguments).__name__,
+                e,
+            )
     return {}
 
 

packages/uipath-agent-framework/tests/governance/test_middleware.py

@@ -125,6 +125,25 @@ def test_install_governance_installs_on_workflow_inner_agents():
         assert any(isinstance(m, GovernanceChatMiddleware) for m in node.middleware)
 
 
+def test_install_governance_recurses_into_nested_workflow():
+    """A WorkflowAgent inside a WorkflowAgent (workflow-of-workflows): the deep
+    leaf agent must still be governed, not left one level below the walk."""
+    leaf = FakeAgent("leaf")
+    inner = FakeWorkflowAgent([leaf])
+    root = FakeWorkflowAgent([inner])
+    install_governance(root, FakeEvaluator(), agent_name="x", session_id="s")
+    assert any(isinstance(m, GovernanceChatMiddleware) for m in leaf.middleware)
+
+
+def test_install_governance_is_cycle_safe():
+    """A workflow whose executor points back at itself must not loop forever."""
+    w = FakeWorkflowAgent([])
+    w.workflow.executors = {"self": SimpleNamespace(_agent=w)}
+    # completes (id-visited set breaks the cycle) and governs w exactly once
+    install_governance(w, FakeEvaluator(), agent_name="x", session_id="s")
+    assert sum(isinstance(m, GovernanceChatMiddleware) for m in w.middleware) == 1
+
+
 def test_install_governance_is_idempotent():
     agent = FakeAgent()
     ev = FakeEvaluator()