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

> How the Security Agent runtime works — the streaming loop, system prompts, tools, plan and approval gates, and what it remembers

The core API hosts the **Security Agent**, a chat-driven runtime that answers questions about the attack surface and, in Agent mode, acts on them. It lives inside the core API ([tier 2](https://docs.oasm.io/architecture/overview.md#2-core-api)) rather than forming its own tier, so it is not drawn in the platform diagram.

```mermaid theme={null}
flowchart TD
    User([User])
    Console[Console chat]

    subgraph Agent["Security Agent runtime — inside the core API"]
        direction TB
        Loop["Streaming loop<br/>reasoning and tool calls"]
        Prompt["System prompts<br/>base + mode + plan"]
        Skill["Skills<br/>loaded on demand"]
        Plan["Plan and steps"]
        Gate["Approvals gate"]
        Loop --> Prompt
        Loop --> Skill
        Loop --> Plan
        Loop --> Gate
    end

    subgraph Tools["What the agent can call"]
        direction TB
        Data["Workspace data tools<br/>assets, vulnerabilities, targets, ports,<br/>technologies, TLS, issues, jobs, workers"]
        Web["Web fetch<br/>CVE records and vendor advisories"]
        MCP["External MCP tools<br/>connected from outside OASM"]
        Cmd["Remote command<br/>shell on a worker node"]
        Data ~~~ Web
        Web ~~~ MCP
        MCP ~~~ Cmd
    end

    subgraph State["What the agent remembers"]
        direction TB
        STM[("Short-term memory<br/>Redis, per conversation")]
        LTM[("Long-term memory<br/>workspace knowledge")]
        Hist[("Messages and tool calls")]
        STM ~~~ LTM
        LTM ~~~ Hist
    end

    LLM[LLM provider<br/>member's API key]
    Worker[Worker nodes]

    User --> Console
    Console --> Loop
    Loop <-->|Reason and choose| LLM
    Loop --> Data
    Loop --> Web
    Loop --> MCP
    Loop --> Gate
    Gate -->|Approved| Cmd
    Cmd --> Worker
    Loop <-->|Recall and save| STM
    Loop <-->|Persist| LTM
    Loop <-->|Transcript| Hist
```

## The loop

A run is a streaming loop: the model receives the conversation, the system prompt for the current mode, the conversation history, and the tool definitions, then emits text or tool calls. Each tool call executes and its result is fed back, so the model can chain calls until it has what it needs — up to a configured step limit.

The system prompt is assembled from a small set of files: a base prompt shared by all modes, a mode-specific prompt (**Ask** or **Agent**), and a plan prompt added only when plan mode is active. Skills are appended as a list of available specialist instructions, which the agent loads on demand rather than carrying in full context up front.

## Tools

The agent's tools fall into three groups:

* **Workspace data tools** — read and query the inventory: assets, vulnerabilities, targets, ports, technologies, TLS certificates, issues, jobs, workers, and dashboard statistics. Every call is scoped to the current workspace, so the agent cannot see another tenant's data.
* **Web fetch** — retrieves public pages for CVE records, vendor advisories, and exploit references when workspace data alone is not enough.
* **External MCP tools** — tools connected from outside OASM, discovered from configured MCP servers and passed through the same approvals gate as built-in tools.

One tool is special: **remote command execution**. Instead of reading data, it runs a shell command on a connected worker node — never on the core API host — which gives the runtime access to real security tooling like `nmap`, `dig`, and `curl`, executed against the workspace's scope — never on the core API host.

## Plans and approvals

Plans and approvals are two separate gates that answer different questions.

A **plan** is the model's proposed step sequence, frozen at approval time: the runtime cannot restructure it mid-run, so the approved step list is the executed step list. Approval also sets the run's autonomy — proceed automatically, or ask before each command.

The **approvals gate** then governs individual calls as they happen:

* **Read-only tools** run without asking.
* **Side-effecting calls** — remote commands and non-read-only MCP tools — block until approved. An approval can be scoped to the single call or to the rest of the conversation.
* A rejection carries feedback back into the loop as a tool result. A rejected command is **not retried**: the model either follows the feedback or asks how to proceed.

> [!NOTE]
>
> The gate is why Agent mode can be autonomous without being unsupervised: the runtime can plan and read freely, but nothing that changes state leaves the platform until a human has said so.

## Memory

Findings are remembered at two scopes. **Short-term memory** lives in Redis for the duration of a conversation, so the agent can recall what it already discovered without re-querying. **Long-term memory** is persisted per workspace, carrying knowledge across conversations — target profiles, known exposures, and analysis worth keeping.

Messages and every tool call are persisted too, so the full history of a run — what was called, with what arguments, and what came back — remains inspectable after the fact.

## Where the runtime gets its data

The agent does not query the database directly. Workspace tools read the same inventory the [data pipeline](https://docs.oasm.io/architecture/overview.md#the-data-pipeline) populates, and side effects it triggers — scans, job state changes — reach the rest of the platform as events on the [event bridge](https://docs.oasm.io/architecture/event-bridge.md), the same way a console action does.

## Related

> [card] [Chat Agent](https://docs.oasm.io/chat-agent.md)
>
> The console surface this runtime backs

> [card] [MCP](https://docs.oasm.io/settings/mcp.md)
>
> The external-tool protocol the runtime consumes

> [card] [Event bridge](https://docs.oasm.io/architecture/event-bridge.md)
>
> How the platform propagates the changes the agent causes

> [card] [Architecture overview](https://docs.oasm.io/architecture/overview.md)
>
> The five tiers the agent runs inside


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