AgentAction

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

Created before the before_capability policy stage
Before decision when policy evaluates the action and returns a Decision
Executed if allowed, when the function runs
After record when a new AgentAction is created with output populated
After decision when after_capability policy evaluates the output
Returned or denied when output is returned or CapabilityDeniedError is raised

Audit events are planned at each lifecycle transition.

Fields

Field	Type	Description
`action_id`	`str`	Unique ID for this action. Auto-generated if not provided.
`trace_id`	`str	None`	Trace this action belongs to.
`parent_action_id`	`str	None`	Parent action ID for nested or delegated actions.
`action_type`	`str`	What kind of action this is.
`timestamp`	`str`	ISO 8601 timestamp when the action was created.
`agent_id`	`str	None`	Identity of the agent attempting the action.
`principal_id`	`str	None`	User or service the agent is acting on behalf of.
`tenant_id`	`str	None`	Tenant in a multi-tenant deployment.
`environment`	`str	None`	Runtime environment.
`capability`	`Capability`	The capability being attempted.
`input`	`dict`	Bound input arguments for the capability call.
`output`	`Any	None`	Output after execution. Populated in after-action records.
`input_summary`	`str	None`	Human-readable input summary for audit.
`output_summary`	`str	None`	Human-readable output summary for audit.
`cost_so_far_usd`	`float	None`	Accumulated cost so far in the trace.
`estimated_cost_usd`	`float	None`	Estimated cost for this action.
`latency_so_far_ms`	`float	None`	Accumulated latency so far in the trace.
`labels`	`dict`	Arbitrary key-value labels for filtering.
`metadata`	`dict`	Arbitrary metadata for policy use.

Computed Property

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

Action Types

Type	Description
`tool_call`	Generic tool invocation
`model_call`	LLM or embedding call
`memory_read`	Read from agent memory
`memory_write`	Write to agent memory
`retrieval`	Vector or semantic search
`database_query`	Database query
`external_api_call`	External HTTP API call
`mcp_tool_call`	MCP tool invocation
`sandbox_execution`	Code execution in a sandbox
`file_read`	File read
`file_write`	File write
`secret_access`	Credential or secret retrieval
`agent_handoff`	Handoff to another agent
`human_approval`	Human 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.

Start Here

Core Model

Answer Guides

Build With Python

Recipes

Reference

Definition

How Actions Are Created

Example Action

Lifecycle

Fields

Computed Property

Action Types

Identity Fields

Trace Fields

​Definition

​How Actions Are Created

​Example Action

​Lifecycle

​Fields

​Computed Property

​Action Types

​Identity Fields

​Trace Fields

Definition

How Actions Are Created

Example Action

Lifecycle

Fields

Computed Property

Action Types

Identity Fields

Trace Fields