Runtime

The coordinator for capabilities and policies. Create one per agent process.

Definition

A Runtime owns the capability registry, the policy engine, and the interception machinery. You create one per agent process, configure it with capabilities and policies, and let it govern all capability calls.

Constructor

from brane import Runtime

runtime = Runtime(
    agent_id="support-agent",
    environment="prod",
    tenant_id="tenant_acme",
    principal_id="user_sarah",
)

All constructor arguments are optional.

Argument	Type	Description
`agent_id`	`str	None`	Identity of this agent. Used in every AgentAction record.
`environment`	`str	None`	Runtime environment: `dev`, `staging`, `prod`.
`tenant_id`	`str	None`	Default tenant for all actions. Can be overridden per action.
`principal_id`	`str	None`	Default principal for all actions.
`capabilities`	`list[Capability]`	Pre-register capabilities at construction.
`policies`	`list[Policy]`	Pre-register policies at construction.

Owned Components

Attribute	Type	Purpose
`capabilities`	`CapabilityRegistry`	Stores and retrieves registered capabilities.
`policy`	`PolicyRegistry`	Stores registered policy functions.
`policies`	`PolicyEngine`	Evaluates actions against registered policies.
`interceptor`	`CapabilityInterceptor`	Core intercept-evaluate-execute loop.
`callables`	`CallableCapabilityInterceptor`	Wraps Python callables with interception and argument binding.

Methods

runtime.register_capability(capability: Capability)

runtime.capability(name, type, risk, **kwargs)

Decorator that registers the function as a governed capability and wraps it with policy enforcement.

runtime.wrap_capability(fn, name, type, risk, **kwargs)

Wrap an existing function as a governed capability without decorator syntax.

runtime.before_capability(target, name=None, version=None)
runtime.after_capability(target, name=None, version=None)

runtime.create_action(capability_name, input, action_type=None)
runtime.evaluate_action(action)
runtime.evaluate(capability_name, input)

Create and evaluate actions manually.

Common Setups

Minimal local development:

runtime = Runtime(agent_id="my-agent")

Full production context:

runtime = Runtime(
    agent_id="support-agent",
    environment="prod",
    tenant_id=request.tenant_id,
    principal_id=request.user_id,
)

Pre-registering capabilities and policies:

from brane import Capability, Policy, Decision, Runtime

cap = Capability(name="send_email", type="tool", risk="medium")

def block_external_domains(ctx):
    to = ctx.arg("to", "")
    if not to.endswith("@acme.com"):
        return Decision(type="deny", reason="External email addresses are blocked")
    return Decision(type="allow")

policy = Policy(
    target="send_email",
    stage="before_capability",
    function=block_external_domains,
    name="block_external_email",
)

runtime = Runtime(
    agent_id="comms-agent",
    capabilities=[cap],
    policies=[policy],
)

Per-request runtime for multi-tenant systems:

def handle_request(request):
    runtime = Runtime(
        agent_id="support-agent",
        environment="prod",
        tenant_id=request.tenant_id,
        principal_id=request.user_id,
    )

    runtime.register_capability(SHARED_REFUND_CAP)
    runtime.before_capability("refund_customer")(refund_policy)

One runtime per agent process is the recommended pattern. If you need different tenant or principal contexts per request, create a new Runtime per request with the appropriate identity fields, or override them per create_action call.

Future Constructor Arguments

audit: AuditSink for recording action events
approvals: ApprovalProvider for handling approval_required decisions
cloud: CloudClient for remote policy evaluation
grants: GrantRegistry for agent capability grants
fail_mode: fail-open or fail-closed on policy engine errors

Start Here

Core Model

Answer Guides

Build With Python

Recipes

Reference

Definition

Constructor

Owned Components

Methods

Common Setups

Future Constructor Arguments

​Definition

​Constructor

​Owned Components

​Methods

​Common Setups

​Future Constructor Arguments

Definition

Constructor

Owned Components

Methods

Common Setups

Future Constructor Arguments