# AI agents

An AI agent account: an agent with its own signing key on a dedicated account

An **agent account** is an [operating account](https://splits.org/docs/accounts#operating-accounts) whose signer set includes a signing key that the agent generated and holds itself. The agent never holds the human's seed phrase, private key, or passkey. The account's balance and its [threshold](https://splits.org/docs/accounts/thresholds) bound what the agent can reach. The account's owner, the Treasury, can remove the agent's key at any time.

## Why not share a key

A key copied to an agent has the human's full authority on every account that the key signs for. To revoke it, the human must rotate their own key on every account. A separate key on a separate account bounds both:

| Property | Shared human key | Agent's own key on an operating account |
| --- | --- | --- |
| Reach | Every account that the human signs for | One account's balance |
| Revocation | Rotate the human's key on every account | Owner rotates one signer set |
| Audit | Indistinguishable from the human | Every transaction recorded under the agent's key |
| Human co-signature | None | Threshold 2 or more requires one on every action |

## How it works

* **Each agent has a dedicated account.** The account holds only what the agent operates on. Under the [ownership chain](https://splits.org/docs/accounts), a leaked agent key reaches that account's contents and nothing else.
* **The threshold sets autonomy.** Threshold 1 lets the agent act alone within the account. Threshold 2 or more keeps a human co-signature on every transaction, in the app with a passkey.
* **Recovery is contract-enforced.** The Treasury owns the account, so the Treasury's signers can remove the agent's key by [resetting signers](https://splits.org/docs/accounts/editing#resetting-signers). The reset needs no signature from the account's own signers and does not change the account's address. Deposits and integrations that point at the address keep working.
* **Scopes bound the API, signers bound the chain.** The agent's API key carries a [scope](https://splits.org/docs/workspaces/roles#api-key-scopes) (Read, Write, or Owner). The scope governs what the agent can query and propose. Scopes grant **no onchain signing authority**. Only the agent's registered key on the account's signer set grants that authority.
* **Every action is a proposal.** The agent proposes [transactions](https://splits.org/docs/transactions) like any client. A transaction executes when its signatures meet the threshold. The agent proposes signer changes, and a human approves them in the app.
* **The agent is a member.** When you approve the agent's [browser login](https://splits.org/docs/introduction/agents#sign-in-from-the-browser), it joins the workspace as an [agent member](https://splits.org/docs/members#agent-members) with its own name and key. The workspace records its actions under its name, not yours.
* **The whole surface is available.** The CLI ships a built-in MCP server. An agent can do over the [CLI or MCP](https://splits.org/docs/introduction/agents) anything that a human can do in the app.

## Setting up an agent

Prerequisites: a [workspace](https://splits.org/docs/workspaces), and the CLI installed where the agent runs.

:::steps
### Sign the agent in

The agent starts a [browser login](https://splits.org/docs/introduction/agents#sign-in-from-the-browser) and gives you a code. A Splits login page opens. Sign in, enter the code, and connect the workspace with the [scopes](https://splits.org/docs/workspaces/roles#api-key-scopes) you choose. No API key passes through the agent. The agent then confirms the workspace, scopes, and key source.

### Use the agent's signing key

Use the EOA registered during browser approval and its signer ID for [headless signing](https://splits.org/docs/introduction/agents#sign-locally-with-an-eoa).

### Add the key to an account

Choose one:

* Add the agent's signer ID to an existing operating account. This creates a proposal that a human approves in the app.
* Create a new operating account with the agent's key and the human's passkey as signers from the start. This needs no approval step.

### Choose the threshold

Set threshold 1 for autonomous operation inside the account. Set threshold 2 or more to require the human on every transaction. You can change both later: see [Changing signers and thresholds](https://splits.org/docs/accounts/editing#changing-signers-and-thresholds).

### Fund and audit

Fund the account with what the agent operates on. The agent's transactions appear under its own key in the app, the CLI, and [accounting](https://splits.org/docs/accounting).
:::

## Budgets and top-ups

Give an agent a budget by giving it its own operating account (also called a subaccount). The balance is its spending limit.

* **People hold the Treasury.** An agent that signs in through the browser joins the workspace as a member. A member can read and propose, but a role never grants signing, and the agent has no key on the Treasury. Adding its key to an account needs an owner's approval.
* **The balance is the budget.** Create an operating account where the agent's key is the only signer, at threshold 1, and fund it with what the agent may spend. The agent can spend the whole balance, including in one payment, and nothing beyond it. Splits does not add per-payment limits or allowlists.
* **The agent asks for more.** An agent with **Write** scope can propose a transfer from the Treasury to its own account, with a memo that says what it is for. An owner approves it with a passkey. Money reaches the agent only because a person approved it.

## Limits

* **Per-signer restrictions by target contract or function do not exist onchain today.** A key that meets the threshold alone can take any action from its account, including changing the account's signer set. The bound is the account.
* Approval steps that happen only in the app (accepting a signer change, completing workspace setup) are platform policy.
* A person approves the agent's access in the browser. The exception is a [workspace the agent creates](https://splits.org/docs/workspaces#from-an-agent), which needs no approval.

## Next steps

* [Create a workspace](https://app.splits.org) and an operating account for the agent
* [Agents & API](https://splits.org/docs/introduction/agents): scopes, the proposal model, headless signing, output tuning
* [Personal usage](https://splits.org/docs/introduction/personal-usage#agents-as-collaborators): agents as collaborators on a team of one

## Programmatic access

Via the [Splits CLI / MCP](https://splits.org/docs/introduction/agents):

* `npx -y @splits/splits-cli@latest --llms-full`: the full command surface and MCP tool list, no install
* `splits auth login --client-name "<app name>"`: sign the agent in through your browser approval
* `splits workspace create --name "<name>" --client-name "<app name>"`: create a workspace for the agent, which you approve in the browser
* `splits auth whoami`: find the agent's registered EOA and `signerId` after browser login. Use `splits auth create-key --register` with **Read** and **Write** scopes if you authenticated with an API key
* `splits accounts update-signers <account> --add-eoa-signer-ids <id>`: propose adding only the agent's signing key, with no threshold change (**Write** scope for Member agents, **Write** and **Owner** scopes otherwise)
* `splits accounts create --name "<label>" --eoa-signer-ids <id> --passkey-ids <human-passkey-id> --threshold 2`: create the agent's account with both signers (**Owner** scope)
* `splits accounts create --name "<label>" --eoa-signer-ids <id> --threshold 1`: create a budget account where the agent is the only signer (**Owner** scope)
* `splits transactions sign <id>`: sign pending proposals with the agent's key (**Write** scope)
