Docs/Concepts/Mental Model
Implemented

Mental Model

One formula covers every capability, every policy, every integration.

The Formula

Capability + AgentAction + PolicyContext → Policy → Decision

A Capability is anything an agent can use: a tool, a model, a memory store, a database, an MCP server, a secret, another agent.
An AgentAction is one attempted use of that capability — capturing identity, environment, input, and trace context.
A PolicyContext is the clean interface the policy author uses to inspect the action.
A Policy is a function that takes a PolicyContext and returns a Decision.
A Decision is what the runtime enforces.

The Lifecycle

01Capability is invoked — a function call, tool use, or API call
02Brane intercepts the invocation before the function executes
03Brane creates an AgentAction record capturing who, what, where, and with what
04Brane builds a PolicyContext — the clean developer-facing view of the action
05Matching before_capability policies evaluate the context in priority order
06Policy returns a Decision — allow or deny (more types planned)
07If denied: Brane raises CapabilityDeniedError. The function never executes.
08If allowed: the original function executes and returns output
09Brane creates an after-action record with the output included
10Matching after_capability policies evaluate — they can inspect the output
11If after policy denies: Brane raises CapabilityDeniedError after execution
12If after policy allows: Brane returns the output to the caller

Developer Example

Here is the full loop in code:

from brane import Decision, Runtime

# 1. Create a runtime for this agent
runtime = Runtime(agent_id="support-agent", environment="prod", tenant_id="acme")

# 2. Register a capability
@runtime.capability(name="refund_customer", type="tool", risk="high")
def refund_customer(customer_id: str, amount_usd: float):
    # actual refund logic here
    return {"refunded": True, "amount": amount_usd}

# 3. Write a before policy
@runtime.before_capability("refund_customer")
def limit_refund_amount(ctx):
    amount = ctx.arg("amount_usd", 0)
    if amount > 100:
        return Decision(type="deny", reason=f"Refund ${amount} exceeds $100 limit")
    return Decision(type="allow")

# 4. Call the capability
refund_customer("cust_123", 50.00)   # allowed
refund_customer("cust_456", 250.00)  # denied: Refund $250 exceeds $100 limit

At the refund_customer("cust_456", 250.00) call, Brane:

  1. Intercepts before the function runs
  2. Creates an AgentAction for support-agent in prod using refund_customer with amount_usd=250
  3. Builds a PolicyContext wrapping that action
  4. Finds limit_refund_amount, which matches refund_customer
  5. Calls the policy — ctx.arg("amount_usd") returns 250, which is over the limit
  6. Returns Decision(type="deny")
  7. Raises CapabilityDeniedError. The actual refund function never runs.

Security Team Example

The same formula expressed as a security policy:

@runtime.before_capability("*")  # matches all capabilities
def block_high_risk_in_prod(ctx):
    if ctx.is_prod and ctx.is_high_risk:
        return Decision(
            type="deny",
            reason="High-risk capability use is not allowed in prod without an approved workflow",
        )
    return Decision(type="allow")

ctx.is_prod checks the runtime environment. ctx.is_high_risk checks the capability's risk field. Neither requires knowing which specific capability was called — the policy works across the entire governed surface.

Why This Is The Right Boundary

The control boundary for agent systems is not the text they produce. It is the capabilities they use.

Policy on prompts and outputs leaves a gap: the agent can still call a tool, write a file, or query a database before the output is inspected. Policy on capability use catches the action at the right moment — before the consequence occurs.

The formula works the same regardless of the agent framework. LangGraph tools, CrewAI tools, OpenAI Agents SDK function tools, and MCP tool calls all reduce to the same AgentAction against the same capability. One policy runtime governs all of them.