# 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**                             | OAuth/SSO via the Console                 |
| **Internal agent** (your backend)     | Server API key                            |
| **External agent** (a third-party AI) | JWT, anchored to an on-chain registration |

All three call the same endpoints. All three are subject to Policy. All three land in Audit.

### 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 AI 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 allowed, the action executes (or routes to a human)
5. Audit anchors what happened
```

Agents propose. Brain decides. **Agents never bypass Policy.**

### 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)                                        |
| `agent: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 can **propose** but cannot **execute**. Execution is reserved for internal Brain workers running under tenant policy. This 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 AI agents to tools and data sources. Brain runs an MCP server at `mcp.brain.fi`. Any agent built on an MCP-compatible runtime (Anthropic's, OpenAI's via adapters, or open-source ones) 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.