> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aosplane.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aosplane.io/_mcp/server.

# Create and configure an agent

An agent is a saved setup for sessions: a coding agent, a model, standing instructions, how often it asks first, and an optional repository. You pick one each time you start a session.

> **Note**
>
> Owners, Admins and Engineers can create, edit and archive agents. Other roles can see them.

## Create an agent

#### Open the Agents tab

Open the project and choose the **Agents** tab, then **New agent**.

#### Name it and pick a coding agent

Enter a **Name**, then choose the **Coding agent**: **Claude Code**, **Codex**, **Kiro (preview)**, **Tower (preview)**, **Cursor (preview)** or **Antigravity (preview)**.

#### Choose the code and model

Pick a **Repository**, or **No repository**. Leave **Model** on **Default model**, pick one from the list, or choose **Custom model ID…**.

#### Write instructions

In **Instructions**, add what the agent should follow in every session, such as coding standards or how to test.

#### Set how it asks

Choose a **Permission mode** (see below), then choose **Create agent**.

![New agent panel with Name, Coding agent, Repository, Model, Instructions and Permission mode filled in, and the Create agent button](/_fern-files/_img/779de0d2c7794dbbf1e8290e5bd85a2c210040d4ba21cc8c9a23fe8fc5af01fa.webp)

## Choose a permission mode

| Mode                    | What the agent does                                             |
| ----------------------- | --------------------------------------------------------------- |
| **Ask first** (default) | Asks before protected actions.                                  |
| **Auto edits**          | Edits files without pausing.                                    |
| **Auto edits + shell**  | Also runs shell commands and searches and fetches from the web. |
| **Full access**         | Doesn't ask before editing files or running commands.           |

People can pick a different mode for one session when they start it.

## Edit or archive an agent

On the agent's row, choose **Edit**, change the settings, and choose **Save changes**. To retire it, choose **Archive**, then **Archive** in **Archive \{name}?**.

![Agents tab with a search box and a table of agents showing Name, Coding agent, Repository, Model and Status, with New session, Edit and Archive on each row](/_fern-files/_img/093bf8d9803902c8cfdd00878b3512751602049e6e889393b788d4e4c1ed1f19.webp)

## Good to know

* Edits apply to new sessions only. Running sessions keep the settings they started with.
* The repository is set when you create the agent. For another repository, create another agent.
* **New session** on a row opens the composer with that agent picked.
* Archiving hides the agent from new sessions and can't be undone. Its past sessions stay.
* A row that says **Relink required** needs GitHub access again: choose **Relink GitHub**. See [GitHub](/github).
* Claude Code agents also have **Thinking** (**Default**, **Adaptive** or **Off**) and **Default effort** in the edit form.

#### More settings

| Setting                 | What it does                                                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Default AI account**  | **Choose when a session starts**, or an organization AI account to always use. Personal accounts are picked at session start. See [Project AI accounts](/project-ai-accounts). |
| **Sandbox resources**   | **Plan default**, a size (Shrimp, Tuna, Shark or Whale), or **Custom** CPU and memory. Your plan decides which sizes you can use. See [Sandboxes](/sandboxes).                 |
| **Spend limit**         | **Limit this agent's spend** caps what its sessions spend. Only Owners and Admins can change it.                                                                               |
| **Session token limit** | Default token cap for new sessions: **None**, 500K, 1M, 2M or 5M. Not available for Kiro.                                                                                      |

## Related

* [Start a session](/start-a-session)
* [Tools](/tools)
* [Project AI accounts](/project-ai-accounts)