Usar o modo plano

Este guia mostra como obter um plano estruturado de um agente antes que ele escreva qualquer código.

No modo plano, o agente pesquisa em somente leitura e seu único entregável é um plano tipado: um grafo de dependências de etapas que você aprova, e que o Control Center então compila em trabalho real. Use-o quando quiser ver o escopo de uma mudança, ter as etapas detalhadas ou ver riscos e dependências nomeados antes que qualquer coisa seja tocada.

Colocar um espaço em modo plano

Qualquer um destes alterna o modo do espaço, e a mudança é persistida:

• Escolha Plano na lista suspensa de modo, na extremidade esquerda da barra de ferramentas do composer
• Pressione Shift+Tab
• Envie /plan. Um /plan sozinho apenas arma o modo; /plan <request> o arma e envia o restante como sua mensagem

O /plan nunca trafega como texto — ele define o modo armazenado, que é a autoridade que a superfície de ferramentas, a predefinição de guardrails e o prompt leem. Assim, o modo vale para esta rodada e para todas as seguintes, até você revertê-lo.

O modo é armazenado no espaço, então o mesmo agente pode estar em modo plano aqui e em modo agente em outro lugar.

O que o agente produz

1. Ele pesquisa em somente leitura — memória, o índice de código, arquivos
2. Ele chama submit_plan uma vez, com um goal mais nodes, cada um com uma key estável, um title, uma description e as chaves de nó das quais ele dependsOn (e é isso que permite que trabalho independente rode em paralelo)
3. Ele para

A ferramenta valida o grafo — chaves duplicadas, dependências pendentes, ciclos — e devolve as violações para o agente corrigir, em vez de aceitar um plano quebrado.

O plano aparece na conversa como uma linha compacta que mostra o objetivo, seu status e a contagem de etapas. O Plan Studio — o grafo de dependências, o inspetor por nó e a estimativa de custo — abre como uma aba ao lado da conversa: pressione Abrir na linha ou simplesmente espere, porque um plano que chega em até 30 segundos enquanto você acompanha a conversa abre a aba sozinho.

A garantia de somente leitura é estrutural, mas só no harness integrado

O harness do próprio Control Center monta o registro de ferramentas do agente a partir da especificação de superfície do modo plano, então simplesmente não há ferramenta de escrita, edição ou comando para chamar — a restrição não é uma instrução de prompt da qual o modelo possa se convencer a abrir mão.

O adaptador Claude Code não recebe essa filtragem: o modo chega até ele como uma solicitação que o próprio runner pode ou não honrar, e o Control Center só vê suas chamadas mcp__*. O selo de aplicação ao lado da lista suspensa de modo aparece exatamente quando esse é o caso.

O agente pode fazer perguntas de esclarecimento

Quando o pedido é ambíguo, um agente em modo plano pode pausar e fazer até três perguntas bloqueantes com a ferramenta ask_user. Ele renderiza um formulário na conversa — opções ou texto livre — e a execução fica bloqueada até você responder. A ferramenta é de nível de leitura, então sobrevive à superfície somente leitura do modo plano, e é isenta do wrapper de aprovação (um prompt na frente de outro prompt falharia fechado sem nenhum aprovador conectado, negando ao agente o ato de perguntar).

Ela precisa de um espaço onde renderizar, então um despacho pontual sem conversa não a recebe. Adiantar o escopo, o repo de destino e os critérios de aceitação na sua primeira mensagem continua sendo mais rápido do que uma ida e volta.

Prosa não é um entregável aqui. Uma execução que termina sem chamar submit_plan publica na conversa uma linha visível “Ended without submitting a plan (no submit_plan call).” e sinaliza que a execução não cumpriu seu entregável. O status da execução permanece de propósito como completed — isso mantém intactas as máquinas de estado de pipelines e tickets —, então leia a linha, não o selo de status.

Aprovar o plano

Na linha do plano na conversa, pressione Aprovar e executar. Na barra de aprovação do Plan Studio, pressione Aprovar plano (ou Rejeitar ao lado; a aprovação fica desativada enquanto o grafo tiver um erro de validação).

Em seguida:

1. O Control Center compila o plano em uma orquestração e a materializa — os tickets e a execução. Nenhum modelo participa desta etapa; ela é determinística
2. O plano é executado como o agente que o escreveu. Decidir se traz mais alguém é chamada desse agente em tempo de execução — ele pode delegate_task de uma etapa para um colega mais adequado, dentro do limite de profundidade de delegação do espaço de trabalho
3. O objetivo do plano se torna o objetivo da conversa e o trabalho roda nessa mesma conversa: cada etapa publica o que foi pedido ao agente e transmite a rodada dele de volta em fluxo, então você o acompanha (e pode parar uma rodada) de onde já está
4. A linha do objetivo no painel lateral Geral da conversa (sob Tarefas) traz o progresso da execução como settled/total e o botão de parar; o Plan Studio mostra o estado por nó no grafo e também cancela por ali

Continuar trabalhando sem aprovar

Se você preferir ficar nesta conversa em vez de aprovar o plano, o agente pode chamar exit_plan_mode. Essa é a única saída sancionada: ela abre uma solicitação de aprovação durável vinculada à conversa e retorna pending — o espaço continua em modo plano e o agente não deve agir. Depois que a solicitação é aprovada, a próxima chamada do agente a exit_plan_mode alterna o espaço do plano para o modo agente e libera suas ferramentas que mutam. Uma rejeição permite que ele abra uma nova solicitação com um plano revisado.

Para sair do modo plano, alterne a lista suspensa do composer (ou use Shift+Tab) ou aprove o plano enviado. O exit_plan_mode abre uma aprovação durável decidida com a ferramenta MCP decide_approval. O overlay de guardrails para chamadas de ferramenta bloqueadas é outra coisa: uma fila em memória, que não carrega solicitações de saída do modo plano.

O modo plano em uma etapa de pipeline

Um nó de pipeline messaging.createSpace lê o modo da conversa a partir do extra mode da configuração do nó — extras['mode']: 'plan'. A chave exige correspondência exata: qualquer outra grafia, incluindo conversationMode ou dispatchMode, é ignorada em silêncio e a sala recorre ao padrão do corpo, que é o modo Revisão, e não conversa. Uma etapa promptAgent entra em uma sala que não criou e não redefine as permissões dela. O seletor Modo de despacho do editor de configuração de nó (allParallel / manager) é para nós de despacho de equipe. Defina o modo da conversa com extras['mode'] em um modelo que abre o espaço, ou na configuração desse nó pela API.

Guias relacionados

• Conversar com um agente
• Usar espaços
• Trabalhar no Plan Studio
• Executar uma orquestração

Conceitos relacionados

• Modos
• Orquestração