Agent Governance ToolkitAgent Governance Toolkit 4.1.0 · Python 3.10+
Dashboard
0%

Shadow mode: trying a policy safely

Shadow mode is a kernel setting that returns a simulated success for any call the policy allows, instead of running the tool, so you can put a new gate in front of real traffic and watch it decide without a single tool firing.

Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0

The Two ways the engine checks a call lesson noted that a kernel in shadow mode answers an allowed call differently. This lesson puts that to work: you turn shadow mode on to rehearse a policy against the shop agent before you let it enforce anything.

Turning shadow mode on

Syntax: pass shadow_mode=True when you build the kernel. Here the same policy is wrapped twice, once to enforce and once to rehearse, so the two can be compared on the same calls.

python
import warnings; warnings.simplefilter("ignore")
from agent_control_plane import PolicyEngine, AgentKernel

# support may check a status; everything else is denied by default
policy = PolicyEngine()
policy.add_constraint("support", ["order_status"])

# the same policy, enforced two ways
enforce = AgentKernel(policy_engine=policy)
shadow = AgentKernel(policy_engine=policy, shadow_mode=True)

An allowed call is simulated, not run

The loop asks the gate and honours the verdict: None means run the tool, anything else is used as the result. Under enforcement an allowed call returns None and the tool runs. Under shadow mode the same call comes back as a simulated-success dictionary, and the tool is never called.

ExampleAn allowed call runs under enforcement and is simulated in shadow mode
def order_status(order_id):
    return f"{order_id}: out for delivery"

def run(kernel, tool, args):
    verdict = kernel.intercept_tool_execution("support", tool, args)
    if verdict is None:                     # None means allowed: run the tool
        return "ran -> " + order_status(**args)
    return verdict.get("result", verdict.get("status"))   # else use the verdict

print("enforce:", run(enforce, "order_status", {"order_id": "A-2291"}))
print("shadow :", run(shadow, "order_status", {"order_id": "A-2291"}))

A denied call is still blocked in shadow mode

Shadow mode does not turn blocking off. The policy check runs before the shadow step, so a call the policy denies comes back as the same blocked verdict whether the kernel is enforcing or shadowing. Shadow mode only changes the allow path.

ExampleA denied call is refused in both modes
blocked_enforce = enforce.intercept_tool_execution("support", "delete_account", {})
blocked_shadow = shadow.intercept_tool_execution("support", "delete_account", {})

print("enforce status:", blocked_enforce["status"])
print("shadow status :", blocked_shadow["status"])
print("same verdict? ", blocked_enforce == blocked_shadow)

What the two runs tell you

  • An allowed call does not run the tool in shadow mode. It returns Success (Simulated), so you can route live traffic through the gate and no tool fires.
  • A denied call is still denied. Shadow mode is a rehearsal of the allow path, not an off switch for enforcement, so a blocked tool stays blocked.
  • The verdict shape changes. An allow is None under enforcement and a dictionary under shadow mode, so a loop that tests verdict is None stops running every allowed tool once shadow mode is on.

Enforce mode and shadow mode side by side

A call the policy...Enforce modeShadow mode
allowsNone, the tool runs{'status': 'simulated', ...}, the tool is skipped
denies{'status': 'blocked', ...}{'status': 'blocked', ...}, the same
Does the tool ever runYes, on an allowNo, never

Where you use shadow mode

  • Trying a tighter policy on real traffic, watching what it would allow and deny before any tool acts on the result.
  • A migration, where a new allow-list runs in shadow next to the old one so you can compare their verdicts.
  • A smoke test, confirming the gate is wired into every tool call without the calls having side effects.
Watch out. Shadow mode is not a passive observer. An allowed tool is replaced by a simulated result, so any agent downstream sees Success (Simulated) rather than the real answer, and a denied tool is still blocked outright. Treat shadow mode as a dry run, not as a way to let everything through. The sync and async methods also report a simulated allow with different keys, which Two ways the engine checks a call covers.
Try it yourself
  • Run the allowed call through the shadow kernel on its own and read the full simulated dictionary.
  • Add order_status to a second role and rehearse that role's calls in shadow mode.
  • Switch the loop to intercept_tool_execution_async and see the allowed verdict change shape again.

Little by little, you're building something great.