API Reference

Complete API documentation for predicate-secure.

SecureAgent

The main class for wrapping your agent with security features.

Constructor

class SecureAgent:
    def __init__(
        self,
        agent: Any,
        policy: str | Path

Parameters

Parameter	Type	Description
`agent`	`Any`	The agent to wrap (browser-use, Playwright, LangChain, etc.)
`policy`	`string \| null`	Path to YAML policy file
`mode`	`string`	Execution mode: `strict`, `permissive`, `debug`, or `audit`
`principalId`	`string \| null`	Agent principal ID for authorization
`sidecarUrl`	`string \| null`	Sidecar URL (default: `http://localhost:8787`)
`traceFormat`	`string`	Trace output format: `console` or `json`
`traceFile`	`string \| null`	Path to write trace output

Properties

@property
def config(self) -> SecureAgentConfig: ...

@property
def wrapped(self) -> WrappedAgent: ..

Methods

# Run the agent with authorization
def run(self, task: str | None = None) -> Any: ...

# Get the pre-action authorizer callback
def

Tracing Methods

# Trace a step
def trace_step(self, action: str, resource: str = "") -> int | None: ...

Static Methods

@staticmethod
def attach(agent: Any, policy: str = None, mode: str = "strict", **kwargs) -> SecureAgent:

Exceptions

class AuthorizationDenied(Exception):
    """Raised when an action is denied by policy"""
    decision: Any  # The authorization decision

class VerificationFailed(Exception):
    """Raised when post-execution verification fails"""
    predicate: str  # The failed predicate

Mode Constants

MODE_STRICT = "strict"
MODE_PERMISSIVE = "permissive"
MODE_DEBUG = "debug"
MODE_AUDIT = "audit"

Framework Detection

from predicate_secure import FrameworkDetector, Framework

detection = FrameworkDetector.detect(my_agent)
print(detection.framework)   # Framework.BROWSER_USE
print(detection.confidence)  # 1.0
print

Framework Enum

Value	Description
`BROWSER_USE`	browser-use Agent
`PLAYWRIGHT`	Playwright Page
`LANGCHAIN`	LangChain AgentExecutor
`PYDANTIC_AI`	PydanticAI Agent
`OPENCLAW`	OpenClaw CLI (Python only)
`UNKNOWN`	Unrecognized framework

Environment Variables

Variable	Description
`PREDICATE_AUTHORITY_POLICY_FILE`	Default policy file path
`PREDICATE_PRINCIPAL_ID`	Default agent principal ID
`PREDICATE_AUTHORITY_SIGNING_KEY`	Signing key for mandates
`PREDICATE_SECURE_VERBOSE`	Enable verbose logging

TypeScript Types

import type {
  SecureAgentOptions,
  SecureAgentConfig,
  WrappedAgent,
  DetectionResult,
  AdapterResult,
  TraceEvent,
  PolicyDecision,
  VerificationResult,
} from '@predicatesystems/predicate-secure';

Debug Mode