Observe Mode

Adding governance to a live agent pipeline is risky. You write a policy, deploy a callback handler, and hope it doesn't block a legitimate action or let a bad one through. If it does, you find out in production, usually from an alert at 2am or an auditor asking questions you can't answer.

The Asqav SDK now supports observe mode. One flag change, and the entire governance layer runs without touching the server. Every policy check, every signature, every enforcement decision gets logged locally so you can see exactly what would happen before you go live.

from asqav.extras.langchain import AsqavCallbackHandler

# Dry-run governance - logs decisions, never calls the server
handler = AsqavCallbackHandler(observe=True)

# Attach to your agent as usual
agent.invoke(
    "Delete all inactive user accounts",
    config={"callbacks": [handler]},
)

The handler intercepts every tool call and chain event. In observe mode it evaluates the action against your policies, builds the signature payload, and writes the result to a local log. The agent runs exactly as it would in production. The only difference is that nothing leaves your machine.

Semantic action patterns

Observe mode pairs well with semantic action types. Instead of signing a generic tool call, you label the action with what it actually means.

agent = asqav.Agent.create("db-maintenance")

# Tag the action with a semantic pattern
sig = agent.sign("sql-destructive", context={
    "query": "DROP TABLE inactive_users",
    "target": "production-db"
})

Semantic patterns like sql-destructive, api:transfer, or file:write let you write policies against categories of behavior instead of individual tool names. When a new tool shows up, the policy still applies if the semantic label matches.

Preflight explanations

Once you know what the governance layer will do, you probably want to know why. The preflight endpoint returns plain-English explanations alongside the allow/deny decision.

check = agent.preflight("sql-destructive")
if not check.cleared:
    for reason in check.reasons:
        print(reason)
    # "Policy 'prod-db-protection' blocks sql-destructive actions
    #  outside the maintenance window (Sat 02:00-06:00 UTC)"

The explanation includes the policy name, the rule that matched, and the specific condition that triggered it. No more guessing which of your twelve policies blocked the action.

A safer path to production

The workflow is straightforward. Run your agent with observe=True, review the log, adjust policies, repeat. When the log shows the right actions getting signed and the wrong ones getting blocked, flip the flag and deploy. You get the same audit trail structure in both modes, so the transition is a one-line change.

Install or upgrade:

pip install --upgrade asqav

Full docs at asqav.com/docs. Source on GitHub. If something doesn't work the way you expect, open an issue.