---
title: Agents
description: The working surface of Studio — one agent, one job, its own thread history and tools
icon: Bot
---

import Callout from "../../../../components/ui/Callout.astro";

## What is an agent?

An **agent** is an AI configured for a specific job: a focused set of tools, clear instructions, and a single purpose. Agents are the working surface of Studio — almost everything you do in the product happens inside one.

An agent has:

- **A clear goal** — what it does and when to use it
- **The right tools** — only what it needs, attached from your [connections](/en/studio/connections)
- **Detailed instructions** — how to behave, what to prioritize, what to avoid
- **A thread history** — every past conversation with it, saved and resumable
- **A layout** — what the user sees when they open the agent, plus any pinned views surfaced from its connected tools
- **An optional sandbox** — an isolated runtime where the agent can run code from a linked repo (its own MCP server, a dev server, etc.)
- **Optional automations** — schedules or event triggers that run the agent unattended

You reach an agent from the home grid, the thread list in the sidebar, or the **+** / "Browse agents" button. Open one and the whole screen becomes that agent.

## The agent screen

When you open an agent, the screen splits in two:

- **Left — chat.** Talk to the agent in natural language; it uses its attached tools to do the work. Your past messages and threads with this agent live here. Above the input are the **model-tier picker** (Fast, Smart, Thinking — see [AI Providers](/en/studio/ai-providers)) and the **runtime picker** (see [Where an agent runs](#where-an-agent-runs)).
- **Right — a tabbed panel.** Which tabs appear depends on what the agent is:

| Tab | When it appears |
|---|---|
| **Settings** | Whenever you can manage agents — name, description, icon, instructions, attached connections, files & skills, and **layout** (the default view, plus pinned views from tools that expose an interactive UI) |
| **Automations** | Always — schedules and event triggers attached to this agent |
| **Preview** | When the agent is backed by a clonable repo or site — a live preview of what it builds |
| **Content** | When that repo exposes editable pages or sections — edit content inline |
| **Review changes** | When the agent is linked to a GitHub repo **and has an open pull request** — review the branch and its diff |

A Git-backed agent also shows a **branch selector** beside the runtime picker, and a **sandbox status** indicator while its environment boots.

Everything about a single agent lives on this one screen.

### Layout and pinned views

Some connections expose more than tools — they ship an interactive UI (a dashboard, a form, a data explorer) alongside their MCP endpoint. In the agent's **Layout** settings, you can pin any of those views so they appear as top-level tabs inside the agent. This is how an agent turns into a small purpose-built app, not just a chat.

These views come from **MCP apps**.

### MCP apps: extending Studio with tools + UI

An **MCP app** is the way to extend Studio today. It's a regular MCP server that bundles two things in one package:

- **Tools** — the actions an agent can take
- **Views** — React UIs (a page, a panel, a dashboard) shipped as resources, linked to specific tools via `_meta.ui.resourceUri`

When an MCP app is installed as a connection, Studio knows which views belong to which tools. Pin a view in the agent's Layout and it surfaces as a tab in the agent — clicking a relevant tool result, or opening the tab directly, loads the view inline. Two-way communication between the chat and the view is handled by Studio.

Authoring an MCP app uses the `@decocms/runtime` framework (React 19 + Tailwind + shadcn, built to a single HTML file with Vite). The reference template — including project structure, build setup, and examples of tools-with-views — lives at [github.com/decocms/mcp-app](https://github.com/decocms/mcp-app).

In a future release, Studio will let you build simple views directly inside the agent UI, without scaffolding a repo. For anything custom or production-grade today, start from the template repo above.

### Sandbox

An agent can be backed by code. Link it to a GitHub repository in **Settings → Sandbox** and Studio will run the repo as an isolated dev environment scoped to that agent — typically the agent's own MCP server, but it can be any service the agent needs. The sandbox starts on demand, lives only as long as the agent needs it, and never leaks across agents.

When the agent is running with a local code-editor runtime, **Open in VSCode** and **Open in Cursor** buttons appear directly in the tab bar for one-click access to the repo on your machine. In other runtime modes the same options are available in the tab bar's three-dot (⋯) menu.

## Where an agent runs

Above the chat input, next to the model picker, is the **runtime picker**. It controls *where* the agent executes and *which harness* drives it. There are two groups:

**Cloud**

- **Decopilot** — _"Runs in an agent sandbox."_ The agent executes in a sandbox managed by Studio. This is the default, always available, with nothing to install.

**Local** — run the agent on your own machine. Until a local runtime is connected, these options read **"Desktop not detected"** and stay disabled.

- **Decopilot** — the Decopilot harness, running on your desktop
- **Claude Code** — drives the agent with the [Claude Code](https://claude.com/claude-code) CLI
- **Codex** — drives the agent with the Codex CLI

Running locally means the agent's sandbox lives on your machine: it can read and write your local files, use your installed tooling, and run with your own credentials — while Studio still handles the chat, connections, and logging. The cloud sandbox, by contrast, is fully managed and isolated per agent.

To enable the local options, connect a desktop runtime with `deco link`. Studio detects the connection and lights up whichever harnesses it exposes — **Claude Code** and **Codex** appear once their CLI is available on the linked machine.

<Callout type="tip">
  Cloud is the right default for unattended runs and teammates who shouldn't need a local setup. Reach for a local runtime when the agent needs your machine — your files, your credentials, or a coding harness like Claude Code or Codex.
</Callout>

## Windows

The daemon runs natively on Windows with one prerequisite: **[Git for Windows](https://gitforwindows.org)** — it provides both `git` and the bash shell used to run your project's dev scripts. If the daemon reports "POSIX shell (sh) not found", install Git for Windows or set the `DECO_SHELL` environment variable to a bash-compatible shell. WSL2 remains a fully supported alternative. Org file mounts are not yet available on Windows.

## An agent is a virtual MCP

Each agent in Studio is exposed as its own **MCP endpoint**: a curated bundle of tools, resources, and instructions that any MCP-compatible client can connect to. You can think of an agent as a "virtual MCP server" that you assemble visually — pick a few tools from your connections, layer on instructions, and you've published a focused MCP endpoint your team (or your other agents) can use.

This is why the same agent can be used three different ways:

- **From the Studio chat** — open the agent and talk to it
- **From an external client** — point Cursor, Claude Desktop, or any MCP client at the agent's endpoint
- **From another agent or tool** — call it programmatically over MCP

When two attached connections expose a tool with the same name, the one from the connection listed first wins; the duplicate is dropped silently.

## Attaching connections

Connections live in **Settings → Connections** at the org level. Inside an agent's **Settings** tab, you choose which connections (and which specific tools from each) the agent can use. Pick narrow. An agent with three well-chosen tools behaves more predictably than one with thirty.

## Built-in agents

Studio ships with agents for managing the platform itself — creating other agents, configuring connections, managing members, browsing the store. They're available immediately without setup.

## Designing a good agent

**Keep the scope tight.** An agent that does one thing well is more reliable and easier to maintain than one that tries to do everything. If you find yourself attaching unrelated tools, make a second agent.

**Write instructions like a handoff.** Step-by-step workflow, edge cases to watch for, what to do when something goes wrong. The instructions field is where the agent's personality and judgment live.

**Choose tools deliberately.** A customer service agent needs order lookup and refund tools — not inventory or marketing tools.

**Good**: "Order Fulfillment Agent" — processes and ships orders
**Too broad**: "Ecommerce Operations Agent" — fulfillment, customer service, inventory, marketing, analytics…

## Ways to run an agent

- **Interactively** — open the agent and chat
- **Unattended** — attach an [automation](/en/studio/automations) that runs it on a schedule or event
- **From Decopilot** — Decopilot can hand a task to a specialist agent in a subtask (see [Decopilot](/en/studio/decopilot/overview))
- **From your own code** — call its MCP endpoint directly

---

**Next:** Attach tools via [Connections](/en/studio/connections), run agents unattended with [Automations](/en/studio/automations), or see [Decopilot](/en/studio/decopilot/overview) for how Studio's built-in assistant uses agents.
