Execution Modes

SecureAgent supports four execution modes to match different deployment scenarios.

Mode Overview

Mode	Behavior	Use Case	Sidecar Required
`strict`	Fail-closed: deny action if policy check fails	Production deployments	Yes
`permissive`	Log but don't block unauthorized actions	Development/testing	Yes
`debug`	Human-readable trace output	Troubleshooting	No
`audit`	Record decisions without enforcement	Compliance monitoring	No

Strict Mode (Default)

Strict mode is fail-closed: if a policy check fails, the action is denied and an exception is raised.

secure_agent = SecureAgent(
    agent=agent,
    policy="policy.yaml",
    mode="strict",  # Actions denied by policy will raise an exception
)

Error Handling in Strict Mode

from predicate_secure import AuthorizationDenied

try:
    secure_agent.run()
except AuthorizationDenied as e:
    print(f"Action blocked: {e}")
    print(f"Decision:

Permissive Mode

Permissive mode logs unauthorized actions but allows them to proceed. Useful for development and testing when you want to see what would be blocked.

secure_agent = SecureAgent(
    agent=agent,
    policy="policy.yaml",
    mode="permissive",  # Log unauthorized actions but don't block
)

Debug Mode

Debug mode provides detailed trace output for troubleshooting agent behavior. No sidecar is required.

secure_agent = SecureAgent(
    agent=agent,
    policy="policy.yaml",
    mode="debug",  # Show detailed trace output
)

See Debug Mode for detailed information on trace output and configuration.

Audit Mode

Audit mode records all decisions without enforcement. Useful for compliance monitoring and understanding agent behavior before enabling enforcement.

secure_agent = SecureAgent(
    agent=agent,
    policy="policy.yaml",
    mode="audit",  # Record all decisions without blocking
)

Mode Constants

You can use mode constants for type safety:

from predicate_secure import (
    MODE_STRICT,
    MODE_PERMISSIVE,
    MODE_DEBUG,
    MODE_AUDIT,
)

secure_agent = SecureAgent(
    agent=agent,
    policy="policy.yaml",
    mode=MODE_STRICT

Choosing a Mode

Scenario	Recommended Mode
Production deployment with real users	`strict`
Testing new policies before enforcement	`permissive`
Debugging agent behavior	`debug`
Developing new policies	`debug`
Compliance monitoring without blocking	`audit`
Local development without sidecar	`debug` or `audit`

Framework Guides

Writing Policies