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. You do not need to create it manually in the normal flow.
# Brane creates the AgentAction automatically
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},
is_prod=True,
)Lifecycle
- Created — before the before_capability policy stage
- Before decision — policy evaluates the action and returns a Decision
- Executed — if allowed, the function runs
- After record — a new AgentAction is created with
outputpopulated - After decision — after_capability policy evaluates the output
- Returned or denied — output is returned or CapabilityDeniedError is raised
Audit events (planned) will be emitted at each lifecycle transition so every attempted action has a full record regardless of outcome.
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. Links actions across a workflow run. |
| parent_action_id | str | None | Parent action ID for nested or delegated actions. |
| action_type | str | What kind of action this is. See action types below. |
| 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: dev, staging, prod. |
| 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. Avoids storing raw secrets. |
| output_summary | str | None | Human-readable output summary for audit. |
| cost_so_far_usd | float | None | Accumulated cost so far in the current 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—Trueifenvironment == "prod". Exposed on PolicyContext asctx.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.
- agent_id: which agent system is acting (e.g.
support-agent,research-agent) - principal_id: which human or service the agent is acting for (e.g.
user_sarah) - tenant_id: which tenant in a multi-tenant SaaS context (e.g.
tenant_acme)
Policy can check any of 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 (planned).