Agents

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
• 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 — a main view padrão, além de quais views disponíveis do projeto e de MCP apps fixados aparecem na sidebar
• 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 navegação permanente dele fica na seção do projeto na sidebar, e o workspace pode se dividir em duas partes:

• Sidebar — views do projeto. Em Layout, escolha se Home, Deco Score, Tasks, Site Editor, Automations e cada view disponível de Assets, Hosting, E2E, Deco Analytics, Monitor ou de MCP apps fixados aparece aqui. Selecionar uma delas a abre como main view; esses destinos não aparecem também como tabs de nível superior no painel.
• 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-tier picker (Fast, Smart, Thinking — veja AI Providers) e o runtime picker (veja Onde um agent roda).
• Direita — main view. Esta é a view selecionada na sidebar ou configurada como padrão do projeto. Uma view ainda pode ter suas próprias tabs contextuais — por exemplo, Preview, Content e Code dentro do Site Editor — e outputs temporários do chat podem aparecer aqui sem virar navegação permanente na sidebar.

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

As configurações de Layout do agent controlam de forma independente a main view padrão e as entradas da sidebar. Projetos que ainda não salvaram preferências da sidebar começam com Home, Deco Score, Tasks e Site Editor quando essas views estão presentes; Automations e as outras views disponíveis começam desabilitadas. O Studio só oferece uma view nativa quando ela está presente no projeto: views ligadas a código exigem um repositório ou template, Assets precisa de um armazenamento de assets associado e Hosting, E2E, Deco Analytics e Monitor dependem dos serviços disponíveis para o site. Uma view presente fica disponível no seletor de Main view mesmo que seu switch da sidebar esteja desabilitado. O switch apenas adiciona ou remove essa entrada permanente da sidebar do projeto.

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. Você pode fixar qualquer uma dessas views em Layout. Uma pinned view segue o mesmo modelo: ela se torna uma entrada selecionável na sidebar do projeto e uma opção de main view padrão. É 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 entrada na sidebar do projeto — clicar no resultado de uma tool relevante, ou selecionar essa entrada, 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.

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 Studio hosted é dono do runtime e, sempre que uma sandbox é necessária, usa seu AgentSandbox gerenciado; callers não escolhem um provider de sandbox. Este é o padrão, sem nada para instalar.

Local — rode o agent na app nativa do Studio para desktop. Fora da app desktop, essas opções exibem "Desktop not detected" e ficam desabilitadas.

• Claude Code — conduz o agent com o CLI do Claude Code
• Codex — conduz o agent com o CLI do Codex
• OpenCode — conduz o agent com o CLI do OpenCode

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 usar as opções locais, abra a app nativa do Studio. O local-api embutido detecta os CLIs compatíveis na máquina, inicia o harness selecionado no worktree local do chat e intercepta localmente as chamadas de lifecycle e filesystem da sandbox. Ele registra esse runtime como local-api; a API hosted continua fixa no AgentSandbox.

Windows

O daemon roda nativamente no Windows com um pré-requisito: Git for Windows — ele fornece tanto o git quanto o shell bash usado para rodar os scripts de dev do seu projeto. Se o daemon reportar "POSIX shell (sh) not found", instale o Git for Windows ou defina a variável de ambiente DECO_SHELL para um shell compatível com bash. O WSL2 continua sendo uma alternativa totalmente suportada. Montagens de arquivos da org ainda não estão disponíveis no Windows.

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 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)
• Pelo seu próprio código — chame seu endpoint MCP diretamente

---

Próximo: Anexe tools via Connections, execute agents sem supervisão com Automations, ou veja Decopilot para entender como o assistente integrado do Studio usa agents.