Writing Policies

Policies are functions. They take a PolicyContext and return a Decision.

Policy Function Shape

Every policy is a plain Python function:

from brane import Decision, PolicyContext

def my_policy(ctx: PolicyContext) -> Decision:
    return Decision(type="allow")

No inheritance, no framework, no configuration file. Just a function that receives context and returns a decision.

Registering Policies

Use @runtime.before_capability or @runtime.after_capability to register:

@runtime.before_capability("execute_sql")
def read_only_sql(ctx):
    if not ctx.arg("query").lower().strip().startswith("select"):
        return Decision(type="deny", reason="Only SELECT queries are allowed")
    return Decision(type="allow")

The decorator registers the function as a Policy targeting "execute_sql" at the before_capability stage. The original function is returned unchanged, so you can call it directly in tests.

Policy Targets

Exact match:

@runtime.before_capability("refund_customer")
def refund_policy(ctx):
    ...

Wildcard:

@runtime.before_capability("*")
def global_policy(ctx):
    if ctx.is_prod and ctx.is_high_risk:
        return Decision(type="deny", reason="High-risk actions blocked in prod")
    return Decision(type="allow")

Wildcard policies run alongside exact-match policies. Both are evaluated; deny wins.

Policy Metadata

Provide a name and version to make decisions traceable:

@runtime.before_capability(
    "refund_customer",
    name="refund_amount_limit",
    version="1.0",
    description="Blocks refunds above the tenant limit",
    priority=10,
)
def refund_limit_policy(ctx):
    amount = ctx.arg("amount_usd", 0)
    tenant_limit = get_tenant_limit(ctx.tenant_id)
    if amount > tenant_limit:
        return Decision(type="deny", reason=f"Amount exceeds limit of ${tenant_limit}")
    return Decision(type="allow")

The name and version are annotated onto the Decision and appear in CapabilityDeniedError.policy_name.

Policy Metadata Fields

name: human-readable identifier. Defaults to the function name.
version: policy version string.
description: what this policy enforces.
priority: higher priority runs first. Default is 0.
enabled: set False to disable without removing. Default is True.
source: where this policy came from.

Multiple Policies On The Same Capability

Multiple policies can target the same capability. They all run. Deny wins: if any policy returns deny, the action is denied regardless of other policies returning allow.

@runtime.before_capability("refund_customer", priority=10)
def refund_amount_limit(ctx):
    if ctx.arg("amount_usd", 0) > 100:
        return Decision(type="deny", reason="Amount too high")
    return Decision(type="allow")

@runtime.before_capability("refund_customer", priority=5)
def refund_scope_check(ctx):
    if not ctx.agent_has_scope("refunds:create"):
        return Decision(type="deny", reason="Missing refunds:create scope")
    return Decision(type="allow")

Testing Policies

Because policies are plain functions, you can test them by constructing a PolicyContext directly:

from brane import AgentAction, Capability, PolicyContext
from my_policies import refund_amount_limit

def test_refund_limit_deny():
    cap = Capability(name="refund_customer", type="tool", risk="high")
    action = AgentAction(
        action_type="tool_call",
        capability=cap,
        input={"customer_id": "cust_1", "amount_usd": 250.0},
    )
    ctx = PolicyContext(action=action, args=action.input)
    decision = refund_amount_limit(ctx)
    assert decision.denied
    assert "Amount too high" in decision.reason

Where Policy Lives

Policy should be a separate control layer: not scattered across tool implementations, not hidden in prompts, not inside ad hoc if-statements in the agent logic. Start with a single policy file per agent. Once policies are explicit, they can be tested, audited, reused, and eventually moved to a central policy system or cloud bundle.

Write explicit deny rules for high-risk capabilities rather than relying on allow-by-default.

Start Here

Core Model

Answer Guides

Build With Python

Recipes

Reference

Writing Policies

Policy Function Shape

Registering Policies

Policy Targets

Policy Metadata

Policy Metadata Fields

Multiple Policies On The Same Capability

Testing Policies

Where Policy Lives

​Policy Function Shape

​Registering Policies

​Policy Targets

​Policy Metadata

​Policy Metadata Fields

​Multiple Policies On The Same Capability

​Testing Policies

​Where Policy Lives

Policy Function Shape

Registering Policies

Policy Targets

Policy Metadata

Policy Metadata Fields

Multiple Policies On The Same Capability

Testing Policies

Where Policy Lives