Revisão de Orquestração Multi-Agente

Visão Geral

Revise uma orquestração como uma máquina de estados distribuída, não como uma lista de papéis de agente. O objetivo é provar que cada tarefa tem um proprietário, cada transição de estado tem uma autoridade e cada resultado terminal é alcançável sem efeitos duplicados, trabalho perdido ou loops ilimitados.

Esta habilidade revisa um projeto ou implementação. Não inicie workers, não modifique filas, não cancele execuções, não altere configurações de produção ou implante correções, a menos que o usuário solicite a implementação separadamente.

Quando Usar

• Revisando projetos de supervisor/worker, planejador/executor, debate, enxame, grafo ou agentes hierárquicos.
• Introduzindo ramificações paralelas, subagentes, ferramentas MCP, execução durável, memória, checkpoints ou portões com intervenção humana (human-in-the-loop).
• Diagnosticando trabalho duplicado, contexto desatualizado, deadlocks, livelocks, corridas de ramificação (branch races), retentativas descontroladas ou propriedade ambígua.
• Decidindo se uma tarefa complexa deve ser paralela, sequencial, delegada ou mantida em um único agente.

Não o use para uma única chamada de ferramenta independente ou um pipeline simples sem concorrência, estado compartilhado, retentativas ou limite de delegação.

Capturar o Contrato de Orquestração

Solicite ou derive:

• objetivo de negócio, critérios de sucesso e não-objetivos;
• grafo de tarefas com IDs de tarefa estáveis e arestas de dependência;
• papéis de agente, capacidades, permissões, ferramentas e limites de sandbox;
• esquema de estado, fonte da verdade, propriedade, versionamento e persistência;
• envelopes de mensagem e contratos de entrega de artefatos;
• políticas de despacho, junção, retentativa, tempo limite, cancelamento, compensação e escalonamento;
• orçamentos de token, custo, concorrência, tempo de relógio (wall-clock) e efeitos externos;
• estados terminais e evidências necessárias para entrar neles.

Marque cada campo como declarado, inferido ou ausente. Nunca invente comportamento de framework a partir de nomes de papéis como "supervisor" ou "validador".

Decidir se a Execução Multi-Agente é Justificada

A execução multi-agente é justificada quando as tarefas têm saídas verificáveis independentemente e podem ser isoladas por arquivos, artefatos, permissões ou escopos de somente leitura. Mantenha o trabalho sequencial quando uma ramificação consome a saída em evolução de outra, todos os workers devem editar o mesmo estado, ou o custo de coordenação excede o ganho paralelo esperado.

Pontue cada tarefa candidata:

Se alguma dimensão não for resolvida, recomende serialização ou um mecanismo de coordenação explícito em vez de concorrência otimista.

Modelar a Máquina de Estados

Represente o estado da tarefa explicitamente:

pending -> ready -> leased -> running -> succeeded
                         |        |-> retry_wait -> ready
                         |        |-> needs_human
                         |        |-> failed
                         |        |-> cancelled
                         |-> lease_expired -> ready

Para cada registro de transição:

• ator autorizado;
• pré-condição compare-and-set (comparar e definir) ou versão de estado esperada;
• campos persistidos e referências de artefatos;
• evento emitido e chave de deduplicação;
• orçamento consumido;
• comportamento de tempo limite ou concessão (lease);
• caminho de compensação ou recuperação.

Rejeite projetos onde workers sobrescrevem todo o objeto de estado compartilhado ou onde "concluído" é uma mensagem de formato livre em vez de uma transição validada.

Revisar Propriedade de Tarefa e Estado

Cada tarefa precisa de um proprietário de concessão (lease) ativo, um token de bloqueio (fencing token) ou uma tentativa monotonicamente crescente, e uma chave de idempotência estável para efeitos externos. Uma retentativa pode repetir o cálculo, mas não deve repetir um efeito comprometido.

Use um destes padrões de estado deliberadamente:

• Coordenador de escritor único: workers retornam propostas ou artefatos; apenas o coordenador modifica o estado canônico.
• Estado particionado: cada worker possui um namespace区 (disjunto); um joiner escreve o agregado.
• Log de eventos com redutores: workers anexam eventos imutáveis; redutores determinísticos derivam o estado.

Marque edições de checkout compartilhado, blobs JSON de "última escrita vence" (last-write-wins), memória global mutável e resumos não versionados como riscos de colisão.

Revisar Despacho e Entregas

Um envelope de despacho deve vincular:

{
  "run_id": "run-7",
  "task_id": "backend-3",
  "attempt": 2,

…