Orquestração

Um único agente é bom numa só coisa. Alguns pedidos são maiores do que isso: «investigar o mercado de X e escrever um documento de posicionamento», «lançar esta funcionalidade de ponta a ponta», «auditar este módulo e corrigir o que encontrar». Uma orquestração é a forma como o Control Center trata esses casos: um orquestrador (normalmente o seu agente CEO) propõe um plano de toda a equipa, você aprova-o uma única vez e um materializador determinístico transforma-o num pipeline que faz o trabalho.

Situa-se entre as duas formas existentes de realizar trabalho:

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

A forma de uma proposta

Quando dá um objetivo ao orquestrador, este devolve uma OrchestrationProposal estruturada: um plano tipado que a aplicação pode validar e executar, em vez de texto livre. Uma proposta tem:

Objetivo: o seu pedido de alto nível, reformulado.
Papéis: quem faz o trabalho. Cada papel é um agente existente que escolhe, ou uma nova contratação que a orquestração cria aquando da aprovação.
Subtarefas: o trabalho, dividido num DAG de tickets.
Investigação (opcional): uma fase de investigação que corre primeiro e alimenta o resto.
Discussão (opcional): uma ronda delimitada em que cada papel publica uma posição estruturada antes de o trabalho começar.
Síntese: o passo final que produz o entregável.
Orçamento: um limite de custo declarado.

Onde a revê

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

O cartão de proposta vive na conversa que produziu o plano. É uma única mensagem que se volta a renderizar ao longo de todo o ciclo de vida — proposta, em execução, concluída — com as ações de aprovar e cancelar na própria mensagem.

O Plan Studio é o editor: uma área de desenho de DAG, um inspetor de nós, uma gaveta de revisões e diferenças e a barra de aprovação com a estimativa. Abre como separador de editor diretamente a partir desse cartão. Não existe deliberadamente um item «Planos» na barra lateral; /plans e /plans/:kind/:id existem como ligações diretas para partilha.

A aprovação é exclusiva do operador. Não existe nenhuma ferramenta MCP para isso: um agente pode propor (propose_orchestration), submeter um plano (submit_plan) ou instanciar um playbook (run_playbook), mas só um humano aprova. As revisões iniciadas por agentes estão ainda sujeitas a um período de espera de dois minutos, pelo que um ciclo de replaneamento se agrega em vez de inundar o seu fluxo de atividade.

Aquilo que pode alterar antes de aprovar é o que o inspetor de nós expõe: mudar o título ou reescrever uma subtarefa, mudar o papel que a detém, religar as respetivas dependências, editar o respetivo esquema de saída ou eliminar o nó por completo. Os nós estruturais (investigação, discussão, síntese) e os nós que já foram executados são só de leitura. A partir do editor, não pode fixar um papel a um agente específico com nome nem editar o orçamento.

Dois editores no mesmo plano são resolvidos por concorrência otimista, e não por fusão. Cada edição transporta a base_revision sobre a qual foi feita; uma edição baseada numa revisão desatualizada é recusada com «o plano avançou» em vez de substituir silenciosamente a de outra pessoa. Rebobinar também não é eliminar — acrescenta a proposta mais antiga como uma nova revisão, pelo que a linha temporal de revisões só cresce.

Estimativas honestas, ou nenhumas

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

Um nó cujo papel não tem histórico de execuções concluídas comunica sampleSize: 0 e intervalos nulos. Isso é apresentado exatamente como isso — desconhecido —, nunca como um valor pontual inventado, porque uma estimativa em que 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 só aparece quando um nó declarou referências de proveniência symbol ou file; um nó sem elas permanece «desconhecido», em vez de inferir a partir do texto.

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

Esta é a ideia central: o agente planeia; uma função determinística executa. Quando aprova, o OrchestrationMaterializer, uma função pura sem LLM e sem I/O, converte a proposta num verdadeiro pipeline. Dada a mesma proposta e os mesmos papéis resolvidos, produz sempre o mesmo DAG. Isso é importante porque o pipeline gerado herda tudo o que o motor já faz gratuitamente: suspensão e retoma entre reinícios, recuperação de falhas, totais de custo e de tokens por execução e a interface de detalhe da execução.

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

contrata todos os papéis marcados como novos (e regista os identificadores dos agentes contratados, para que uma falha a meio da aprovação possa ser retomada sem contratações duplicadas)
uma equipa que agrupa os papéis
um projeto onde fica arquivado o ticket principal
o modelo de pipeline + execução que impulsiona tudo isto

O ciclo de vida

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

Estado	Significado
`proposed`	O plano está pronto e à espera da sua aprovação única e prévia
`approved`	Aprovou-o; a materialização está em curso (contratações, equipa, projeto, pipeline)
`executing`	O pipeline gerado está em execução: subtarefas, discussão, trabalho
`synthesizing`	As subtarefas terminaram; o passo de síntese está a produzir o entregável
`completed`	Concluído: o ticket principal é marcado como concluído e o entregável é publicado no espaço partilhado
`failed`	A materialização falhou, ou a execução do pipeline gerado falhou
`cancelled`	Cancelou-a

Um número de revisão monotónico acompanha a proposta à medida que o orquestrador a revê enquanto esta ainda está proposed; a aplicação regista qual foi a revisão que aprovou. propose_orchestration recusa uma revisão a partir do momento em que o estado já não é proposed.

Uma orquestração abre sempre contra um ticket principal e partilha um único espaço de discussão, para que todo o esforço seja rastreável a um único item de trabalho e a equipa converse numa só sala.

O que acontece quando termina

Um serviço de escuta mantido ativo vigia o pipeline gerado e mapeia o respetivo estado terminal de volta para a orquestração e para o ticket principal, para que a conclusão e a falha apareçam nos locais que já acompanha. A funcionalidade de orquestração não precisa de um motor de execução próprio.

Pode cancelar uma orquestração em qualquer altura; o cancelamento desmancha o trabalho em curso.

Ver também

Pipelines e automatização: o motor sobre o qual corre uma orquestração materializada
Tickets e delegação: o ticket principal em que uma orquestração é ancorada
O modelo de agentes: os papéis que uma orquestração preenche ou contrata
Executar uma orquestração
Trabalhar no Plan Studio