# Agents

Source: https://docs.settlemint.com/docs/console/participants/agents
Create software agents that act for the organisation inside a mandate the chain enforces, change or revoke a mandate, and halt every agent at once.

An agent is software that acts for the organisation without a person approving each step. A payout run for coupons and dividends is one example. Each agent acts inside a mandate that the chain enforces: the contracts and functions it may call, the most it may move of each metered asset in one transaction and in one period, and the date the mandate ends. The agent signs with a managed custody key that the platform holds, and only an organisation owner creates agents and changes their mandates. A mandate does not restrict recipients, and its ceilings meter only `transfer`, `transferFrom` and `approve` on the assets it lists. [Agents and mandates](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandates) explains what the chain refuses and how the starter mandate is set.

Each row on the list is one agent. The list opens with the newest agent first, shows 20 agents per page, and refreshes on its own while an agent reads **Setting up**. "Search agents" filters it. Opening a row opens the agent's page, where the owner reads the mandate and the limits used this period, replaces the mandate, manages the roles of the agent's account or revokes the agent. The foot of the list holds "Halt all agents", the organisation's kill switch, which revokes every agent at once.

![The Agents page before any agent exists, with the Create agent button, No agents yet and the Halt all agents control](https://docs.settlemint.com/docs/screenshots/console-agents.light.en.webp)

[Screenshot] The "Agents" page before any agent exists, with "Create agent" in the header.

The page describes itself as "Agents act for your organisation inside a mandate that the chain enforces. Only owners create agents and change mandates." With no agent, it reads "No agents yet" and "Create an agent to let software run coupon and dividend payouts within limits you set." The "Halt all agents" control sits below. Once an agent exists, the table, searched with "Search agents", shows "Name", "Status", "Account", "Created" and "Revoked".

## Before you start [#before-you-start]

- **Your wallet verification.** Creating an agent, replacing a mandate, revoking an agent and halting or resuming all agents each ask for your wallet verification before the change is sent.
- **The halt is off.** While all agents are halted, "Create agent" is unavailable and the page says "Turn off the halt to create agents." [Halt all agents](#halt-all-agents) shows how to turn it off.
- **The mandate you want.** Decide which contracts and functions the agent needs, which assets it may move, the ceiling for one transaction and for one period, and the date it should stop. The sheet starts from a starter mandate for coupon and dividend payouts that you review and change.
- **A reason, for revoking and halting.** Revoking an agent and halting all agents are final for the agents they stop, and both ask for a reason of up to 500 characters. To stop one agent, revoke that agent instead of halting all of them.

## Steps [#steps]

### Open the Create agent sheet [#open-the-create-agent-sheet]

Select **Create agent**. The sheet opens with an "Agent name" field and the starter mandate the platform proposes. While the proposal loads, the mandate area shows a placeholder. Reading the proposal creates nothing.

### Name the agent [#name-the-agent]

Enter the **Agent name**, up to 120 characters. The sheet shows "Enter a name for the agent." until you do.

### Review the mandate [#review-the-mandate]

The mandate editor holds four settings. Change what the agent should not get, and add what it needs.

1. **Expires** sets the date and time the mandate ends. It must be in the future.
2. **Ceiling period** is the window the per-period ceilings count over. Choose "1 hour", "1 day" or "7 days". When you edit a mandate whose period is none of these three, the list shows its period as a fourth choice.
3. **Allowed contracts and functions** lists each contract the agent may call and, under it, the functions it may use there. The editor names the known functions, such as "Fund coupon payments", "Pay a coupon to a holder", "Declare a dividend", "Pay a dividend to a holder", "Approve spending of an asset" and "Transfer an asset", each with its own add button.

   To add a function the editor does not name, enter its 4-byte selector in "Function selector", such as `0x12345678`, and select "Add function". Select "Add contract" and enter a "Contract address" to allow another contract. Every contract needs at least one function, and the Console says "Choose at least one function for this contract." when one has none. Remove a contract with "Remove this contract".

4. **Ceilings per asset** lists each asset the agent may move. Select "Add asset", enter the "Asset address", and set the "Ceiling per transaction" and the "Ceiling per period". Both fields take the amount in your own number format, group it when you leave the field, and accept a `k`, `m` or `b` suffix such as `1.5k`. Every asset needs both ceilings.

   A ceiling limits only `transfer`, `transferFrom` and `approve` on that asset. Another function the mandate allows, such as a mint or a payout call, counts against no ceiling, so allow only the functions the agent needs.

Under the editor the footer names the first thing that blocks you, such as "Set an expiry in the future.", "Add at least one contract." or "List each contract once."

### Confirm and create [#confirm-and-create]

Continue to the confirmation, which reads "Create this agent with this mandate" and summarises the "Agent name", "Expires", "Ceiling period", the number of allowed contracts and the number of assets. Select **Create agent** and confirm with your wallet verification. The Console shows "Agent created" and opens the agent's page. A new agent reads "Setting up" until its account exists on the chain, and "Active" after that.

## Open an agent [#open-an-agent]

Select a row to open the agent's page. It has two tabs, **Overview** and "Activity log", and a status badge beside the name.

The **Overview** tab shows these cards:

- **Identity** with "Status", "Account", "Signer", "Mandate owner", "Identity", "Created" and, for a revoked agent, "Revoked" and "Revoked by". "Revoked by" reads "The kill switch of this agent" or "The kill switch of the organisation".
- **Mandate** with "Expires", "Ceiling period" and "Allowed contracts and functions". A mandate with no contract reads "The agent may not call any contract."
- **Limits this period** with, for each asset, how much the agent has used of its ceiling for the period, and its "Ceiling per transaction". When the mandate sets no asset or native ceilings, the card reads "The mandate sets no asset or native ceilings. Ceilings meter only transfers, approvals and native value. A ceiling does not meter any other call the mandate allows." The card means nothing is metered: the agent can still make every call the mandate allows.

An active agent's header also has **Manage roles** when the agent has an account and your account may grant roles. It opens the roles sheet with the agent's account already chosen. A role you grant that account lets the agent call that role's functions on any contract the mandate lists, and no ceiling meters those calls.

A notice at the top of the **Overview** tab explains an agent that is not active: "The agent is being set up", "Setting up the agent failed" or "This agent is revoked". When the chain does not answer, the page says "The mandate could not be read from the chain. Try again in a moment."

## Edit a mandate [#edit-a-mandate]

Select **Edit mandate** in the header of an active agent. The sheet reads "Replace the mandate of" the agent's name and "The new mandate applies as soon as the change lands on the chain." It holds the same editor as the create sheet, filled with the current mandate. Change it, continue to the confirmation, select "Replace mandate" and confirm with your wallet verification. The Console shows "Mandate replaced".

The new mandate replaces the old one entirely: it drops the previous allowed calls, asset rules and counters, and starts a new period count. You can replace the mandate of an active agent only.

## Revoke an agent [#revoke-an-agent]

On the "Overview" tab of an active agent, the danger row "Revoke agent" ends the agent's mandate for good. Select **Revoke agent**, enter the "Reason", and confirm with your wallet verification, or select "Keep agent" to stop. The sheet says the agent stops at once, and that revoking is final: the agent can never act again, and the only way to grant new limits is to create a new agent. The Console shows the agent's name followed by "revoked", and the agent reads "Revoked".

## Halt all agents [#halt-all-agents]

Halting is not a pause. The halt revokes every agent of the organisation that is not already revoked, and cancels each agent's transactions that are still waiting in the queue. An agent the halt revokes stays revoked after you turn the halt off, so you create each agent again with a new mandate.

To halt, select the danger row **Halt all agents** below the list, enter the "Reason", and confirm with your wallet verification, or select "Keep agents running" to stop.

While the halt is on, a banner reads "All agents are halted", with your reason and "Halted on" followed by the date, and the danger row shows "Turn off halt" instead. Select **Turn off halt**, enter the "Reason", and confirm, or select "Keep halt on" to stop. Turning the halt off lets the organisation create agents again.

## Agent statuses [#agent-statuses]

| Status | What it means |
| --- | --- |
| **Setting up** | The agent's account is being created on the chain. The page updates when the agent is ready. |
| **Active** | The mandate is on the chain and the agent can act within it. |
| **Revoked** | An owner revoked this agent, or the halt revoked it. This is final. |
| **Failed** | The agent never became active. Create a new agent to try again. |

## You should see [#you-should-see]

- After you create an agent, its page shows the badge **Active**, and "Mandate" and "Limits this period" show the expiry, the allowed contracts and the ceilings you set.
- After you replace a mandate, the **Mandate** card shows the new values and the used amount in "Limits this period" starts again.
- After you revoke an agent, its badge reads **Revoked**, "Revoked by" reads "The kill switch of this agent", and "Edit mandate" and "Manage roles" are gone.
- After a halt, every live agent reads **Revoked** with "The kill switch of the organisation" and the banner "All agents are halted" shows on the list.

## Troubleshooting [#troubleshooting]

**“Create agent” is unavailable**

All agents are halted, and the page says "Turn off the halt to create agents." Select **Turn off halt** and confirm.
Through the Platform API, a creation while the halt is on fails with `DALP-199552`.

**The sheet does not continue**

The footer names the first problem with the mandate or the name. The Console stops an empty contract list, a contract
without a function and an asset without both ceilings. Through the Platform API, `DALP-199554` refuses an expiry that
is not in the future, a contract, asset or function listed twice, a `transfer`, `transferFrom` or `approve` on a
contract that has no asset ceiling, and any other function on an asset that has one. `data.rule` names the rule. This
is a caller error, and sending the same mandate fails again.

**An agent stays on “Setting up”**

The agent's account is still being created on the chain, and the page updates by itself. If the agent then reads
**Failed**, it never became active. Create a new agent with the same mandate.

**The mandate could not be read from the chain**

The agent is active but the chain read did not answer. Reload the page in a moment. The mandate and the limits show
again once the read succeeds.

**“Edit mandate” or “Manage roles” is missing**

Both show only on an active agent. A revoked agent, an agent that is still being set up and a failed agent have no
header actions, and the platform refuses a change to them with `DALP-199553`. **Manage roles** also needs an account
on the agent and your permission to grant roles.

**“Agents” is missing from the sidebar**

Only an organisation owner opens the page, and the platform refuses every agent route for anyone else with
`DALP-199555`. Ask an owner to make the change.

## API routes [#api-routes]

The Platform API serves the same actions under `/api/v2/agents`, and every route is owner only. `GET /api/v2/agents` lists the agents and `POST /api/v2/agents` creates one. `GET /api/v2/agents/mandate-proposal` returns the starter mandate the sheet starts from. `GET /api/v2/agents/{agentId}` reads one agent with its mandate and usage, `PUT /api/v2/agents/{agentId}/mandate` replaces the mandate, and `POST /api/v2/agents/{agentId}/revocation` revokes the agent. `GET /api/v2/agents/kill-switch` reads the halt and `PUT /api/v2/agents/kill-switch` turns it on or off. See the [API reference](https://docs.settlemint.com/docs/api-reference/v2) for the schemas.