Agents

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
• Detailed instructions — how to behave, what to prioritize, what to avoid
• A thread history — every past conversation with it, saved and resumable
• A layout — the default main view, plus which available project and pinned MCP-app views appear in the sidebar
• 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, its durable navigation lives in the project section of the sidebar and the workspace can split in two:

• Sidebar — project views. In Layout, choose whether Home, Reports, Tasks, Site Editor, Automations, and any available Assets, Hosting, E2E, Deco Analytics, Monitor, or pinned MCP-app view appears here. Selecting one opens it as the main view; these destinations do not also appear as top-level panel tabs.
• 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) and the runtime picker (see Where an agent runs).
• Right — main view. This is the view selected from the sidebar or configured as the project’s default. A view can still have its own contextual tabs — for example Preview, Content, and Code inside Site Editor — and temporary output from a chat can appear here without becoming permanent sidebar navigation.

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

The agent’s Layout settings independently control its default main view and sidebar entries. Projects that have not saved sidebar preferences start with Home, Reports, Tasks, and Site Editor when those views are present; Automations and other available views start off until enabled. Studio only offers a built-in project view when that view is present for the project: source-backed views require a repository or template, Assets needs an associated asset store, and Hosting, E2E, Deco Analytics, and Monitor depend on the site’s available services. A present view is available in the Main view selector whether or not its sidebar switch is enabled. The switch only adds or removes that durable entry from the project sidebar.

Some connections expose more than tools — they ship an interactive UI (a dashboard, a form, a data explorer) alongside their MCP endpoint. You can pin any of those views in Layout. A pinned view follows the same model: it becomes a selectable project-sidebar entry and an eligible default main view. 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 project-sidebar entry — clicking a relevant tool result, or selecting that entry, 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.

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.” Hosted Studio owns the runtime and, whenever a sandbox is needed, uses its managed AgentSandbox; callers do not choose a sandbox provider. This is the default, with nothing to install.

Local — run the agent in the native Studio desktop app. Outside the desktop app, these options read “Desktop not detected” and stay disabled.

• Claude Code — drives the agent with the Claude Code CLI
• Codex — drives the agent with the Codex CLI
• OpenCode — drives the agent with the OpenCode 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 use the local options, open the native Studio app. Its embedded local-api detects the supported CLIs on that machine, launches the selected harness in the chat’s local worktree, and intercepts sandbox lifecycle and filesystem calls locally. It records that runtime as local-api ; the hosted API remains fixed to AgentSandbox.

Windows

The daemon runs natively on Windows with one prerequisite: Git for Windows — 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 that runs it on a schedule or event
• From Decopilot — Decopilot can hand a task to a specialist agent in a subtask (see Decopilot)
• From your own code — call its MCP endpoint directly

Next: Attach tools via Connections, run agents unattended with Automations, or see Decopilot for how Studio’s built-in assistant uses agents.