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

# Agents

In Brain, an **agent** is any non-human caller that proposes or executes actions on a tenant's behalf. Agents and humans share the same authorization model. The only thing that differs is the credential.

| Caller                                    | Credential                                      |
| ----------------------------------------- | ----------------------------------------------- |
| **Human**                                 | Email + password, or a linked wallet (SIWX)     |
| **Internal agent** (your backend)         | Server API key (the `brain_sk_…` service token) |
| **External agent** (third-party software) | JWT, anchored to an on-chain registration       |

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

### Internal vs External

You can use Brain 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 Brain. 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. Brain 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; Brain 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 payments (cannot execute)                                        |
| `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**; they never **execute**. Once an action is eligible (Policy returned `allow` and the rail permits autonomy, or all required human approvals are in), Brain's internal settlement path runs the §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 external 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. Brain runs an MCP server at the canonical host `https://mcp.brain.fi` (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 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.brain.fi/concepts/agents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.