Como orquestrar múltiplos AI agents sem virar caos

A maior parte do que o mercado chama de "multi-agent orchestration" é três prompts encadeados num loop. Funciona em demo. Quebra em produção. Esse artigo mostra o que faz a diferença: framework com authority delegation, Constitution explícita e quality gates entre handoffs. Os números do AIOX estão aqui, e a estrutura pode ser replicada em ~4 horas para um time de 1 a 3 devs.

Por que orquestrar agents é diferente de chamar uma API em loop?

Chamar uma API LLM em loop é automação. Orquestrar agents é coordenar entidades com responsabilidade própria, autoridade própria e contexto próprio. A diferença não é semântica. É arquitetural.

Quando o operador trata um agent como função que recebe input e devolve output, ele está usando o agent como serviço. Isso é o que LangChain, CrewAI e AutoGen oferecem na superfície. Funciona para tasks isoladas. Quebra quando dois agents precisam tocar o mesmo recurso, quando um agent precisa decidir baseado no estado de outro, ou quando o sistema precisa rastrear quem fez o quê e por quê.

Orquestração real implica três contratos: cada agent tem authority exclusiva sobre alguma coisa, cada handoff entre agents passa por um gate de qualidade, e cada decisão é traceável. Sem esses contratos, multi-agent é só um chatbot com mais latência.

O que é authority delegation e por que ela é a peça que falta?

Authority delegation é o princípio de que cada agent tem responsabilidades exclusivas que nenhum outro pode executar. No framework AIOX, isso é Constitution Art. III. Em código real, parece com isso: só @devops faz git push, só @db-sage executa migration, só @architect aprova mudança de arquitetura.

Em 7.500+ sessões Claude Code, observei o padrão claro: agents sem authority delegation multiplicam hallucination junto com o volume. Quando qualquer agent pode tocar qualquer coisa, todos viram médios. Quando autoridade é exclusiva, cada agent fica especialista no que delega.

A peça que o mercado de multi-agent ignora é exatamente essa: agents precisam de accountability, não só de capability. LangGraph dá controle de fluxo. CrewAI dá role abstraction. Nenhum dos dois força contrato de autoridade exclusiva. Resultado: dois agents fazendo db.migration em paralelo, schema quebrado, três horas para descobrir qual foi.

A solução é mais simples do que parece. Cada agent declara em config o que ele pode fazer com exclusividade. O orquestrador (chief) recebe pedidos e roteia para o agent correto. Se outro agent tenta executar fora da autoridade, falha rápido com erro explícito. Não é mágica. É contrato.

Como o framework AIOX estrutura orquestração em 8 layers?

AIOX organiza agents em 8 camadas hierárquicas, da identidade do negócio (L1) até evolução do próprio framework (L8). Cada layer define escopo, propriedade e ciclo de vida. Agents existem em L2 (Execution), mas operam dentro das constraints das camadas acima.

Na prática, isso vira uma estrutura clara. L1 Business define o "porquê" (mission, ICP, oferta). L2 Execution agrupa agents em squads (copy, design, dev, devops, qa). L3 Product roda apps reais. L7 Governance é a Constitution que ninguém viola. Agents podem propor mudanças em L7, mas só o operador humano aprova.

No AIOX Hub, esse modelo está rodando com 53 squads e 473 agentes registrados. Não rodam todos ao mesmo tempo. Em pico, 280 simultâneos. Em rotina, 140. O número absoluto importa menos do que o fato de que cada um tem authority isolada e handoff explícito.

Quem está começando não precisa de 53 squads. Precisa de quatro: @architect, @dev, @qa, @devops. Esse é o squad mínimo viável. Cada um com authority própria, cada handoff entre eles documentado em arquivo de contrato. Comparativo completo está em BMAD-METHOD vs AIOX.

Quais agents rodam em paralelo e quais devem ser sequenciais?

A regra é direta: phases independentes podem ser paralelas, phases com dependência são sequenciais. O erro comum é tratar isso como decisão de performance. Não é. É decisão de correção.

Independente significa que o output de um agent não muda o input de outro. Exemplo: três pesquisas de mercado em domínios distintos, cada uma feita por um analyst diferente. Saída de uma não afeta saída de outra. Pode rodar em paralelo. Quatro forks ao mesmo tempo, 4x speed-up.

Dependente significa que o agent B precisa de fato do output do agent A. Exemplo: @architect decide stack, @dev implementa baseado na stack, @qa testa a implementação, @devops deploya o que passou. Cada step lê o anterior. Paralelizar quebra a cadeia. Mantém sequencial.

Tem um terceiro caso, que é o mais delicado: phases que parecem independentes mas tocam o mesmo recurso compartilhado. Dois agents escrevendo no mesmo banco de dados em paralelo é race condition. Dois agents escrevendo em arquivos diferentes não é. Authority delegation resolve isso na origem: só um agent tem permissão de escrever no recurso. Os outros propõem; ele decide.

Como evitar race conditions e authority drift entre agents?

Race condition em multi-agent acontece quando dois agents tentam modificar o mesmo recurso ao mesmo tempo, sem coordenação. Resultado depende de timing, e timing varia. Bug que aparece uma vez em dez execuções é o pior tipo.

A primeira mitigação é authority delegation. Se só @db-sage faz migration, ninguém mais pode disparar db.migrate em paralelo. O outro agent que precisa de schema novo emite handoff: documenta o que precisa, salva em docs/migrations-pending/, e termina. @db-sage lê a fila, decide, executa. Linear. Sem race.

A segunda mitigação é observability. Cada handoff entre agents é registrado com timestamp, agent origem, agent destino, payload e verdict. Em sessão real, isso vira um log auditável. Quando algo dá errado, você lê o log de trás para frente até achar o ponto onde dois agents tomaram decisões conflitantes. No AIOX, esse padrão está em outputs/content-geo/missions/{mission-id}/phase-*.yaml: um arquivo por phase, traceável end-to-end.

Authority drift é o irmão silencioso. Acontece quando um agent começa a executar coisas fora do escopo declarado, e ninguém percebe. Mitigação é hook que valida authority antes de cada operação sensível. No AIOX Hub, hooks bloqueiam git push se o agent ativo não for @devops. Bloqueiam migration se não for @db-sage. Drift detectado no momento da tentativa, não após o estrago.

Como medir qualidade quando muitos agents tocam o mesmo código?

Quality gates são o segundo contrato fundamental de orquestração real, depois de authority. A regra é simples: nenhum handoff entre agents é aceito sem passar pelo gate.

No AIOX, cada story passa por quatro gates obrigatórios. @po valida draft antes de virar Ready (10-point checklist). @dev implementa, mas só completa quando typecheck e lint passam. @qa review com sete checks (code review, testes, ACs, regressions, performance, security, docs). @devops só deploya o que passou nos três gates anteriores. Sem PASS, sem deploy.

A diferença entre isso e "review humano" é que os gates são executáveis. Lint não é opinião. Typecheck é binário. Test coverage é número. Cada agent recebe feedback objetivo, refaz se necessário, e só avança quando o gate dá verde. Subjetividade fica reservada para os pontos onde ela é inevitável (decisão de arquitetura, prioridade de produto), e mesmo nesses casos a decisão fica registrada como ADR (Architecture Decision Record).

A consequência prática é que adicionar um quinto agent ao squad não adiciona caos proporcional. Adiciona ruído proporcional ao volume de handoffs, mas o gate filtra. Em escala, isso é o que separa squads que escalam de squads que viram comitê.

Quais 3 armadilhas reais quebram orquestração em produção?

A primeira armadilha é tratar agent como função pura. Função pura recebe input, devolve output, sem efeito colateral. Agent não é função pura. Agent tem context, lê estado externo, modifica estado externo. Quando você trata como função, você ignora o que ele realmente faz, e o sistema falha de formas que o código não explica.

A segunda armadilha é authority drift sem detecção. Em projetos pequenos, o time fundador conhece todos os agents e pega drift por inspeção. Em projetos médios, ninguém lê todos os logs. Sem hook automatizado que rejeita operações fora da authority, drift acumula até o dia que um agent executa algo destrutivo (delete, drop, force push) achando que tem permissão.

A terceira armadilha é hallucination scaling sem Constitution. LLMs alucinam. Em volume baixo, alucinação é raro. Em volume alto (centenas de chamadas por hora), alucinação vira certeza estatística: vai acontecer. Sem Constitution que define o que é proibido (não invente APIs, não modifique schema sem migration story, não execute em produção sem @devops), o agent inventa solução, executa, quebra. Constitution não impede a alucinação. Impede que ela vire ação.

Mitigação para as três é a mesma estrutura: authority explícita por agent, gates entre handoffs, Constitution publicada. Sem estrutura, o problema não é se vai quebrar. É quando.

Como começar: setup mínimo de orquestração em ~4 horas?

Esqueça por agora 53 squads e 473 agentes. Para um time de 1 a 3 devs, o setup mínimo é quatro agents, uma Constitution e um arquivo de handoff contract. Tempo realista: 3 a 5 horas para deixar funcionando.

Step 1 (60 min). Crie quatro arquivos de agent em .claude/agents/ (ou estrutura equivalente do seu IDE): architect.md, dev.md, qa.md, devops.md. Cada um declara em frontmatter o que pode fazer, o que não pode, e que handoff espera receber. Use o template do framework AIOX como base; ele já vem com authority delegation declarado. Tempo de 60 minutos é realista para alguém que nunca configurou agent antes; quem já tem familiaridade com persona files termina em 20.

Step 2 (45 min). Escreva uma Constitution mínima em .constitution.md. Cinco regras bastam para começar: (1) authority delegation respeitada, (2) só @devops faz push, (3) story-driven (toda mudança referencia story), (4) no invention (specs traçam para requirements), (5) quality first (lint e typecheck passam antes de merge). Cinco regras pequenas funcionam. Cinquenta regras viram regulamento que ninguém lê.

Step 3 (30 min). Configure hooks que enforçam authority. No mínimo: hook que bloqueia git push quando o agent ativo não é @devops, hook que bloqueia edição de migration quando não é @db-sage. Hooks são scripts simples (shell ou Node), ficam em .claude/hooks/, e param a operação antes da execução.

Step 4 (90 min). Materialize o primeiro handoff. Pegue uma feature pequena (formulário de contato, endpoint REST simples). @architect propõe arquitetura em arquivo de spec, descrevendo decisão de stack, modelo de dados e contrato de API. @dev lê o spec, implementa, e quando completa cria handoff em docs/handoffs/ listando arquivos modificados, testes adicionados e itens pendentes. @qa lê handoff, roda os sete checks, devolve verdict (PASS, CONCERNS, FAIL ou WAIVED) com observações. @devops lê verdict, deploya se PASS, retorna ciclo se FAIL.

Você observa o ciclo, ajusta o que estiver áspero, documenta o que aprendeu. Vai sentir desconforto na primeira execução. Vai querer pular um gate. Não pule. O ganho do framework é exatamente esse: estruturar o trabalho em pontos onde a tentação humana é cortar caminho.

Em quatro horas, você tem multi-agent orchestration funcionando com governance real. O resto é escala. AIOX começou assim em projeto único, com quatro agents e uma Constitution de cinco regras. 280 agentes simultâneos vieram depois, ao longo de meses, com a estrutura provada em escala menor antes de qualquer expansão. A ordem importa. Estrutura sustenta volume. Volume sem estrutura cria caos rápido.

Próximo passo

O framework AIOX é open source MIT. Não é plataforma, não tem lock-in, não tem signup. Você pega o repositório, copia a estrutura de agents e Constitution para o seu projeto, e adapta. O contexto completo do "porquê" desse design está em Por que a AIOX existe.

Se você está decidindo entre AIOX e outras opções (BMAD-METHOD, LangGraph, CrewAI), o comparativo técnico de 5 frameworks está em BMAD-METHOD vs AIOX: comparação técnica. 50 práticas comparadas estão em BMAD vs AIOX: 50 práticas.

Estrutura primeiro. Escala depois. É a ordem que funciona.