Docs/Python SDK/Runtime
Implemented

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:

ArgumentTypeDescription
agent_idstr | NoneIdentity of this agent. Used in every AgentAction record.
environmentstr | NoneRuntime environment: dev, staging, prod. Used in ctx.is_prod and action records.
tenant_idstr | NoneDefault tenant for all actions. Can be overridden per-action.
principal_idstr | NoneDefault principal (user or service) for all actions.
capabilitieslist[Capability]Pre-register capabilities at construction.
policieslist[Policy]Pre-register policies at construction.

Owned Components

AttributeTypePurpose
capabilitiesCapabilityRegistryStores and retrieves registered capabilities.
policyPolicyRegistryStores registered policy functions.
policiesPolicyEngineEvaluates actions against registered policies.
interceptorCapabilityInterceptorCore intercept-evaluate-execute loop.
callablesCallableCapabilityInterceptorWraps Python callables with interception and argument binding.

Methods

runtime.register_capability(capability: Capability)

Register a capability in the capability registry.

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

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

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

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

runtime.before_capability(target, name?, version?) → decorator

Register a policy that runs before the capability executes. Target is a capability name or wildcard.

runtime.after_capability(target, name?, version?) → decorator

Register a policy that runs after the capability executes with the output available on ctx.output.

runtime.create_action(capability_name, input, action_type?) → AgentAction

Create an AgentAction manually without calling through the callable interceptor.

runtime.evaluate_action(action: AgentAction) → Decision

Evaluate a manually created action against before_capability policies.

runtime.evaluate(capability_name, input) → Decision

Convenience method: create_action + evaluate_action in one call.

Common Setups

Minimal — local dev:

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):
    # Create a runtime with the request's tenant and principal
    runtime = Runtime(
        agent_id="support-agent",
        environment="prod",
        tenant_id=request.tenant_id,
        principal_id=request.user_id,
    )

    # Attach the same shared capabilities and policies
    runtime.register_capability(SHARED_REFUND_CAP)
    runtime.before_capability("refund_customer")(refund_policy)

    # Now all actions in this request have the right identity
    ...
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

Planned additions to the Runtime constructor:

  • 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