> ## 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.

# AI Studio overview

> Ask questions about your attack surface in plain language, or hand the AI agent a security task that it plans, runs on your workers and reports back on

AI Studio is the AI assistant built into the OASM console. You use it in two ways:

* **Ask** a question about your workspace, such as "Which open ports look risky?", and get an answer built from your assets, vulnerabilities and other workspace data.
* **Hand the agent a task**, such as "Map the attack surface of this domain and report what is exposed". The agent writes a plan, waits for your approval, runs security tools on your [workers](https://docs.oasm.io/worker.md) and reports what it found.

AI Studio runs on the AI model you connect. Each member connects their own provider and API key and has their own settings. Conversations are private to the member who created them.

## When to use AI Studio

| Use AI Studio to | Example |
| - | - |
| Get a quick answer from workspace data | "Show my critical and high vulnerabilities and how to fix them" |
| Triage and prioritize what you already know | "Group the open findings in this project by host and rank them by exploitability" |
| Run multi-step recon or testing | "Enumerate the web services on these targets and check their security headers" |
| Investigate one asset or finding in depth | "Check whether the Confluence instance on wiki.example.com is exploitable" |
| Produce a written summary | "Write a one-page exposure report for the CISO" |

For scheduled, repeatable scanning, use [projects](https://docs.oasm.io/project.md) and [workflows](https://docs.oasm.io/workflows.md) instead. The agent can help you build those too.

## Where it lives in the console

Open **AI Studio** in the main sidebar (route `/aistudio`). AI Studio replaces the main sidebar with its own:

| Item | What it opens |
| - | - |
| **New Chat** | A new conversation. See [Chat](https://docs.oasm.io/ai-studio/chat.md) |
| **Usage** | Tokens, cost and sessions you used. See [Usage](https://docs.oasm.io/ai-studio/usage.md) |
| **Connectors** | The tools the agent can use. See [Connectors](https://docs.oasm.io/ai-studio/connectors.md) |
| **Settings** | The agent settings dialog: Providers, Models, Agents, Web Search, Instruction, Skills and Memory |
| **Projects** | Your projects. Picking one starts a chat locked to it. See [Project chats](https://docs.oasm.io/ai-studio/project-chats.md) |
| **Chats** | Your recent conversations, with rename and delete |

![AI Studio with its own sidebar (New Chat, Usage, Connectors, Settings, Projects and Chats) and a new chat composer set to a project, Auto (any worker), the Agent button active and Manual approval, above the External recon, Ports & services and Web app pentest prompt groups](https://mintcdn.com/oasmplatform/JcAER2Ib37AN8_8A/images/screens/ai-compose.webp?fit=max\&auto=format\&n=JcAER2Ib37AN8_8A\&q=85\&s=db3dd620e451ce2804f292d4be0a3c63)

A new chat in Agent mode, scoped to a project, with the starter prompt groups below the composer

## Ask and Agent at a glance

The **Agent** button in the composer switches a chat between the two modes. A new chat starts in Ask mode.

| | Ask | Agent |
| - | - | - |
| **Purpose** | Quick answers | Multi-step work that runs tools |
| **What the agent can use** | Workspace data and public web pages | Workspace data, plus commands, tool connectors and a headless browser on a worker |
| **Plan before work** | Never | For any task larger than one tool call |
| **Needs a worker** | No | Yes, at least one online worker |
| **Approvals** | None | Plan approval, and command approval in **Manual** mode |

See [Chat](https://docs.oasm.io/ai-studio/chat.md) for the composer, modes, starter prompts and conversations.

## How an agent task flows

**1. You ask**

You describe the outcome you want in Agent mode, optionally in a [project chat](https://docs.oasm.io/ai-studio/project-chats.md) so the agent stays inside that project. In Agent mode no tool runs until a plan is approved, so use [Ask mode](https://docs.oasm.io/ai-studio/chat.md) for a quick lookup.

**2. The agent plans**

For anything larger, the agent writes a **plan**: an ordered list of outcomes. No work tool runs before the plan is approved.

**3. You approve**

The **Run this plan?** prompt replaces the composer. Approve it to run commands automatically or to approve each command, reject it, or tell the agent how to change it. See [Plans and approvals](https://docs.oasm.io/ai-studio/plans-and-approvals.md).

**4. Subagents do the work**

The main agent dispatches **subagents** for the hands-on jobs, several at once when they are independent. Commands run on a [worker](https://docs.oasm.io/worker.md), never on the OASM API host. Follow the run in the [side panel](https://docs.oasm.io/ai-studio/side-panel.md).

**5. You get the answer**

The agent writes its answer in the chat. Findings it can back with evidence are recorded as **proposals** that wait for a reviewer under **Pending review (AI)** on the [Vulnerabilities](https://docs.oasm.io/vulnerability.md#ai-proposals-and-review) page; they do not count as findings until someone approves them.

![A conversation showing a five-step plan marked Plan ready, a Dispatch Subagent call and the final summary, next to the side panel Subagents tab listing three completed asset-analyst subagents with their run times](https://mintcdn.com/oasmplatform/JcAER2Ib37AN8_8A/images/screens/ai-subagents.webp?fit=max\&auto=format\&n=JcAER2Ib37AN8_8A\&q=85\&s=c33a9030c5c021d1e9a1ab640a5ba4fa)

Three subagents dispatched in parallel, with the plan and the final answer

A run lives on the server. Closing the tab does not stop it; only the **Stop** button does.

![A completed Agent mode answer with a four-step plan, a Transition Step group of 46 tool calls and a summary of findings ranked by exploitability, next to the side panel Stats tab](https://mintcdn.com/oasmplatform/JcAER2Ib37AN8_8A/images/screens/ai-answer.webp?fit=max\&auto=format\&n=JcAER2Ib37AN8_8A\&q=85\&s=fb5b93c5009f5b50de3d99b4c81aca0b)

A finished answer, with the approved plan, grouped tool calls and turn stats

## Get started

**1. Connect a model**

In AI Studio, click **Settings**, then **Connect** next to a provider, and enter your API key. Your first connection becomes your default model. See [Connect a model](https://docs.oasm.io/ai-studio/connect-a-model.md).

**2. Connect a worker for Agent mode**

Ask mode works without a worker. Agent mode needs at least one online worker; if none is connected, the **Agent** button opens the connect-worker dialog. See [Workers](https://docs.oasm.io/worker.md).

**3. Ask your first question**

Click **New Chat**, pick a starter prompt under **Overview**, **Attack surface** or **Vulnerabilities**, or type a question and press Enter.

**4. Run your first agent task**

Click **Agent**, leave the worker on **Auto (any worker)**, and keep the approval mode on **Manual**. Describe the task, review the plan in **Run this plan?**, then approve it and answer each command prompt.

## Key concepts

| Concept | What it is |
| - | - |
| **Provider** | The AI service that runs your conversations, such as OpenAI, Anthropic or your own OpenAI-compatible endpoint. You connect it with your own API key. See [Connect a model](https://docs.oasm.io/ai-studio/connect-a-model.md) |
| **Model** | The model of a connected provider that answers. You set a default and can switch it from the composer. See [Models](https://docs.oasm.io/ai-studio/settings/models.md) |
| **Agent** | A role with its own instructions and tools, such as the main agent or an asset analyst. OASM ships built-in agents, and you can create custom ones that you mention as `@name`. See [Agents](https://docs.oasm.io/ai-studio/settings/agents.md) |
| **Subagent** | An agent the main agent dispatches in the background for one focused job. It runs unattended, so a call that would need your approval is refused instead of waiting |
| **Skill** | Specialized instructions the agent loads on demand when a task calls for them. See [Skills](https://docs.oasm.io/ai-studio/settings/skills.md) |
| **Connector** | A tool the agent can run, such as a scanner installed in the workspace. See [Connectors](https://docs.oasm.io/ai-studio/connectors.md) |
| **Plan** | The ordered outcomes the agent proposes for a multi-step task in Agent mode. You approve it before work starts |
| **Approval mode** | **Manual** asks before each new command; **Auto** runs commands without asking. See [Plans and approvals](https://docs.oasm.io/ai-studio/plans-and-approvals.md) |
| **Project chat** | A conversation locked to one [project](https://docs.oasm.io/project.md): the agent only reads and acts inside it. See [Project chats](https://docs.oasm.io/ai-studio/project-chats.md) |

## Permissions

| Permission | What it allows in AI Studio |
| - | - |
| `agent.read` | Open AI Studio, chat, read your conversations and subagent transcripts, and view Usage |
| `agent.write` | Connect, change and disconnect providers; change agent settings; stop a run; answer plan and command approvals; rename and delete conversations |

Some settings need more than `agent.write`: workspace skills can be changed only by the workspace owner, and a custom agent can be edited only by the member who created it. See [Permissions](https://docs.oasm.io/permissions.md).

> [!NOTE]
>
> Provider connections are per member, and connecting one needs `agent.write`. A member who has only `agent.read` cannot connect a provider, so they cannot start chatting until someone grants `agent.write` or they get it through their permission group.

The agent acts with **your** permissions. Each built-in tool checks the same permission as the console page that shows that data, at the moment the agent calls it. For example, the agent can propose findings only if you have `vulnerability.write`.

## Security and data handling

AI Studio is part of your OASM deployment. Conversations, plans, settings and memories are stored in your OASM database.

* **What leaves your deployment.** OASM sends each model request to the provider you connected. A request carries the conversation and the workspace data the agent read to answer it. Choose a provider whose data handling fits your policy, or point the custom provider at your own OpenAI-compatible endpoint.
* **API keys.** Provider and web search keys are encrypted with your workspace's encryption key and only ever shown masked. Your provider key is never shared with other members.
* **Commands run on workers.** Agent-mode commands, tool connectors and the headless browser run on your [workers](https://docs.oasm.io/worker.md), never on the OASM API host.
* **Checks before every approval.** In both approval modes, built-in safety checks run before the agent may call a tool:
  * Shell commands and external MCP tool calls that match a built-in deny list are refused.
  * Workspace tool rules, managed by the workspace owner through the `/api/agents/tool-rules` endpoints, can deny a call, allow it without a prompt, or force an approval prompt.
  * A scope gate keeps work on your targets. Tool connector targets and subagent targets outside the scope are refused. Hosts outside the scope that appear in a shell command trigger an approval prompt, and excluded hosts are always refused. In a project chat, the scope is the project's scope rules; otherwise it is the workspace's domain, IP and CIDR targets.
* **You stay in control.** No work tool runs until you approve the plan. An approval prompt left unanswered for five minutes counts as a rejection.

> [!WARNING]
>
> Never paste a provider API key or other secret into a chat message. Chat content and long-term memory are stored as workspace data.

For how the runtime, tools and gates work internally, see [AI agent architecture](https://docs.oasm.io/architecture/ai-agent.md).

## In this section

> [card] [Connect a model](https://docs.oasm.io/ai-studio/connect-a-model.md)
>
> Connect a provider, pick a model and set your default

> [card] [Chat](https://docs.oasm.io/ai-studio/chat.md)
>
> The composer, Ask and Agent modes, starter prompts and conversations

> [card] [Plans and approvals](https://docs.oasm.io/ai-studio/plans-and-approvals.md)
>
> Review plans and approve commands before they run

> [card] [Side panel](https://docs.oasm.io/ai-studio/side-panel.md)
>
> Plan, Workflow, Subagents, Browser, Tool calls and Stats

> [card] [Project chats](https://docs.oasm.io/ai-studio/project-chats.md)
>
> Lock a chat to one project and give the agent project context

> [card] [Connectors](https://docs.oasm.io/ai-studio/connectors.md)
>
> The tools the agent can use, and external MCP servers

> [card] [Usage](https://docs.oasm.io/ai-studio/usage.md)
>
> Tokens, cost, sessions and cache hit over time

> [card] [Models](https://docs.oasm.io/ai-studio/settings/models.md)
>
> Default, small and subagent models, reasoning effort and approval mode

> [card] [Agents](https://docs.oasm.io/ai-studio/settings/agents.md)
>
> Built-in agents and your custom agents

> [card] [Skills](https://docs.oasm.io/ai-studio/settings/skills.md)
>
> System skills and workspace skills

> [card] [Web Search](https://docs.oasm.io/ai-studio/settings/web-search.md)
>
> The search provider the agent uses to browse the web

> [card] [Instruction](https://docs.oasm.io/ai-studio/settings/instruction.md)
>
> Standing instructions added to every conversation

> [card] [Memory](https://docs.oasm.io/ai-studio/settings/memory.md)
>
> Long-term memory across your conversations

> [card] [MCP Server](https://docs.oasm.io/settings/mcp.md)
>
> Let external AI clients read your workspace over MCP


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