# Create an agent

> Create an agent with the Agent Builder, then set its prompt fields, model, reply language and resources yourself on its tabs.

After this page you can create an agent without Orca, fill in what it is and how it behaves, choose its model and reply language, and give it what it needs to work.

## Two ways to start

| You have | Use |
|---|---|
| A skill, a spec or an MCP server, and you want the agent and everything it needs built in one go | [Orca](https://docs4.mindset.ai/docs/ams/turn-a-skill-or-spec-into-an-agent) |
| An idea of the agent, and connections, functions or widgets that already exist or that you'll build yourself | **Agents → + New agent**, on this page |

There is no form for a new agent. **+ New agent** opens a **New agent** dialog with the **Agent Builder** in it, and you describe the agent in a conversation. Once the builder has created it, the dialog's button turns into **Open agent →**. Closing the dialog never deletes an agent the builder created.

After that, every part of the agent is on its tabs, and you can edit each part by hand or ask the Agent Builder docked on the left.

## Create the invoice exceptions agent

1. Go to **Agents** and press **+ New agent**.
2. Tell the Agent Builder what the agent is for, for example: "An agent for the finance team that checks an invoice against its purchase order and, when they differ, checks the supplier contract and registers a supplier query."
3. When it has created the agent, press **Open agent →**.
4. Read and adjust the **System Prompt** and **Settings** tabs (below).
5. Add what it can use on the **Resources** tab.
6. Press **Save as version**. Nothing reaches anyone yet.
7. Try it on the **Chat** tab, then activate the version and make the agent available on the **Versions & Availability** tab. See [Agent versions](https://docs4.mindset.ai/docs/ams/agent-versions) and [Where your agent can be reached](https://docs4.mindset.ai/docs/ams/where-your-agent-can-be-reached).

A new agent starts unavailable. It answers nobody but org admins until someone switches it on.

## Write the prompt

The prompt is on the **System Prompt** tab. Its **Agent configuration** card holds what you write. **Your name** and **Your purpose** are shown here and edited on Settings. The other four fields are edited here:

| Field | What goes in it |
|---|---|
| **Personality** | The agent's identity and behavior. The main free text of the prompt |
| **Background** | Domain background and audience context. The agent's catalog description is separate and never enters the prompt |
| **Policy rules** | Rules the agent must obey. These are instructions to the model, not something Mindset enforces |
| **Output formatting** | How replies should be shaped. Mindset's default formatting guidance starts in this field, so the fields are the whole authored prompt |

Each field, and **Purpose**, holds at most **2,000 characters**, and a counter shows how much you've used. Mindset refuses to save a wording over the limit. Each field also has a history icon that brings back earlier wordings.

Below it, **Added by the platform** shows what Mindset appends on every run: the reply language, and situational awareness added at run time from the page the agent runs on. **Assembled preview** shows the whole prompt the agent receives.

For the invoice agent, keep the prompt to what applies all the time. The order of work (gather, assess, prepare, close) belongs in a [script](https://docs4.mindset.ai/docs/ams/write-a-script), because the agent must not skip ahead.

## The Settings tab

The **Configuration** card:

| Field | What it does |
|---|---|
| **Name** | What the agent is called, and the name it gives itself in conversation |
| **Purpose** | What the agent is for, in a sentence or two. Up to 2,000 characters |
| **Model** | The model the agent runs on. Only models your org has a provider key for are listed. Picking one that isn't served is refused rather than quietly swapped for another. See [Use your own model provider keys](https://docs4.mindset.ai/docs/ams/use-your-own-model-provider-keys) |
| **Reply language** | **Inherit**, which follows your org's language, or **A specific language**, which you name the way you'd say it to a person, such as "Spanish" |

Every change here is saved as a new version and goes live when you activate it.

**Delete agent** sits in its own card below. The agent stops answering anyone. Its history is kept for audit, and an admin can't bring the agent back.

### Reply language and the org default

The agent's own language wins. When the agent is set to **Inherit**, it follows the org's language, and changes when the org's language changes. When neither is set, Mindset's default applies. A version records the language it was saved with, so activating an older version brings back its language too.

The language is an instruction to the model. Mindset doesn't check that replies are in it.

## The Resources tab

**Resources** has one card per kind of thing the agent can use, each with **Add**:

| Card | What it gives the agent |
|---|---|
| **Connections** | Operations it can call on a connected system. See [Connect a system](https://docs4.mindset.ai/docs/ams/connect-a-system) |
| **Widgets** | Widgets it can show in a conversation. See [Build a widget](https://docs4.mindset.ai/docs/ams/build-a-widget) |
| **Functions** | Functions it can run. See [Build a function](https://docs4.mindset.ai/docs/ams/build-a-function) |
| **Agents (A2A)** | Other agents it can hand a task to. See [Teams of agents](https://docs4.mindset.ai/docs/ams/teams-of-agents) |

For the invoice agent, add the finance system's `get_invoice`, `get_purchase_order_for_invoice` and `register_supplier_query` operations, the supplier contracts knowledge base, and the `invoice-comparison` function. A write such as `register_supplier_query` also needs its approval. See [Approve what an agent can do](https://docs4.mindset.ai/docs/ams/approve-what-an-agent-can-do).

Resources are part of the version. Adding or removing one is an unsaved change until you save, and it reaches people when you activate.

## What the Agent Builder can and can't do

The Agent Builder works on the agent you have open. In the **New agent** dialog it can only create an agent, list agents, read one, and change the agent it just created.

On an agent's page it can:

- Change the name, the five prompt fields, the model and which script the agent runs.
- Add and remove resources: operations, widgets, functions and other agents that already exist.
- Read and restore the agent's earlier versions, and explain what differs between two of them.
- Write or change the script, by handing the work to the Script Builder.
- Set schedules, and read the agent's triggers and their run history.
- Create and run [behavior tests](https://docs4.mindset.ai/docs/ams/test-an-agents-behavior).
- Make the agent available when you ask it to. It never opens **The Hub**, **Embedded in your own product** or **Outside systems** on its own.
- Archive or delete the agent.

Every change it makes to the prompt fields, model or script either activates the new version or leaves it staged. It must choose one each time, and it tells you which.

It can't:

- Connect a system. Use the Connection Builder on **Connections**.
- Build a function or a widget. Use the Function Builder on **Functions** or the Widget Builder on **Widgets**. Orca can build all of these for you.
- Approve a write operation. No agent can.

## What can go wrong

- **The model you want isn't in the list.** Only models your org has a provider key for are listed. Add the key first.
- **Save is refused.** A prompt field is over 2,000 characters. Shorten it, or move the order of work into a script.
- **The agent says it can't do something you gave it.** The version with that resource isn't active yet. Activate it on **Versions & Availability**.
- **Nobody can reach the agent.** A new agent starts unavailable. Switch it on and choose where people reach it.

## You're done when

- The agent has a purpose, a personality and the policy rules it must follow, each within 2,000 characters.
- You chose its model and checked whether it inherits the org's reply language.
- Its resources are the smallest set it needs.
- You saved a version, tried it on the **Chat** tab and activated it.