> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> See the built-in agents, mention one with @name, and create, edit or delete your own custom agents

An **agent** is a named persona with its own system prompt, tools, skills and model settings. In [Agent mode](https://docs.oasm.io/ai-studio/chat.md), the main agent you talk to delegates focused jobs to these agents, which run in the background as **subagents**. OASM ships with built-in agents, and you can add custom ones.

Open the list from **Settings → Agents** in the AI Studio sidebar. The header reads "Built-in agents and custom agents you can mention with @name", and each card shows the display name, the `@name`, a scope badge (**Built in**, **Personal** or **Workspace**), the description and how many skills and tools the agent has.

![Agent settings with the Agents section selected, showing Total 14 items and cards for Asset analyst, Auto, Exploit verifier, Goal decomposition, Main agent, Network service tester, Penetration testing, Planner, Attack-surface recon and Report writer, each with a Built in badge and Skill and Tool counts](https://mintcdn.com/oasmplatform/JcAER2Ib37AN8_8A/images/screens/ai-agents.webp?fit=max\&auto=format\&n=JcAER2Ib37AN8_8A\&q=85\&s=8adaed6934c14b904798cf5a649cb966)

Settings → Agents lists the built-in agents first, then the custom agents you can see

## How agents are used

* **Agent mode only.** The main agent delegates only in Agent mode. In Ask mode it answers by itself and no agent is dispatched.
* **Which agents can be dispatched.** Every agent whose mode is **subagent** or **all**, built-in or custom, is offered to the main agent with its `@name`, display name and description. Agents in **primary** mode are listed in settings but are not offered for delegation.
* **@mentions.** To ask for a specific agent, name it in your message, for example `@recon map the attack surface of example.com`. The composer does not autocomplete names; the main agent reads the mention, matches it against the agents it can dispatch and sends that agent a brief. Each `@name` resolves to exactly one agent, because names are unique across built-in, workspace and personal agents.
* **Edits apply on the next run.** A subagent loads its agent definition when it starts, so changes you save apply to later dispatches. A queued subagent whose agent was deleted fails with an error.

See [Side panel](https://docs.oasm.io/ai-studio/side-panel.md) for how dispatched subagents appear while a chat runs.

## Built-in agents

Built-in agents ship with OASM and are read-only. Click a card to read its full system prompt.

| Agent | Mention | Mode | What it does | Skills it can load |
| - | - | - | - | - |
| **Asset analyst** | `@asset-analyst` | subagent | Reviews targets and assets (open ports, technologies, TLS, related vulnerabilities, statistics) and reports an exposure analysis of the requested scope | vulnerability-analysis |
| **Auto** | `@auto` | primary | Platform assistant for tasks, assets, skills, custom tools and MCP servers | vulnerability-analysis, web-research, command-execution, browser |
| **Exploit verifier** | `@exploit-verifier` | subagent | Confirms or rules out one candidate finding with the minimum safe proof and returns a verdict with evidence that can be replayed | exploit-verification, command-execution |
| **Goal decomposition** | `@goals` | subagent | Breaks a penetration-testing objective into independent, verifiable subgoals | none |
| **Main agent** | `@mainagent` | primary | Human interface that turns your intent into hints or high-priority intents | vulnerability-analysis, web-research, command-execution |
| **Network service tester** | `@network-tester` | subagent | Assesses the exposed non-web services of one host or range (TLS, SSH, mail, databases, caches, file shares, RPC, remote access) and returns each service with its version, misconfiguration and evidence | network-service-testing, command-execution |
| **Penetration testing** | `@pentest` | all | Runs an end-to-end penetration test of one objective, from reconnaissance to validation and wrap-up, with its own plan and evidence trail | reconnaissance, web-app-testing, exploit-verification, command-execution, browser |
| **Planner** | `@planner` | subagent | Reviews the situation and goals and adds exploration intents only for directions not yet covered | vulnerability-analysis |
| **Attack-surface recon** | `@recon` | subagent | Maps one target's attack surface (subdomains, DNS, live hosts, ports, services, technologies, TLS, endpoints, parameters, hidden content) and returns the inventory plus the entry points worth testing | reconnaissance, osint-and-assets, command-execution |
| **Report writer** | `@reporter` | subagent | Writes a penetration-test report from existing findings and evidence and returns it to the main agent to show in the chat | vulnerability-analysis, exploit-verification |
| **Vulnerability researcher** | `@researcher` | subagent | Researches vulnerabilities and open issues in the workspace (CVE details, affected assets, exploit availability, severity) and returns an evidence-backed summary | vulnerability-analysis, web-research |
| **Finding retest** | `@retester` | subagent | Re-checks one registered finding: reads the original evidence, re-runs the minimal proof and saves an independent retest conclusion | vulnerability-analysis, exploit-verification |
| **Web app & API tester** | `@webapp-tester` | subagent | Tests one web application or API for exploitable weaknesses (authentication, session, access control, injection, SSRF, business logic, file handling, API flaws) and returns candidates with evidence and a verdict for each | web-app-testing, api-testing, browser |
| **Worker** | `@worker` | subagent | Runs the named tools against the named target for one intent, writes back facts and findings, then stops | command-execution, browser |

When a multi-step task finishes and **Report writer** is available, the main agent dispatches it to produce the final report.

> [!NOTE]
>
> A built-in agent dispatched as a subagent runs the command and connector tools it declares without approval prompts, in Manual mode too, because the plan it serves was already approved. Built-in safety checks (the command deny list and the target scope check) still apply. A custom agent in a chat that is not in **Auto** mode gets read-only tools only. See [Plans and approvals](https://docs.oasm.io/ai-studio/plans-and-approvals.md).

## Create a custom agent

**1. Open the New Agent sheet**

In AI Studio, open **Settings → Agents** and click **New Agent** in the header. The **New Agent** sheet opens with the subtitle "Configure a new assistant persona".

**2. Fill in Identity & Role**

Set **Agent Name** and its scope, and optionally **Display Name** and **Description**. Pick a **Mode**: choose **subagent** or **all** if you want the main agent to be able to dispatch it.

**3. Set Model & Parameters (optional)**

Leave these empty to use your defaults, or set **Override Model**, **Thinking Variant**, **Temperature**, **Top P** and **Max steps**.

**4. Write the system prompt**

Under **System Prompt**, describe the agent's role, method and what it should hand back.

**5. Save**

Click **Create Agent**. The console confirms with "Agent created" and the new card appears in the list.

![New Agent sheet with the Identity and Role section (Agent Name new-agent with a user scope selector, Display Name, Description, Mode primary, subagent or all), the Model and Parameters section (Override Model Not selected, Thinking Variant default, Temperature, Top P and Max steps steppers), a System Prompt box and Cancel and Create Agent buttons](https://mintcdn.com/oasmplatform/JcAER2Ib37AN8_8A/images/screens/ai-agent-new.webp?fit=max\&auto=format\&n=JcAER2Ib37AN8_8A\&q=85\&s=7aa5802155dde30e7c44ffe4cca65f15)

The New Agent sheet

### Fields

| Field | Description | Limits and default |
| - | - | - |
| **Agent Name** | The slug you mention as `@name`. Uppercase letters are lowercased and spaces become dashes as you type | Lowercase letters, numbers and single dashes only, up to 64 characters. Starts as `new-agent`. Required |
| Scope (next to the name) | **user**: a personal agent only you can see. **workspace**: shared with every member of the workspace | Default **user**. Shown as **Personal** or **Workspace** on the card |
| **Display Name** | The name shown on the card and as the sheet title | Optional, up to 100 characters |
| **Description** | What the agent does. The main agent reads it when deciding whom to dispatch, so make it specific | Optional, up to 2,000 characters |
| **Mode** | **primary**: runs as the main agent. **subagent**: only delegated to by another agent. **all**: both | Default **primary**. Only **subagent** and **all** agents are offered for delegation |
| **Override Model** | The model this agent runs on, picked from your connected providers | Optional. **Not selected** uses your [Subagent Model](https://docs.oasm.io/ai-studio/settings/models.md), then the chat's model |
| **Thinking Variant** | Provider reasoning variant, such as `low`, `medium` or `high` | Optional, up to 50 characters. Empty uses the default |
| **Temperature** | Randomness of the answers | 0 to 2 in steps of 0.1. Empty uses the model default |
| **Top P** | Nucleus sampling | 0 to 1 in steps of 0.05. Empty uses the model default |
| **Max steps** | Maximum tool-call steps per run | 1 to 1,000. Empty uses your agent settings. The main agent can set a step budget for a single dispatch, which takes precedence |
| **System Prompt** | The agent's instructions | Up to 20,000 characters |

The console form has no tool or skill picker. A custom agent created in the console runs with the read-only workspace lookup tools and no skills. The agent definitions API (`/api/agents/definitions`) also accepts `tools` and `skills` lists in `metadata`.

> [!NOTE]
>
> **Override Model** points at one of your own provider connections. When another member's chat uses a workspace agent you created, your connection is not theirs, so the run falls back to the model of their chat. **Thinking Variant** is saved with the agent; in the current release subagent runs take their reasoning effort from the model connection rather than from this field.

### Naming rules

The console checks the pattern as you type and shows "Lowercase letters, numbers and single dashes only". The API also refuses a name that would make an `@mention` ambiguous:

* A built-in agent name is reserved: the save fails with `"@name" is a built-in agent`.
* A personal agent may not use the name of a workspace agent, and a workspace agent may not use a name any member already uses for a personal agent. The save fails with `Agent "@name" already exists`.
* Two of your own personal agents cannot share a name.

## Edit or delete a custom agent

**1. Open the agent**

In **Settings → Agents**, click the agent's card. The sheet title is the display name, or `@name` when there is none.

**2. Change the fields**

Edit any field, including the name and the scope. Changing the name or scope runs the same name checks as creating.

**3. Save or delete**

Click **Save Changes** ("Agent updated"). To remove the agent, click **Delete**, then confirm **Delete** in the **Delete Agent** dialog. Deleting cannot be undone.

You can only edit or delete agents you created. Opening any other agent shows a read-only sheet with a **Close** button:

* Built-in agents show "Built-in agent (read only)".
* Workspace agents created by another member show "Shared by another workspace member (read only)".

## Permissions

| Action | Requirement |
| - | - |
| List agents | `agent.read` |
| Create an agent | `agent.write` |
| Edit or delete an agent | `agent.write`, and you created the agent |

The list you see contains the built-in agents, every workspace agent and your own personal agents. Other members' personal agents are never shown to you. See [Permissions](https://docs.oasm.io/permissions.md).

## Related

> [card] [Skills](https://docs.oasm.io/ai-studio/settings/skills.md)
>
> The instruction sets agents load on demand

> [card] [Models](https://docs.oasm.io/ai-studio/settings/models.md)
>
> Default and subagent models

> [card] [Side panel](https://docs.oasm.io/ai-studio/side-panel.md)
>
> Follow subagents while they run

> [card] [Plans and approvals](https://docs.oasm.io/ai-studio/plans-and-approvals.md)
>
> What runs with and without your approval


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.