---
title: Agents
description: A superfície de trabalho do Studio — um agent, um trabalho, seu próprio histórico de thread e tools
icon: Bot
---

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

## O que é um agent?

Um **agent** é uma IA configurada para um trabalho específico: um conjunto focado de tools, instruções claras e um único propósito. Agents são a superfície de trabalho do Studio — quase tudo o que você faz no produto acontece dentro de um.

Um agent tem:

- **Um objetivo claro** — o que ele faz e quando usá-lo
- **As tools certas** — apenas o que ele precisa, anexadas a partir das suas [connections](/pt-br/studio/connections)
- **Instruções detalhadas** — como se comportar, o que priorizar, o que evitar
- **Um histórico de thread** — cada conversa passada com ele, salva e retomável
- **Um layout** — o que o usuário vê ao abrir o agent, além de quaisquer pinned views trazidas das suas tools conectadas
- **Um sandbox opcional** — um runtime isolado onde o agent pode rodar código de um repo vinculado (seu próprio MCP server, um dev server, etc.)
- **Automations opcionais** — schedules ou triggers de evento que executam o agent sem supervisão

Você chega a um agent pela home grid, pela lista de threads na sidebar ou pelo botão **+** / "Browse agents". Abra um e a tela inteira se torna aquele agent.

## A tela do agent

Quando você abre um agent, a tela se divide em duas:

- **Esquerda — chat.** Converse com o agent em linguagem natural; ele usa as tools anexadas para fazer o trabalho. Suas mensagens e threads passadas com este agent ficam aqui. Acima do input estão o **model picker** e o **runtime picker** (veja [Onde um agent roda](#where-an-agent-runs)).
- **Direita — um painel com abas.** Quais abas aparecem depende do que o agent é:

| Tab | Quando aparece |
|---|---|
| **Settings** | Sempre que você pode gerenciar agents — nome, descrição, ícone, instruções, connections anexadas, files & skills, e **layout** (a view padrão, mais pinned views de tools que expõem uma UI interativa) |
| **Automations** | Sempre — schedules e triggers de evento anexados a este agent |
| **Preview** | Quando o agent é respaldado por um repo ou site clonável — um preview ao vivo do que ele constrói |
| **Content** | Quando esse repo expõe páginas ou seções editáveis — edite o conteúdo inline |
| **Review changes** | Quando o agent está vinculado a um repo do GitHub **e tem um pull request aberto** — revise a branch e seu diff |

Um agent baseado em Git também mostra um **branch selector** ao lado do runtime picker, e um indicador de **status do sandbox** enquanto seu ambiente inicializa.

Tudo sobre um único agent vive nesta única tela.

### Layout e pinned views

Algumas connections expõem mais do que tools — elas trazem uma UI interativa (um dashboard, um formulário, um explorador de dados) junto ao seu endpoint MCP. Nas configurações de **Layout** do agent, você pode fixar qualquer uma dessas views para que apareçam como abas de nível superior dentro do agent. É assim que um agent se transforma em um pequeno app de propósito específico, e não apenas um chat.

Essas views vêm de **MCP apps**.

### MCP apps: estendendo o Studio com tools + UI

Um **MCP app** é a forma de estender o Studio hoje. É um MCP server comum que empacota duas coisas em um único pacote:

- **Tools** — as ações que um agent pode executar
- **Views** — UIs em React (uma página, um painel, um dashboard) entregues como resources, vinculadas a tools específicas via `_meta.ui.resourceUri`

Quando um MCP app é instalado como uma connection, o Studio sabe quais views pertencem a quais tools. Fixe uma view no Layout do agent e ela aparece como uma aba no agent — clicar no resultado de uma tool relevante, ou abrir a aba diretamente, carrega a view inline. A comunicação bidirecional entre o chat e a view é tratada pelo Studio.

Para criar um MCP app você usa o framework `@decocms/runtime` (React 19 + Tailwind + shadcn, compilado para um único arquivo HTML com Vite). O template de referência — incluindo estrutura de projeto, configuração de build e exemplos de tools-com-views — fica em [github.com/decocms/mcp-app](https://github.com/decocms/mcp-app).

Em um release futuro, o Studio permitirá que você construa views simples diretamente dentro da UI do agent, sem precisar criar um repo. Para qualquer coisa custom ou de nível de produção hoje, comece pelo template repo acima.

### Sandbox

Um agent pode ser respaldado por código. Vincule-o a um repositório do GitHub em **Settings → Sandbox** e o Studio executará o repo como um ambiente de dev isolado com escopo daquele agent — tipicamente o próprio MCP server do agent, mas pode ser qualquer serviço que o agent precise. O sandbox inicia sob demanda, vive apenas enquanto o agent precisar dele, e nunca vaza entre agents.

Quando o agent está rodando com um runtime local de code-editor, os botões **Open in VSCode** e **Open in Cursor** aparecem diretamente na barra de abas para acesso com um clique ao repositório na sua máquina. Em outros modos de runtime, as mesmas opções ficam disponíveis no menu de três pontos (⋯) da barra de abas.

## Onde um agent roda

Acima do input do chat, ao lado do model picker, está o **runtime picker**. Ele controla *onde* o agent executa e *qual harness* o conduz. Há dois grupos:

**Cloud**

- **Decopilot** — _"Roda em um agent sandbox."_ O agent executa em um sandbox gerenciado pelo Studio. Este é o padrão, sempre disponível, sem nada para instalar.

**Local** — rode o agent na sua própria máquina. Até que um runtime local seja conectado, essas opções exibem **"Desktop not detected"** e ficam desabilitadas.

- **Decopilot** — o harness do Decopilot, rodando no seu desktop
- **Claude Code** — conduz o agent com o CLI do [Claude Code](https://claude.com/claude-code)
- **Codex** — conduz o agent com o CLI do Codex

Rodar localmente significa que o sandbox do agent vive na sua máquina: ele pode ler e escrever seus arquivos locais, usar suas ferramentas instaladas e rodar com suas próprias credenciais — enquanto o Studio continua tratando o chat, as connections e o logging. O cloud sandbox, por outro lado, é totalmente gerenciado e isolado por agent.

Para habilitar as opções locais, conecte um runtime de desktop com `deco link`. O Studio detecta a connection e acende quaisquer harnesses que ela expõe — **Claude Code** e **Codex** aparecem assim que seu CLI estiver disponível na máquina vinculada.

<Callout type="tip">
  Cloud é o padrão certo para execuções sem supervisão e para colegas de time que não deveriam precisar de uma configuração local. Recorra a um runtime local quando o agent precisar da sua máquina — seus arquivos, suas credenciais ou um coding harness como Claude Code ou Codex.
</Callout>

## Um agent é um MCP virtual

Cada agent no Studio é exposto como seu próprio **endpoint MCP**: um pacote curado de tools, resources e instruções ao qual qualquer client compatível com MCP pode se conectar. Você pode pensar em um agent como um "MCP server virtual" que você monta visualmente — escolha algumas tools das suas connections, adicione instruções, e você publicou um endpoint MCP focado que seu time (ou seus outros agents) pode usar.

É por isso que o mesmo agent pode ser usado de três formas diferentes:

- **Pelo chat do Studio** — abra o agent e converse com ele
- **Por um client externo** — aponte Cursor, Claude Desktop ou qualquer MCP client para o endpoint do agent
- **Por outro agent ou tool** — chame-o programaticamente via MCP

Quando duas connections anexadas expõem uma tool com o mesmo nome, a da connection listada primeiro vence; a duplicata é descartada silenciosamente.

## Anexando connections

Connections ficam em **Settings → Connections** no nível da org. Dentro da aba **Settings** de um agent, você escolhe quais connections (e quais tools específicas de cada uma) o agent pode usar. Escolha de forma restrita. Um agent com três tools bem escolhidas se comporta de forma mais previsível do que um com trinta.

## Agents integrados

O Studio já vem com agents para gerenciar a própria plataforma — criar outros agents, configurar connections, gerenciar membros, navegar na store. Eles estão disponíveis imediatamente, sem configuração.

## Projetando um bom agent

**Mantenha o escopo restrito.** Um agent que faz uma coisa bem é mais confiável e fácil de manter do que um que tenta fazer tudo. Se você se pegar anexando tools não relacionadas, crie um segundo agent.

**Escreva instruções como um handoff.** Workflow passo a passo, casos extremos para observar, o que fazer quando algo dá errado. O campo de instruções é onde vivem a personalidade e o julgamento do agent.

**Escolha tools deliberadamente.** Um agent de atendimento ao cliente precisa de tools de consulta de pedidos e reembolso — não de tools de estoque ou marketing.

**Bom**: "Order Fulfillment Agent" — processa e envia pedidos
**Amplo demais**: "Ecommerce Operations Agent" — fulfillment, atendimento ao cliente, estoque, marketing, analytics…

## Formas de rodar um agent

- **Interativamente** — abra o agent e converse
- **Sem supervisão** — anexe uma [automation](/pt-br/studio/automations) que o execute em um schedule ou evento
- **Pelo Decopilot** — o Decopilot pode passar uma tarefa para um agent especialista em uma subtask (veja [Decopilot](/pt-br/studio/decopilot/overview))
- **Pelo seu próprio código** — chame seu endpoint MCP diretamente

---

**Próximo:** Anexe tools via [Connections](/pt-br/studio/connections), execute agents sem supervisão com [Automations](/pt-br/studio/automations), ou veja [Decopilot](/pt-br/studio/decopilot/overview) para entender como o assistente integrado do Studio usa agents.
