Executar agentes em paralelo

Este guia mostra como executar vários agentes ao mesmo tempo sem que estes se sobrescrevam uns aos outros.

A unidade de isolamento é o espaço, não o agente

Quando o trabalho começa num espaço, o Control Center aprovisiona um checkout copy-on-write por repo registado sob a raiz própria desse espaço, num branch derivado do modelo de branch do espaço de trabalho. Cada agente do espaço recebe então o seu próprio diretório de trabalho overlay — mas os overlays partilham o diretório repos/ desse espaço.

Por conseguinte:

Dois agentes em espaços diferentes trabalham em checkouts diferentes, em branches diferentes. Isso é isolamento a sério.
Dois agentes no mesmo espaço trabalham no mesmo checkout, no mesmo branch. Os caminhos dos overlays diferem, pelo que o bloqueio de caminho do despacho (que serializa as execuções apenas quando estas pedem o diretório de trabalho idêntico) também não os serializa. Podem escrever os mesmos ficheiros ao mesmo tempo.

A regra que daí decorre: um espaço por tarefa em paralelo.

Executar tarefas em paralelo — espaços separados

Abra um espaço com o agente A e envie-lhe uma tarefa.
Abra um segundo espaço com o agente B e envie-lhe uma tarefa diferente.
Ambos são despachados imediatamente, cada um no checkout do seu espaço e no seu próprio branch.

Esta é a receita a usar sempre que os agentes forem editar ficheiros.

Trabalhar em conjunto num espaço — várias menções

Num único espaço, mencione com @ mais do que um agente:

@alice refactor the auth module. @bob review what alice lands.

Ambos os agentes são despachados em paralelo e transmitem para o mesmo espaço, etiquetados pelo remetente. Como partilham o checkout do espaço, use isto para colaboração — um a escrever, outro a ler, ou dois agentes a raciocinar sobre a mesma árvore —, e não para duas edições independentes.

Fazer fan-out a partir de um pipeline

O modelo pr_review integrado é o exemplo incluído de um fan-out: vários nós revisores são executados em simultâneo a partir de um único disparador e um nó Consolidate (join) reúne as suas constatações num único relatório. Execute-o no ecrã de pipelines e cada revisor é despachado em paralelo.

O editor de pipelines oculta a sentinela terminal e volta a ligá-la para aguardar por cada destino ativo quando adiciona ou liga um passo, pelo que os branches que desenhar são mesmo executados.

Acompanhar a execução

Observabilidade → Ao vivo (rodapé da barra lateral → Observabilidade e, depois, o separador Ao vivo) mostra a lista de agentes deste espaço de trabalho, atualizada a cada segundo: estado (em execução / inativo / estacionado / abortado), o que cada um está a fazer, os tokens e o custo da sua última execução e um controlo de encerramento para um processo em execução. Selecionar uma linha acopla uma gaveta de transcrição em direto.

Definições → Espaço de trabalho → Agentes mostra a mesma lista com um vocabulário de estado diferente, orientado para a atenção, derivado do histórico de execuções de cada agente — em execução, bloqueado, falhou, inativo, nunca executado —, ordenado de modo a que tudo o que precisa de atenção suba para o topo. O separador Registos de cada agente contém o seu próprio histórico de execuções.

Ambas as superfícies têm âmbito limitado ao espaço de trabalho ativo.

Lidar com conflitos

Entre espaços, cada espaço está no seu próprio branch, pelo que uma colisão surge como um conflito de merge normal do Git quando fizer merge da segunda pull request. Resolva-o como resolveria qualquer conflito de merge.

Dentro de um espaço não há fronteira de branch nem bloqueio: os agentes estão a escrever os mesmos ficheiros em direto e o perdedor é simplesmente sobrescrito. Se der por si a querer que dois agentes editem num só espaço, divida antes o trabalho por dois espaços.

Para reduzir colisões de qualquer das formas:

Dê a cada agente um âmbito distinto — ficheiros diferentes, módulos diferentes.
Use o grafo de código para verificar o que uma alteração toca antes de despachar. Consulte Pesquisar código com o grafo de código.
Reveja e faça merge da pull request de cada agente sem demora.

Considerações sobre recursos

Cada agente em execução custa:

Um checkout de espaço — negligenciável em disco enquanto o copy-on-write estiver disponível; no Windows, um git worktree. Um sistema de ficheiros que não consiga fazer reflink faz falhar o aprovisionamento em vez de copiar.
Um processo no anfitrião do servidor
Tokens de modelo, que se acumulam por agente

Os custos aparecem em Observabilidade → Resumo. Note que um turno interativo normal não tem limite de gastos; consulte Gerir custos para os dois comandos que têm um.