Orquestração

Um único agente é bom em uma coisa. Alguns pedidos são maiores do que isso: “pesquise o mercado de X e escreva um documento de posicionamento”, “lance esta funcionalidade de ponta a ponta”, “audite este módulo e corrija o que encontrar”. Uma orquestração é como o Control Center lida com esses pedidos: um orquestrador (normalmente seu agente CEO) propõe um plano de toda a equipe, você aprova uma vez e um materializador determinístico o transforma em um pipeline que faz o trabalho.

Ela fica entre as duas formas existentes de fazer o trabalho:

Quando você quer…	Use
Passar uma tarefa a um agente	Uma mensagem em um espaço
Codificar à mão um processo que você já conhece	Um modelo de pipeline
Dizer o objetivo e deixar a equipe descobrir o plano	Uma orquestração

O formato de uma proposta

Quando você dá um objetivo ao orquestrador, ele retorna um OrchestrationProposal estruturado: um plano tipado que o app pode validar e executar, em vez de prosa livre. Uma proposta tem:

Objetivo: seu pedido de alto nível, reafirmado.
Funções: quem faz o trabalho. Cada função é um agente existente que você escolhe ou uma nova contratação que a orquestração cria na aprovação.
Subtarefas: o trabalho, dividido em um DAG de tickets.
Pesquisa (opcional): uma fase de pesquisa que roda primeiro e alimenta o restante.
Discussão (opcional): uma rodada delimitada em que cada função publica uma posição estruturada antes de o trabalho começar.
Síntese: a etapa final que produz o entregável.
Orçamento: um teto de custo declarado.

Onde você a revisa

Duas superfícies mostram a mesma orquestração.

O cartão de proposta fica na conversa que produziu o plano. É uma única mensagem que é renderizada de novo ao longo de todo o ciclo de vida — proposta, em execução, concluída — com as ações de aprovar e cancelar sobre ele.

O Plan Studio é o editor: um canvas de DAG, um inspetor de nós, uma gaveta de revisões e diffs e a barra de aprovação que carrega a estimativa. Ele abre como uma aba de editor diretamente a partir desse cartão. Deliberadamente não há um item “Planos” na barra lateral; /plans e /plans/:kind/:id existem como links diretos para compartilhamento.

A aprovação é exclusiva do operador. Não há ferramenta MCP para isso: um agente pode propor (propose_orchestration), enviar um plano (submit_plan) ou instanciar um playbook (run_playbook), mas só um humano aprova. Revisões iniciadas por agentes ainda passam por limitação de taxa com um período de espera de dois minutos, de modo que um loop de replanejamento se agrupa em vez de inundar seu feed.

O que você pode alterar antes de aprovar é o que o inspetor de nós expõe: alterar o título ou reescrever uma subtarefa, mudar qual função é responsável por ela, religar suas dependências, editar seu esquema de saída ou excluir o nó de vez. Nós estruturais (pesquisa, discussão, síntese) e nós que já foram executados são somente leitura. Você não pode fixar uma função a um agente nomeado específico nem editar o orçamento pelo editor.

Dois editores em um mesmo plano são resolvidos por concorrência otimista, não por mesclagem. Toda edição carrega a base_revision contra a qual foi feita; uma edição baseada em uma revisão obsoleta é recusada com “o plano avançou”, em vez de sobrescrever silenciosamente a de outra pessoa. Rebobinar também não é uma exclusão — ele acrescenta a proposta mais antiga como uma nova revisão, então a linha do tempo de revisões só cresce.

Estimativas honestas, ou nenhuma

A estimativa na barra de aprovação é construída a partir do histórico real de execuções concluídas de cada função, como uma faixa interquartil (p25–p75). Os totais de custo somam os nós estimáveis; a duração é o caminho crítico pelo DAG, e não a soma (ramos paralelos se sobrepõem).

Um nó cuja função não tem histórico de execuções concluídas informa sampleSize: 0 e intervalos nulos. Isso é renderizado exatamente assim — desconhecido —, nunca como um valor pontual fabricado, porque uma estimativa em que você não pode confiar é pior do que nenhuma estimativa. Quando alguns nós têm histórico e outros não, o total é marcado como parcial. O raio de impacto aparece somente quando um nó declara referências de proveniência symbol ou file; um nó sem elas permanece “desconhecido”, em vez de inferir a partir da prosa.

Uma aprovação e, depois, execução determinística

Esta é a ideia central: o agente planeja; uma função determinística executa. Quando você aprova, o OrchestrationMaterializer, uma função pura sem LLM e sem I/O, converte a proposta em um pipeline real. Dados a mesma proposta e as mesmas funções resolvidas, ele sempre produz o mesmo DAG. Isso importa porque o pipeline gerado herda tudo o que o motor já faz de graça: suspensão e retomada entre reinícios, recuperação de falhas, agregações de custo e tokens por execução e a interface de detalhes da execução.

A aprovação também cria a estrutura de apoio de que o trabalho precisa:

contrata quaisquer funções marcadas como novas (e registra os ids dos agentes contratados para que uma falha no meio da aprovação possa ser retomada sem contratações duplicadas)
uma equipe que agrupa as funções
um projeto que arquiva o ticket pai
o modelo de pipeline + execução que impulsiona tudo isso

O ciclo de vida

proposed → approved → executing → synthesizing → completed
                  ↘                 ↘              failed
                   ↘                 ↘            cancelled

Status	Significado
`proposed`	O plano está pronto e aguardando sua única aprovação antecipada
`approved`	Você o aprovou; a materialização está em andamento (contratações, equipe, projeto, pipeline)
`executing`	O pipeline gerado está em execução: subtarefas, discussão, trabalho
`synthesizing`	As subtarefas terminaram; a etapa de síntese está produzindo o entregável
`completed`	Concluído: o ticket pai é marcado como concluído e o entregável é publicado no espaço compartilhado
`failed`	A materialização falhou, ou a execução do pipeline gerado falhou
`cancelled`	Você o cancelou

Um número de revisão monotônico acompanha a proposta à medida que o orquestrador a revisa enquanto ela ainda está proposed; o app registra qual revisão você aprovou. propose_orchestration recusa uma revisão quando o status já não é proposed.

Uma orquestração sempre é aberta em torno de um ticket pai e compartilha um único espaço de discussão, de modo que todo o esforço é rastreável a um único item de trabalho e a equipe conversa em uma só sala.

O que acontece quando ela termina

Um ouvinte mantido ativo observa o pipeline gerado e mapeia seu estado terminal de volta para a orquestração e o ticket pai, de modo que a conclusão e a falha apareçam nos lugares que você já acompanha. O recurso de orquestração não precisa de seu próprio motor de execução.

Você pode cancelar uma orquestração a qualquer momento; o cancelamento desmonta o trabalho em andamento.

Veja também

Pipelines e automação: o motor em que uma orquestração materializada é executada
Tickets e delegação: o ticket pai no qual uma orquestração é ancorada
O modelo de agentes: as funções que uma orquestração preenche ou contrata
Executar uma orquestração
Trabalhar no Plan Studio