Trabalhar no Plan Studio

Este guia mostra como trabalhar com planos no Plan Studio. Para saber o que são orquestrações e documentos de plano, consulte Orquestração e Usar o modo plano.

Abrir um plano

Um plano pertence à conversa que o produziu, então é lá que você normalmente o alcança: a linha do plano na conversa tem uma ação Abrir e o Plan Studio abre como uma aba de editor ao lado da conversa.

Não há entrada “Planos” na barra lateral

Isso é intencional, não um descuido. O hub em /workspaces/<workspace-id>/plans é apenas um deep link roteável, então marque-o nos favoritos se quiser uma lista permanente.

O hub lista três seções:

• Planos ativos — orquestrações, com as propostas primeiro, com seu status, a contagem de passos e o número da revisão.
• Documentos de plano — planos que um único agente enviou com submit_plan no modo plano, enquanto estão propostos ou aprovados.
• Playbooks — modelos de plano salvos e com parâmetros.

Clique em um card para abri-lo no Plan Studio. A rota é /workspaces/<workspace-id>/plans/<kind>/<plan-id>, em que kind é orchestration ou document, então você também pode criar um deep link para um único plano.

Se você abriu uma orquestração, recebe o canvas editável, a linha do tempo de versões e a barra de aprovação. Se você abriu um documento de plano, o mesmo grafo é renderizado como somente leitura — documentos de plano são escritos por agentes; você os revisa, estima e aprova ou rejeita, e um documento aprovado mostra o estado de execução ao vivo de cada nó da orquestração na qual ele foi compilado.

Editar o DAG

É possível editar uma orquestração enquanto ela está proposed. Todas as edições no canvas são feitas pelo teclado:

1. Clique no canvas e mova a seleção com as setas do teclado.
2. Pressione n para adicionar um passo. Ele aparece selecionado como “Novo passo”; renomeie-o no inspetor à direita.
3. Pressione e no passo que deve ser executado primeiro e clique no passo dependente (ou selecione-o e pressione Enter) para conectar uma dependência. Pressione Esc para descartar uma conexão pendente.
4. Pressione x para cortar a dependência mais recente do passo selecionado ou alterne as dependências exatas no editor de dependências do inspetor.
5. Pressione Delete para remover o passo selecionado; as referências a ele são removidas das dependências dos passos restantes.

No inspetor, você também pode editar a descrição, a função e o esquema de saída do passo. As edições são salvas automaticamente como uma nova revisão após uma breve pausa; um erro de validação (mostrado na barra de aprovação) bloqueia o salvamento até você corrigi-lo.

Somente passos de trabalho são editáveis. Nós estruturais — pesquisa, discussão e síntese — são somente leitura, e o mesmo vale para qualquer passo cujo trabalho já foi executado (ele é marcado como “já executado”, porque editá-lo bifurcaria o plano).

O salvamento é concorrente de forma otimista na revisão a partir da qual você começou. Se o orquestrador replanejar por baixo de você, seu salvamento é recusado com “o plano já avançou”, em vez de ser mesclado ou sobrescrito silenciosamente; releia a revisão atual e refaça sua edição. Os replanejamentos iniciados por agentes são limitados a um a cada dois minutos, então isso é raro.

Nota

O canvas não permite arrastar para reposicionar: o layout é calculado a partir da estrutura de dependências, então “mover” um passo significa reconectar suas dependências.

Ler estimativas de custo, tempo e risco

Pressione Estimar na barra de aprovação.

• Cada passo no canvas recebe um selo com um intervalo de custo e o tamanho da amostra por trás dele, ou “Ainda sem histórico” quando a função do passo nunca foi executada. Selecione um passo para ver todos os detalhes no inspetor: intervalo de custo com tamanho da amostra, um intervalo de duração e um raio de impacto (arquivos e símbolos) derivado da proveniência do passo — ou “desconhecido” quando o passo não tem proveniência.
• A barra de aprovação mostra o total do plano: um intervalo de custo geral, um intervalo de duração para o caminho crítico (ramos paralelos se sobrepõem, então isso não é a soma) e o teto de orçamento quando o plano define um.
• Se apenas alguns passos têm histórico, o total é marcado como parcial e abrange somente os passos estimáveis. Se o limite superior da estimativa exceder o teto de orçamento, o total fica vermelho com um aviso de orçamento excedido.

As estimativas são honestas ou ausentes: um passo cuja função não tem histórico de execuções concluídas informa um tamanho de amostra zero, sem nenhum intervalo, e é mostrado como desconhecido em vez de ser estimado por chute. Trate “Ainda sem histórico” como “ninguém sabe”, não como “barato”.

O teto de orçamento é uma comparação de exibição em relação a essa estimativa. Nada o aplica depois que o plano está em execução — consulte Gerenciar custos para controles que de fato interrompem os gastos.

Comparar uma revisão com uma proposta anterior

Cada edição e cada replanejamento feito pelo orquestrador é acrescentado a uma linha do tempo de revisões somente de acréscimo, mostrada no painel Versões, à esquerda de um plano de orquestração.

1. Clique em uma revisão para compará-la com a proposta atual. Sem nenhuma seleção, o painel compara a revisão anterior com a atual.
2. Leia as diferenças na metade inferior do painel: passos adicionados, removidos ou alterados entre as duas revisões.
3. Se o plano ainda estiver proposed, clique no ícone de retroceder em uma revisão para voltar a ela. Retroceder salva essa proposta como uma nova revisão — nada é perdido.

propose_orchestration e o editor recusam alterações quando o plano deixa de estar proposed, então uma execução em andamento não incorpora um replanejamento no meio da execução.

Aprovar, rejeitar ou ampliar um plano

No app, um plano proposto é uma única decisão, tomada por inteiro: Aprovar plano ou Rejeitar na barra de aprovação. Aprovar plano sempre aprova todos os passos — não há como selecionar um subconjunto primeiro. A aprovação é bloqueada enquanto a proposta tiver erros de validação, que são mostrados ao lado dos botões.

A aprovação é exclusiva do operador. Não há ferramenta MCP para isso, então um agente pode propor e revisar um plano, mas nunca aprová-lo.

Quando uma orquestração está em execução, a barra muda:

• Se um passo parou para perguntar no meio da execução, selecione-o e pressione Continuar nó para retomá-lo.
• Pressione Aprovar selecionados para ampliar uma aprovação parcial ao passo selecionado mais tudo de que ele depende transitivamente (um passo nunca pode ser aprovado sem suas dependências). O controle fica na barra de execução de toda orquestração; ele não tem efeito quando o plano foi aprovado por inteiro.
• Pressione Cancelar execução para interromper a orquestração inteira.

Os passos fora de um conjunto parcial aprovado são renderizados como adiados e não são executados até você ampliar o conjunto.

Aprovações parciais não podem se originar no app

Uma aprovação parcial só existe quando algo chamou orchestration.approve via RPC com uma lista explícita de approved_node_keys. Aprovar plano no app sempre aprova todos os passos. Os documentos de plano são sempre aprovados por inteiro, então um documento em execução oferece apenas Cancelar execução.

Executar um playbook com parâmetros

Um playbook é um modelo de plano salvo com marcadores {{param}} tipados em seu objetivo, títulos de passos, descrições e prompts. A substituição é literal — não há linguagem de expressão; se você precisar de lógica, use um pipeline em vez disso.

1. Na seção Playbooks do hub, pressione Executar no playbook (ou abra a paleta ⌘K e escolha o playbook lá).
2. Preencha os parâmetros. Parâmetros de enumeração são renderizados como menus suspensos; parâmetros de repo e de agente aceitam uma referência de repo ou de agente; parâmetros opcionais usam seu valor padrão.
3. Escolha o ticket de âncora contra o qual o plano é proposto e confirme.

Executar um playbook apenas propõe um plano — a orquestração instanciada abre no Plan Studio como proposed e nada é executado até você aprová-la lá. Para remover um playbook, pressione o ícone de lixeira no card dele.

Os agentes criam e executam playbooks com as ferramentas MCP create_playbook e run_playbook; consulte a referência de ferramentas MCP.

Guias relacionados

• Usar o modo plano: como um agente produz um documento de plano com submit_plan
• Executar uma orquestração: o ciclo de vida de aprovar uma vez do ponto de vista da conversa
• Criar um modelo de pipeline: quando você precisa de lógica que um playbook não consegue expressar
• Monitorar execuções de pipeline: a visão do motor de um plano aprovado

Conceitos relacionados

• Orquestração