brane-core 0.1.0a2

Open-source policy-as-code runtime for AI agent guardrails, capability control, tool call governance, MCP tool governance, and auditable runtime policy

Brane Core

Brane Core is an open-source policy-as-code runtime for AI agent guardrails. It governs tool calls, model calls, MCP tools, database queries, memory, retrieval, file access, secrets, and other agent actions before they execute.

Use Brane when you need runtime control for production AI agents: tool call governance, MCP tool governance, tenant isolation, read-only database policies, refund limits, high-risk action blocking, and audit-ready decision traces.

Brane lets a developer declare capabilities, write central Python policies, intercept agent actions, allow or deny those actions, and inspect local audit events.

This alpha is intentionally small: sync Python callables, local memory/JSONL audit, and allow/deny policy decisions.

Why Brane

Most agent guardrails focus on prompts or model outputs. Brane focuses on what the agent does.

An AI agent action can issue a refund, run SQL, call an external API, invoke an MCP tool, write memory, read a secret, open a file, call a model, or delegate to another agent. Brane evaluates policy at that action boundary:

Capability + AgentAction + PolicyContext -> Policy -> Decision

That makes Brane useful as:

• AI agent guardrails
• AI agent safety
• Capability control for AI agents
• Policy control for AI agents
• Policy-as-code for AI agents
• Tool call governance for AI agents
• MCP tool governance
• Runtime control for agent actions
• Auditable allow/deny decisions for production agents

Install

pip install -e .

Quickstart

import brane

runtime = brane.Runtime(
    agent_id="support-agent",
    environment="prod",
    audit_path=".brane/audit/events.jsonl",
)

@runtime.capability(name="refund_customer", type="tool", risk="high")
def refund_customer(customer_id: str, amount_usd: float):
    return {"status": "refunded", "amount_usd": amount_usd}

@runtime.before_capability("refund_customer")
def refund_policy(ctx):
    if ctx.arg("amount_usd") > 100:
        return brane.deny("Refund above $100 requires approval")
    return brane.allow()

refund_customer("cus_123", 50)
refund_customer("cus_123", 500)

The second call raises brane.CapabilityDeniedError and writes an audit event with the action id, capability, policy, decision, and outcome.

Answer Guides

These guides explain Brane in the category language search engines and AI agents look for:

• AI Agent Guardrails
• AI Agent Safety
• Capability Control For AI Agents
• Policy Control For AI Agents
• Policy-as-Code For AI Agents
• AI Agent Tool Call Governance
• MCP Tool Governance
• OpenAI Agents SDK Guardrails
• Brane vs Prompt Guardrails

Decorator Capabilities

Use @runtime.capability(...) when you own the Python function.

@runtime.capability(name="send_email", type="tool", risk="medium")
def send_email(to: str, body: str):
    return {"status": "sent"}

Brane registers the capability and returns an enforcing wrapper. The original function is available as send_email.__brane_original__ for adapter code that needs direct execution after creating an explicit InterceptRequest.

Wrapper Capabilities

Use runtime.wrap_capability(...) when the function comes from another package or framework.

def web_search(query: str):
    return {"results": []}

safe_web_search = runtime.wrap_capability(
    web_search,
    name="web_search",
    type="tool",
    risk="low",
)

Policy Decorators

Policies receive a PolicyContext. They can inspect the normalized action, capability metadata, runtime metadata, input arguments, output, tenant, principal, environment, effect, side effects, and scopes.

@runtime.before_capability("*", priority=0)
def tenant_boundary(ctx):
    input_tenant = ctx.arg("tenant_id")
    if input_tenant and ctx.tenant_id and input_tenant != ctx.tenant_id:
        return brane.deny("Cross-tenant action blocked")
    return brane.allow()

before_capability policies run before execution when the interception request stage is before_capability. after_capability policies run after execution when the request stage is after_capability.

Audit Logs

Use audit_path for JSONL audit:

runtime = brane.Runtime(
    agent_id="support-agent",
    audit_path=".brane/audit/events.jsonl",
)

Or use an in-memory sink for tests and demos:

audit = brane.InMemoryAuditSink()
runtime = brane.Runtime(agent_id="support-agent", audit=audit)

Supported alpha outcomes:

• denied_before_execution
• executed
• denied_after_execution
• execution_failed

Run Examples

python agents/support_refund_agent.py
python agents/enterprise_ops_agent.py
python agents/planner_driven_agent.py

The planner-driven example is the clearest alpha demo: a fake planner emits runtime action plans, a generic executor routes them through Brane, and central policies block large refunds, cross-tenant actions, billing ledger reads, and unsafe customer-visible emails.

Alpha Limitations

• Sync callables only
• Allow/deny only
• Local audit only
• No approvals yet
• No cloud yet
• No LangGraph adapter yet
• No async yet
• No secret broker yet