Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.brane.membranelabs.org/llms.txt

Use this file to discover all available pages before exploring further.

One attempted use of a capability. The unit of interception, authorization, and audit.

​
Definition

A Capability describes what exists. An AgentAction is one attempted use of it. That distinction matters. Policy cannot make useful decisions from tool_name = refund_customer. It needs the attempted use: which agent, acting for which principal, in which tenant, in which environment, with which arguments, right now. The AgentAction captures all of that. It is the thing the runtime inspects, authorizes, modifies, audits, or blocks.

​
How Actions Are Created

When you call a capability decorated with @runtime.capability, Brane automatically creates the AgentAction from the runtime context and bound arguments. 
result = execute_sql("select * from customers")
You can also create actions manually for custom interception: 
action = runtime.create_action(
    capability_name="execute_sql",
    input={"query": "select * from customers"},
    action_type="database_query",
)
decision = runtime.evaluate_action(action)

​
Example Action

AgentAction(
    action_id="act_7f3a9b",
    trace_id="trace_abc123",
    action_type="tool_call",
    timestamp="2026-05-06T10:32:00Z",
    agent_id="support-agent",
    principal_id="user_sarah",
    tenant_id="tenant_acme",
    environment="prod",
    capability=Capability(name="refund_customer", type="tool", risk="high"),
    input={"customer_id": "cust_456", "amount_usd": 249.00},
)

​
Lifecycle

  1. Created before the before_capability policy stage
  2. Before decision when policy evaluates the action and returns a Decision
  3. Executed if allowed, when the function runs
  4. After record when a new AgentAction is created with output populated
  5. After decision when after_capability policy evaluates the output
  6. Returned or denied when output is returned or CapabilityDeniedError is raised
Audit events are planned at each lifecycle transition.

​
Fields

FieldTypeDescription
action_idstrUnique ID for this action. Auto-generated if not provided.
trace_id`strNone`Trace this action belongs to.
parent_action_id`strNone`Parent action ID for nested or delegated actions.
action_typestrWhat kind of action this is.
timestampstrISO 8601 timestamp when the action was created.
agent_id`strNone`Identity of the agent attempting the action.
principal_id`strNone`User or service the agent is acting on behalf of.
tenant_id`strNone`Tenant in a multi-tenant deployment.
environment`strNone`Runtime environment.
capabilityCapabilityThe capability being attempted.
inputdictBound input arguments for the capability call.
output`AnyNone`Output after execution. Populated in after-action records.
input_summary`strNone`Human-readable input summary for audit.
output_summary`strNone`Human-readable output summary for audit.
cost_so_far_usd`floatNone`Accumulated cost so far in the trace.
estimated_cost_usd`floatNone`Estimated cost for this action.
latency_so_far_ms`floatNone`Accumulated latency so far in the trace.
labelsdictArbitrary key-value labels for filtering.
metadatadictArbitrary metadata for policy use.

​
Computed Property

  • is_prod: True if environment == "prod". Exposed on PolicyContext as ctx.is_prod.

​
Action Types

TypeDescription
tool_callGeneric tool invocation
model_callLLM or embedding call
memory_readRead from agent memory
memory_writeWrite to agent memory
retrievalVector or semantic search
database_queryDatabase query
external_api_callExternal HTTP API call
mcp_tool_callMCP tool invocation
sandbox_executionCode execution in a sandbox
file_readFile read
file_writeFile write
secret_accessCredential or secret retrieval
agent_handoffHandoff to another agent
human_approvalHuman approval request

​
Identity Fields

The combination of agent_id, principal_id, and tenant_id answers the most important governance question: who is doing this, on behalf of whom, for which customer. Policy can check these via ctx.agent_id, ctx.principal_id, and ctx.tenant_id.

​
Trace Fields

trace_id links all actions in a single workflow run. parent_action_id links nested actions, for example when an agent spawns a subagent. These fields form the action tree that becomes the trace timeline in the dashboard.