# Your own actions

Govern an action your organisation defines, not only the built-in ones.

The built-in tools cover a few actions, such as a supplier's bank account. Your
organisation can register its own, such as `invoice.approve`, and your agent proposes
them through one general tool.

## Register the action

Someone with permission to manage capabilities registers it in the console. A
registration says:

| Part        | What it is                                                           |
| ----------- | -------------------------------------------------------------------- |
| Name        | A dotted lowercase name, such as `invoice.approve`                   |
| Fields      | The parameters, as a simple JSON Schema with types, limits and lists |
| Materiality | Which fields matter, so a change after approval is caught            |
| Sensitivity | Which fields are secret                                              |

A few names are reserved for built-in actions; registration tells you if yours is
one. Patterns must be simple and start with `^`, a field with a pattern needs a
maximum length, and an action can have at most 20 fields with a pattern, so one
request can't tie up the service.

A field marked secret is swapped for a token before anything is stored. Only the
token is kept and shown, so approvers and records never see the value. On an action
connected to a system, the value is sealed so that only the bridge can open it, just
before the call. See [Connect a system](/developers/connect-a-system#secret-fields).

## Propose it

Send `propose_action` through any way in, with the action's own fields in
`parameters`:

```json
{
  "request_id": "inv-approve-2291",
  "agent": { "agent_id": "<your agent id>", "session_id": "<your session>" },
  "tool": {
    "name": "propose_action",
    "arguments": {
      "action_type": "invoice.approve",
      "resource_type": "invoice",
      "resource_id": "INV-2291",
      "parameters": { "amount": "1200.00" },
      "reason": "Matches the purchase order"
    }
  },
  "context": {
    "instruction": "Approve invoice INV-2291.",
    "timestamp": "2026-11-02T10:00:00Z"
  }
}
```

An action nobody registered is refused before anything is stored, and so is a
parameter its registration doesn't list.

## What happens next

- The request is **held for a person** by default, unless your own policy says
  otherwise.
- It's **observed**: recorded with its decision, but never run, until your action
  is connected to a system. See [Connect a system](/developers/connect-a-system).
- Read the result as for any action. See [Wait for a result](/developers/results).

## Not yet

- Running your action against a real system: connecting is still in test.