> For the complete documentation index, see [llms.txt](https://docs.robotmoney.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robotmoney.com/concepts/agents.md).

# Agents

Who can read, propose, and act. Internal and external.

This page is optional for headless integrations.

In RobotMoney, an **agent** is any non-human caller that proposes actions or requests decisions on a tenant's behalf. Agents and humans share the same policy and audit model. The credential differs by surface.

| Caller                          | Credential                                                     |
| ------------------------------- | -------------------------------------------------------------- |
| **Human owner**                 | Email and password, or a linked wallet                         |
| **Tenant headless agent**       | `brain_ak_...` key exchanged for a five-minute JWT             |
| **Internal service or backend** | Scoped service credential or tenant API key where enabled      |
| **MCP agent**                   | JWT anchored to an on-chain `BrainMCPAgentRegistry` scope hash |

All three hit the same endpoints, run through Policy, and land in the Audit log.

### Internal vs External

You can use RobotMoney in two ways: **build agents on top of it** or **let other people's agents in**.

| Pattern      | What it looks like                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------ |
| **Internal** | Your backend uses the SDK. Your code is the agent.                                               |
| **External** | Someone else's MCP-compatible agent connects to RobotMoney. The tenant authorizes it explicitly. |

Most apps start with internal agents. External agents become useful when:

* Your tenant wants to use a specialist agent (a vendor-management bot, a treasury agent) you didn't build
* You're building a marketplace where tenants pick agents
* You're integrating a third-party assistant that should see a tenant's financial state

### How Agents Act

Whether internal or external, the lifecycle is the same:

```
1. Read context (memory, citations)
2. Propose an action
3. RobotMoney runs Policy
4. If policy allows, the rail-specific hard floor decides whether it executes or routes to a human
5. Audit anchors what happened
```

An agent proposes; RobotMoney decides. Agents do not bypass Policy, and policy allow is still subject to the money-rail floor. `onchain_transfer`, `escrow_release`, and `wire` require recorded human approval before dispatch. `x402_settle`, ACH, and card can run autonomously only under signed policy caps that cover the action.

### What External Agents Can Do

Tenant-granted scopes determine what an external agent sees and can do.

| Scope                    | Allows                                                                   |
| ------------------------ | ------------------------------------------------------------------------ |
| `ledger:read`            | Read transactions, balances, counterparties, obligations                 |
| `wiki:read`              | Ask natural-language questions; get cited answers                        |
| `raw:write`              | Push artifacts (transcripts, contracts) into the tenant's evidence layer |
| `payment_intent:propose` | Propose PaymentIntents or request decision-only authorizations           |
| `execution:propose`      | Propose non-financial actions                                            |

A tenant can grant any subset. Unused scopes don't appear in the agent's available tools.

{% hint style="warning" %}
External agents only ever **propose** or **request a decision**; they never **execute**. A decision-only authorization returns `approved`, `needs_review`, or `blocked` for the customer's own rail and creates no PaymentIntent. Once a PaymentIntent action is eligible, RobotMoney's internal settlement path runs the section 6 gate and dispatches it. The proposing agent never moves the money itself, and a human approval is a recorded member approval, not a settlement call. That separation is the safety guarantee that makes agents safe to authorize.
{% endhint %}

### How External Agents Stay Accountable

Three properties combine to make external agents safe:

| Property       | Mechanism                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------- |
| **Identity**   | Agent registered in `BrainMCPAgentRegistry` on Base; signs every JWT with its registered key |
| **Scope**      | Tenant signs an EIP-712 message granting specific scopes; the hash is anchored on-chain      |
| **Revocation** | Tenant can revoke at any time; new calls fail within 60 seconds                              |

If an agent goes rogue, you turn it off. The audit log shows exactly what it did, when, and under whose authorization.

### How Internal Agents Stay Accountable

Same audit log, same Policy gating. Your server keys are scoped (you can issue narrow keys per service), and every call carries the key fingerprint. Compromised keys can be revoked, and the trail of what they did before revocation is recoverable.

### What "MCP-Compatible" Means

[MCP](https://modelcontextprotocol.io) is the open standard for connecting agents to tools and data sources. RobotMoney runs an MCP server at the canonical host `https://mcp.robotmoney.com` (which maps onto the internal `POST /v1/agents/mcp` route). Any agent built on an MCP-compatible runtime can connect.

You don't have to know any of this if you're only building internal agents. The MCP server matters when you want to **be a destination** for third-party agents.

[**→ MCP server**](/mcp-server/overview.md)

### Related

| Concept                            | Page             |
| ---------------------------------- | ---------------- |
| What agents read                   | Memory           |
| The rules that gate every action   | Policy           |
| The audit record of agent activity | Proof            |
| Deep dive                          | Protocol: Agents |