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

Two ways the engine checks a call

Two methods run the same gate: a synchronous intercept_tool_execution and an asynchronous twin, and they answer an allowed call in different shapes, so the check your code writes depends on which one you call.

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

Every example so far called intercept_tool_execution, the synchronous method, from the One choke point for every tool call lesson. An agent written with asyncio calls intercept_tool_execution_async instead, and the two do not answer the same way. This is the one piece of the library's shape worth learning before it costs you an afternoon.

The synchronous gate: None means allow

The synchronous method returns None for an allowed call and a dictionary for a blocked one, the convention the rest of this part has used.

ExampleSync: None on allow, a dict on block
from agent_control_plane import PolicyEngine, AgentKernel

policy = PolicyEngine()
policy.add_constraint("support", ["order_status"])
kernel = AgentKernel(policy_engine=policy)

print("allow:", kernel.intercept_tool_execution("support", "order_status", {}))
print("block:", kernel.intercept_tool_execution("support", "delete_account", {}))

The asynchronous twin: a dict even on allow

The asynchronous method is a coroutine, so it is awaited. An allowed call comes back as {'allowed': True}, not None, and a blocked call carries an allowed key instead of a status key.

ExampleAsync: a dict on allow, with an allowed key
import asyncio

async def main():
    allow = await kernel.intercept_tool_execution_async("support", "order_status", {})
    block = await kernel.intercept_tool_execution_async("support", "delete_account", {})
    print("allow:", allow)
    print("block:", block)

asyncio.run(main())

The allowed call is the difference that bites. Code that tests verdict is None for allow, written against the synchronous gate, treats every asynchronous allow as a block, because {'allowed': True} is not None.

Which shape your code must check

Callintercept_tool_execution (sync)intercept_tool_execution_async
AllowedNone{'allowed': True}
Blockeddict with status='blocked'dict with allowed=False
Test for allowverdict is Noneverdict['allowed']

Shadow mode answers differently again

A kernel in shadow mode reports an allowed call as simulated instead of running it, which is how you try a policy without enforcing it. Even the allowed call now returns a dictionary, and the two methods disagree on its keys.

ExampleShadow allow: sync says simulated, async says allowed False
shadow = AgentKernel(policy_engine=policy, shadow_mode=True)

print("sync :", shadow.intercept_tool_execution("support", "order_status", {}))
print("async:", asyncio.run(shadow.intercept_tool_execution_async("support", "order_status", {})))

What the two methods agree and disagree on

  • They enforce the same policy. A blocked call is blocked on both, for the same reason, with the same error.
  • They report an allow differently. The synchronous method returns None; the asynchronous one returns {'allowed': True}.
  • Shadow mode splits them further. A simulated allow is a status='simulated' dict on the synchronous method and an allowed=False dict on the asynchronous one.

Where this difference matters

  • An async agent, where the gate must be awaited and the allow test is verdict['allowed'], not verdict is None.
  • Porting a gate from sync to async, where the allow check has to change or every call looks blocked.
  • Turning on shadow mode, where a loop that runs the tool on a None verdict stops running anything, because an allow is no longer None.
Watch out. Nothing in the library warns you that the two methods return different shapes, or that shadow mode changes the allow shape again. Pick one method and one allow test per codebase. Shadow mode is covered on its own in Shadow mode: trying a policy safely.
Try it yourself
  • Block a call on both methods and confirm the error string is identical.
  • Write an allow test that works for the asynchronous method and check it on an allowed and a blocked call.
  • Run the shadow-mode block with a blocked tool and compare its output to the allowed one.

Slow is fine. Stopping is the only problem.