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, por isso é aí que normalmente o encontra: a linha do plano na conversa tem uma ação Abrir e o Plan Studio abre como separador de editor ao lado da conversa.

O hub lista três secções:

Planos ativos — orquestrações, primeiro as propostas, com o respetivo estado, número de passos e número de revisão.
Documentos de plano — planos que um único agente submeteu com submit_plan no modo plano, enquanto estão propostos ou aprovados.
Playbooks — modelos de plano guardados e parametrizados.

Clique num cartão para o abrir no Plan Studio. A rota é /workspaces/<workspace-id>/plans/<kind>/<plan-id>, em que kind é orchestration ou document, para que também possa criar uma ligação direta para um único plano.

Se abriu uma orquestração, obtém a área de desenho editável, a linha temporal de versões e a barra de aprovação. Se abriu um documento de plano, o mesmo grafo é apresentado só de leitura — os documentos de plano são criados por agentes; é você que os revê, estima e aprova ou rejeita, e um documento aprovado mostra o estado de execução em direto de cada nó da orquestração em que foi compilado.

Editar o DAG

É possível editar uma orquestração enquanto esta está proposed. Todas as edições na área de desenho são feitas com o teclado:

Clique na área de desenho e, em seguida, mova a seleção com as teclas de seta.
Prima n para adicionar um passo. Este aparece selecionado como «Novo passo»; mude-lhe o nome no inspetor à direita.
Prima e no passo que tem de ser executado primeiro e, em seguida, clique no passo dependente (ou selecione-o e prima Enter) para ligar uma dependência. Prima Esc para abandonar uma ligação pendente.
Prima x para cortar a dependência mais recente do passo selecionado, ou alterne dependências exatas no editor de dependências do inspetor.
Prima Delete para remover o passo selecionado; as referências a ele são removidas das dependências dos restantes passos.

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

Só os passos de trabalho são editáveis. Os nós estruturais — investigação, discussão e síntese — são só de leitura, tal como qualquer passo cujo trabalho já tenha sido executado (está marcado como «já executado», porque editá-lo bifurcaria o plano).

A gravação usa concorrência otimista sobre a revisão de onde partiu. Se o orquestrador replanear por baixo de si, a sua gravação é recusada com «o plano avançou», em vez de ser fundida ou substituída em silêncio; volte a ler a revisão atual e refaça a sua edição. Os replaneamentos iniciados por agentes estão eles próprios limitados a um de cada dois minutos, por isso isto continua a ser raro.

Ler as estimativas de custo, tempo e risco

Prima Estimar na barra de aprovação.

Cada passo na área de desenho recebe um distintivo com um intervalo de custo e a dimensão da amostra que o sustenta, ou «Ainda sem histórico» quando o papel do passo nunca foi executado. Selecione um passo para ver o detalhe completo no inspetor: intervalo de custo com dimensão da amostra, um intervalo de duração e um raio de impacto (ficheiros 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 global, um intervalo de duração para o caminho crítico (os ramos paralelos sobrepõem-se, por isso isto não é a soma) e o teto orçamental quando o plano define um.
Se apenas alguns passos tiverem histórico, o total é marcado como parcial e abrange apenas os passos estimáveis. Se o limite superior da estimativa exceder o teto orçamental, o total fica vermelho com um aviso de que está acima do orçamento.

As estimativas são honestas ou não existem: um passo cujo papel não tem histórico de execuções concluídas comunica uma dimensão de amostra de zero, sem quaisquer intervalos, e é apresentado como desconhecido em vez de ser adivinhado. Trate «Ainda sem histórico» como «ninguém sabe», e não como «barato».

O teto orçamental é uma comparação de apresentação em relação a esta estimativa. Nada o impõe depois de o plano estar em execução — consulte Gerir custos para conhecer os controlos que realmente travam os gastos.

Comparar uma revisão com uma proposta anterior

Cada edição e cada replaneamento do orquestrador são acrescentados a uma linha temporal de revisões só de acréscimo, mostrada no painel Versões, à esquerda de um plano de orquestração.

Clique numa revisão para a comparar com a proposta atual. Sem qualquer seleção, o painel compara a revisão anterior com a atual.
Leia as diferenças na metade inferior do painel: passos adicionados, removidos ou alterados entre as duas revisões.
Se o plano ainda estiver proposed, clique no ícone de rebobinar numa revisão para voltar a ela. Rebobinar guarda essa proposta como uma revisão nova — não se perde nada.

Tanto o propose_orchestration como o editor recusam alterações a partir do momento em que o plano já não está proposed, para que uma execução em curso não apanhe um replaneamento a meio da execução.

Aprovar, rejeitar ou alargar um plano

Na aplicação, um plano proposto é uma única decisão, tomada por inteiro: Aprovar plano ou Rejeitar na barra de aprovação. Aprovar plano aprova sempre todos os passos — não há forma de selecionar primeiro um subconjunto. A aprovação fica 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 existe nenhuma ferramenta MCP para isso, por isso um agente pode propor e rever um plano, mas nunca aprová-lo.

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

Se um passo parou para perguntar a meio da execução, selecione-o e prima Continuar nó para o retomar.
Prima Aprovar selecionados para alargar uma aprovação parcial ao passo selecionado mais tudo de que este depende transitivamente (um passo nunca pode ser aprovado sem as suas dependências). O controlo está na barra de execução de todas as orquestrações; não faz nada quando o plano foi aprovado por inteiro.
Prima Cancelar execução para parar toda a orquestração.

Os passos fora de um conjunto aprovado parcial são apresentados como adiados e não são executados enquanto não alargar o conjunto.

Executar um playbook com parâmetros

Um playbook é um modelo de plano guardado com marcadores {{param}} tipados no seu objetivo, títulos de passos, descrições e prompts. A substituição é literal — não existe nenhuma linguagem de expressões; se precisar de lógica, use antes um pipeline.

Na secção Playbooks do hub, prima Executar no playbook (ou abra a paleta ⌘K e escolha aí o playbook).
Preencha os parâmetros. Os parâmetros de enumeração são apresentados como listas pendentes; os parâmetros de repo e de agente recebem uma referência de repo ou de agente; os parâmetros opcionais assumem o respetivo valor predefinido.
Escolha o ticket de âncora em relação ao 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é que o aprove aí. Para remover um playbook, prima o ícone do caixote do lixo no respetivo cartão.

Os agentes criam e executam playbooks com as ferramentas MCP create_playbook e run_playbook; consulte a referência das 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 só vez, do lado da conversa
Criar um modelo de pipeline: quando precisa de lógica que um playbook não consegue expressar
Monitorizar execuções de pipeline: a vista do motor de um plano aprovado

Conceitos relacionados

Orquestração