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.
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.
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"}))enforce: ran -> A-2291: out for delivery shadow : Success (Simulated)
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.
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)enforce status: blocked shadow status : blocked same verdict? True
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
Noneunder enforcement and a dictionary under shadow mode, so a loop that testsverdict is Nonestops running every allowed tool once shadow mode is on.
Enforce mode and shadow mode side by side
| A call the policy... | Enforce mode | Shadow mode |
|---|---|---|
| allows | None, the tool runs | {'status': 'simulated', ...}, the tool is skipped |
| denies | {'status': 'blocked', ...} | {'status': 'blocked', ...}, the same |
| Does the tool ever run | Yes, on an allow | No, 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.
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.Related
- Previous: Checking the toolkit's files with agt integrity
- Next: Both policy engines behind one gate
- See also: Two ways the engine checks a call
- Run the allowed call through the shadow kernel on its own and read the full simulated dictionary.
- Add
order_statusto a second role and rehearse that role's calls in shadow mode. - Switch the loop to
intercept_tool_execution_asyncand see the allowed verdict change shape again.
Little by little, you're building something great.