Writing Policies

Policies are YAML files that define what actions your agent can perform.

Basic Structure

rules:
  - action: "<action_pattern>"
    resource: "<resource_pattern>"
    effect: allow | deny
    require_verification:  # optional
      - <predicate>

Action Patterns

Actions represent what the agent is trying to do:

Pattern	Matches	Example
`browser.click`	Specific action	Only click events
`browser.*`	Action prefix	All browser actions
`tool.search`	Tool call	Search tool invocation
`api.call`	API request	HTTP API calls
`*`	Everything	Catch-all rule

Resource Patterns

Resources represent what the agent is acting on:

Pattern	Matches	Example
`https://example.com/*`	URL prefix	All pages on domain
`checkout`	Contains text	Any checkout URL
`button#submit`	CSS selector	Specific element
`/safe/path/*`	File path prefix	Safe directory
`*`	Everything	Catch-all

Verification Predicates

Predicates ensure the action had the expected effect:

require_verification:
  # URL checks
  - url_contains: "/checkout"
  - url_matches: "^https://.*\\.example\\.com/.*"

  # DOM checks
  - element_exists: "#cart-items"
  - element_text_contains:
      selector: ".total"
      text: "$"

  # Custom predicates
  - predicate: "cart_not_empty"

Available Predicates

Predicate	Description
`url_contains`	Check if current URL contains a string
`url_matches`	Check if current URL matches a regex pattern
`element_exists`	Check if an element exists on the page
`element_text_contains`	Check if an element's text contains a string
`text_matches`	Check if page text matches a pattern
`snapshot_changed`	Check if page snapshot changed after action

Rule Order

Rules are evaluated top-to-bottom. The first matching rule wins:

rules:
  # Specific rules first
  - action: "browser.click"
    resource: "*checkout*"
    effect: allow

  # General rules after
  - action: "browser.*"
    resource: "https://example.com/*"
    effect: allow

  # Default deny last
  - action: "*"
    resource: "*"
    effect: deny

Best practices:

Put specific rules before general rules
Always end with a default deny rule
Group related rules together with comments

Complete Policy Example

# policies/shopping.yaml
#
# Policy for an e-commerce shopping agent

rules:
  # Allow browsing the store
  - action: "browser.navigate"
    resource: "https://*.amazon.com/*"
    effect: allow

  - action: "browser.click"
    resource: "https://*.amazon.com/*"
    effect: allow

  - action: "browser.fill"
    resource: "https://*.amazon.com/*"
    effect: allow

  # Allow checkout with verification
  - action: "browser.click"
    resource: "*place-order*"
    effect: allow
    require_verification:
      - url_contains: "/checkout"
      - element_exists: "#cart-items"

  # Block navigation to external sites
  - action: "browser.navigate"
    resource: "https://malicious.com/*"
    effect: deny

  # Block sensitive actions
  - action: "browser.fill"
    resource: "*password*"
    effect: deny

  # Default: deny everything else
  - action: "*"
    resource: "*"
    effect: deny

Tool Authorization Policy

For LangChain or other tool-based agents:

# policies/tools.yaml
rules:
  # Allow search and calculator
  - action: "tool.search"
    resource: "*"
    effect: allow

  - action: "tool.calculator"
    resource: "*"
    effect: allow

  # Block file operations
  - action: "tool.file_write"
    resource: "*"
    effect: deny

  # Block shell commands
  - action: "tool.shell"
    resource: "*"
    effect: deny

  # Default deny
  - action: "*"
    resource: "*"
    effect: deny

Policy Loading

# Load from file path
secure_agent = SecureAgent(
    agent=agent,
    policy="policies/shopping.yaml",
)

# Or use environment variable
# Set PREDICATE_AUTHORITY_POLICY_FILE=policies/shopping.yaml
secure_agent = SecureAgent(agent=agent)

Modes

Debug Mode