Executar agentes em paralelo

Este guia mostra como executar vários agentes ao mesmo tempo sem que eles sobrescrevam o trabalho uns dos outros.

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

Quando o trabalho começa em um espaço, o Control Center provisiona um checkout copy-on-write por repositório registrado sob a raiz própria daquele espaço, em um branch derivado do modelo de branch do espaço de trabalho. Cada agente do espaço recebe então seu próprio diretório de trabalho overlay — mas os overlays compartilham o diretório repos/ daquele espaço.

Portanto:

Dois agentes em espaços diferentes trabalham em checkouts diferentes, em branches diferentes. Isso é isolamento de verdade.
Dois agentes no mesmo espaço trabalham no mesmo checkout, no mesmo branch. Os caminhos de overlay deles são diferentes, então o bloqueio de caminho do despacho (que serializa as execuções apenas quando elas solicitam o mesmo diretório de trabalho) também não os serializa. Eles podem gravar os mesmos arquivos 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 a ele uma tarefa.
Abra um segundo espaço com o agente B e envie a ele outra tarefa.
Os dois 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 arquivos.

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

Em um único espaço, mencione com @ mais de um agente:

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

Os dois agentes são despachados em paralelo e transmitem no mesmo espaço, etiquetados pelo remetente. Como compartilham o checkout do espaço, use isto para colaboração — um escrevendo, outro lendo, ou dois agentes raciocinando 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 ao mesmo tempo a partir de um único gatilho, e um nó Consolidate (join) reúne os achados deles em um único relatório. Execute-o na tela de pipelines e cada revisor será despachado em paralelo.

O editor de pipelines oculta a sentinela terminal e a reconecta para aguardar cada destino ativo quando você adiciona ou conecta uma etapa, de modo que os ramos que você mesmo desenha de fato são executados.

Acompanhar a execução

Observabilidade → Ao vivo (rodapé da barra lateral → Observabilidade e, depois, a aba Ao vivo) mostra a lista de agentes deste espaço de trabalho, atualizada a cada segundo: status (Em execução / Inativo / Estacionado / Abortado), o que cada um está fazendo, os tokens e o custo da última execução dele e um controle de encerramento para um processo em execução. Selecionar uma linha acopla uma gaveta com a transcrição ao vivo.

Configurações → Espaço de trabalho → Agentes mostra a mesma lista com um vocabulário de status diferente, que prioriza a atenção e deriva do histórico de execuções de cada agente — Em execução, Bloqueado, Falhou, Inativo, Sem execuções —, ordenada de modo que tudo que precisa de atenção suba para o topo. A aba Registros de cada agente contém o próprio histórico de execuções dele.

As duas superfícies têm escopo restrito ao espaço de trabalho ativo.

Lidar com conflitos

Entre espaços, cada espaço está no seu próprio branch, então uma colisão aparece como um conflito de merge comum do Git quando você faz 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 gravando os mesmos arquivos ao vivo e o perdedor simplesmente é sobrescrito. Se você quiser dois agentes editando em um mesmo espaço, divida o trabalho em dois espaços.

Para reduzir colisões em qualquer dos casos:

Dê a cada agente um escopo distinto — arquivos 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.
Revise e faça merge da pull request de cada agente prontamente.

Considerações sobre recursos

Cada agente em execução custa:

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

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