Usar o modo plano

Este guia mostra como obter um plano estruturado de um agente antes de este escrever qualquer código.

No modo plano, o agente investiga em modo só de leitura e o seu único entregável é um plano tipado: um grafo de dependências de passos que aprova e que o Control Center compila depois em trabalho real. Use-o quando quiser ver o âmbito de uma alteração, obter a decomposição dos passos ou ter os riscos e as dependências nomeados antes de se tocar em algo.

Colocar um espaço em modo plano

Qualquer uma destas ações muda o modo do espaço e a alteração é persistida:

Escolha Plano no seletor de modos na extremidade esquerda da barra de ferramentas do compositor
Prima Shift+Tab
Envie /plan. Um /plan isolado apenas arma o modo; /plan <request> arma-o e envia o resto como a sua mensagem

O /plan nunca viaja como texto — define o modo guardado, que é a autoridade que a superfície de ferramentas, a predefinição de barreiras e o prompt leem. Por isso, o modo mantém-se neste turno e em todos os turnos seguintes, até o voltar a alterar.

O modo fica guardado no espaço, por isso o mesmo agente pode estar em modo plano num espaço e em modo agente noutro.

O que o agente produz

Investiga em modo só de leitura — memória, o índice de código, ficheiros
Chama submit_plan uma única vez, com um goal e nodes, cada um com uma key estável, um title, uma description e as chaves dos nós de que dependsOn (é isso que permite que trabalho independente corra em paralelo)
Para

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

O plano aparece na conversa como uma linha compacta que mostra o objetivo, o estado e o número de passos. O Plan Studio — o grafo de dependências, o inspetor por nó e a estimativa de custo — abre num separador ao lado da conversa: prima Abrir na linha ou limite-se a esperar, porque um plano que chegue nos primeiros 30 segundos, enquanto está a ver a conversa, abre o separador sozinho.

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

Precisa de um espaço onde ser apresentada, pelo que um despacho pontual sem conversa não a tem. Ainda assim, adiantar o âmbito, o repo de destino e os critérios de aceitação na primeira mensagem continua a ser mais rápido do que uma ida e volta.

A prosa não é um entregável aqui. Uma execução que termina sem chamar submit_plan publica na conversa a linha visível «Ended without submitting a plan (no submit_plan call).» e assinala a execução como tendo falhado o seu entregável. O estado da execução mantém-se deliberadamente em completed — isso deixa intactas as máquinas de estados dos pipelines e dos tickets —, por isso leia a linha, não o distintivo de estado.

Aprovar o plano

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

A seguir:

O Control Center compila o plano numa orquestração e materializa-a — os tickets e a execução. Nenhum modelo intervém neste passo; é determinístico
O plano é executado pelo agente que o escreveu. Decidir se envolve mais alguém é uma decisão desse agente em tempo de execução — pode chamar delegate_task para entregar um passo a um colega mais adequado, dentro do limite de profundidade de delegação do espaço de trabalho
O objetivo do plano passa a ser o objetivo da conversa e o trabalho corre nessa mesma conversa: cada passo publica o que foi pedido ao agente e transmite o seu turno de volta, pelo que acompanha o trabalho (e pode parar um turno) onde já está
A linha do objetivo no painel lateral Geral da conversa (na secção Tarefas) transporta o progresso da execução como settled/total e o respetivo botão de paragem; o Plan Studio mostra o estado de cada nó no grafo e também permite cancelar aí

Continuar a trabalhar sem aprovar

Se preferir ficar nesta conversa em vez de aprovar o plano, o agente pode chamar exit_plan_mode. É a única saída sancionada: abre um pedido de aprovação duradouro ligado à conversa e devolve pending — o espaço permanece em modo plano e o agente não deve agir. Assim que o pedido é aprovado, a chamada seguinte de exit_plan_mode pelo agente muda o espaço do modo plano para o modo agente e desbloqueia as suas ferramentas que alteram estado. Uma rejeição permite-lhe abrir um novo pedido com base num plano revisto.

Para sair do modo plano, mude o seletor do compositor (ou use Shift+Tab) ou aprove o plano submetido. O exit_plan_mode abre uma aprovação duradoura decidida com a ferramenta MCP decide_approval. A sobreposição de barreiras para chamadas de ferramentas bloqueadas é outra fila, mantida em memória, e não transporta pedidos de saída do modo plano.

O modo plano num passo 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 recai no valor predefinido do corpo, que é o modo revisão, e não o chat. Um passo promptAgent junta-se a uma sala que não criou e não lhe reconfigura as permissões. O seletor Modo de despacho do editor de configuração do nó (allParallel / manager) destina-se a nós de despacho de equipas. Defina o modo da conversa com extras['mode'] num modelo que abre o espaço, ou na configuração desse nó através da API.