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

# How agents work in stagewise

> Understand the agent loop, tool use, and what happens when you send a message to an AI coding agent in the stagewise agentic IDE. Learn how agents reason, use tools, and modify code.

An AI coding agent in stagewise is a model-powered assistant that reads, reasons about, and modifies your codebase through a structured loop. It's not autocomplete — it's an agent that thinks, acts, observes, and repeats until your task is done.

## The agent loop

Each message goes through a cycle of reasoning and action:

```mermaid theme={null}
graph TD
    A[👤 User sends message] --> B[📋 Agent receives context]
    B --> C[🧠 Model reasons about request]
    C --> D{Needs more info<br/>or action?}
    D -->|Take action| E[🔧 Agent uses tools]
    E --> F[📊 Tool results returned]
    F --> C
    D -->|Respond| G[💬 Agent replies to user]
```

The loop continues until the agent completes your request or needs your input.

Say you type: *"Add input validation to the signup form."*

1. **Receive context** — The agent reads your message along with WORKSPACE.md, open files, any @mentions, and DOM context you've attached
2. **Reason** — The model identifies the signup form component, checks what validation patterns the project uses, and plans what to change
3. **Act** — The agent uses tools: reads the form component file, searches for existing validation patterns, edits the file with the new logic
4. **Observe** — Tool results (the file contents, search matches, edit confirmation) are fed back to the agent
5. **Repeat or respond** — If more changes are needed (e.g., adding error messages, updating styles), the agent loops again. Otherwise, it responds: "Added input validation to the signup form. The form now checks..."

## Tools the agent can use

Agents have direct filesystem access through a set of built-in tools:

| Tool               | What it does                                                   |
| ------------------ | -------------------------------------------------------------- |
| **File reading**   | Read any file in connected workspaces                          |
| **File editing**   | Create, modify, or delete files with tracked changes           |
| **Code search**    | Search across your codebase with glob patterns and regex       |
| **Shell access**   | Run shell commands, scripts, and package managers              |
| **Browser access** | Inspect pages, take screenshots, and interact with web content |

## How the agent understands your project

The agent builds understanding from several sources before reasoning:

* **WORKSPACE.md** — Auto-generated project analysis in `.stagewise/` that maps your codebase structure, dependencies, and architecture
* **Skills** — Custom `SKILL.md` files you create to teach the agent project-specific patterns and constraints
* **AGENTS.md** — Optional project instruction file (disabled by default)
* **@mentions** — Files and tabs you explicitly reference in your message
* **DOM context** — Web elements you select from the browser viewport

All of these feed into a single reasoning pass. [Learn how context assembly works →](/core-concepts/agent-context)

## Multiple agents

stagewise supports multiple agent instances running in parallel. Each agent has its own chat session and can use a different model. Switch between agents with `Ctrl+Tab`.

Typical multi-agent setups:

* One agent on frontend changes, another on backend logic
* A fast model for simple refactors, a powerful model for complex architecture work
* Separate chats for separate tasks — keeps each conversation focused

## What agents can't do

Agents operate within the boundaries of your workspace access and tool permissions:

* Cannot access files outside your connected workspaces
* Cannot install system-level software without your explicit shell confirmation
* Cannot browse to external URLs without your direction
* Every file edit is tracked and reviewable — nothing happens silently

## What's next

<CardGroup cols={2}>
  <Card icon="folder-open" href="/core-concepts/workspaces" title="Workspaces">
    Learn how to connect multiple folders and let agents work across your stack.
  </Card>

  <Card icon="block-microphone" href="/core-concepts/models-and-providers" title="Models & providers">
    Choose which AI models power your agents — or bring your own.
  </Card>

  <Card icon="file-check" href="/core-concepts/diff-review" title="Diff review">
    Understand how agent changes are tracked and how to accept, reject, or undo them.
  </Card>
</CardGroup>