> ## 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.

# AgentAction

> An AgentAction is one attempted use of a capability.

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

## Definition

A [Capability](/concepts/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.

```python theme={null}
result = execute_sql("select * from customers")
```

You can also create actions manually for custom interception:

```python theme={null}
action = runtime.create_action(
    capability_name="execute_sql",
    input={"query": "select * from customers"},
    action_type="database_query",
)
decision = runtime.evaluate_action(action)
```

## Example Action

```python theme={null}
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

| 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.