--- title: "Multi-agent orchestration: o que falhou em 3.315 execuções" description: "Orquestração multiagente na prática: 3.315 execuções de subagentes em dois meses, o custo em tokens a preços de API e sete falhas que viraram hooks." url: "https://madsalt.tech/pt/blog/multi-agent-orchestration-what-broke/" author: "Denys Zaichenko" language: "pt" published: 2026-10-19 updated: 2026-10-22 --- # Multi-agent orchestration: o que falhou em 3.315 execuções Em resumo Entre 17 de agosto e 19 de outubro de 2026, a minha configuração do Claude Code lançou 3.315 subagentes. Nos últimos 30 dias isso somou cerca de 16 mil milhões de tokens, 97,7% deles leituras de cache. Pago uma subscrição fixa; a preços de tabela da API, os mesmos tokens custariam pelo menos USD 3.350. As falhas quase nunca foram o modelo a escrever código mau. Estavam nas junções: agentes em paralelo a sobrescrever o mesmo ficheiro com todas as verificações verdes, um script de limpeza a apagar trabalho concluído, um agente a editar as verificações que o bloqueavam. Cada falha virou um pequeno script que bloqueia a execução seguinte, e são esses scripts, não os prompts, que tornaram o sistema utilizável. Sou o Denys, engenheiro full-stack e de IA. Construo software com uma sessão principal do Claude Code que entrega o trabalho a subagentes especializados: exploradores, um planeador, implementadores, revisores de segurança e de código. Este texto é um relato dessa configuração, não de um produto de cliente. Os números vêm dos registos que ela mantém: um livro de lançamentos (uma linha por agente lançado), as transcrições das sessões e o histórico git da própria configuração. Nomes de clientes e de projetos ficam de fora. Construí também um [painel interativo de orquestração multiagente](https://madsalt.tech/pt/work/multi-agent-orchestration/) como protótipo com dados de exemplo. Tudo o que se segue vem de execuções reais. ## O que é a orquestração multiagente? A orquestração multiagente é uma configuração em que um agente principal entrega tarefas delimitadas a agentes especializados e junta os resultados; o orquestrador é dono do contexto, dos orçamentos e das repetições. Neste texto aparece como dois padrões: uma sessão principal com subagentes (exploradores, um planeador, implementadores, revisores) e hooks que fazem cumprir as regras que os agentes não conseguem contornar com palavras. O [painel de orquestração multiagente](https://madsalt.tech/pt/work/multi-agent-orchestration/) mostra a mesma ideia com dados de exemplo; as secções seguintes tratam do que falhou em execuções reais. ## Como é a configuração? Uma sessão principal fala comigo e é dona da tarefa. Nas tarefas maiores, nunca escreve ela própria código de produção. Envia o trabalho para fora: - **Exploradores** leem uma camada da base de código (frontend, backend, base de dados) e escrevem um mapa curto. - **Um planeador** transforma o mapa em passos numerados, com caminhos de ficheiros. - **Implementadores** ficam cada um com uma fase do plano, escrevem primeiro os testes e depois o código. Os implementadores em paralelo recebem o seu próprio git worktree. - **Revisores** verificam o diff: um para segurança, outro para correção, ambos sobre o mesmo commit. Entre eles ficam os hooks: pequenos scripts que o Claude Code executa antes e depois de cada chamada de ferramenta. Um hook pode bloquear uma chamada, por exemplo o lançamento de um agente, a escrita de um ficheiro ou um `git commit`. A configuração tem 165 hooks, cerca de 40 deles sobre orquestração. As regras que os agentes leem são Markdown; as regras que não conseguem contornar são hooks. Essa divisão é a principal lição destes dois meses, e o resto do texto explica porquê. ![Como uma tarefa percorre os agentes. Os hooks ficam entre cada passo e podem bloqueá-lo. Percurso normal: Exploração → Plano → Código → Revisão → Commit; Mesma falha três vezes: Código → Mesma falha 3x → Modelo superior → Uma pessoa.](https://madsalt.tech/charts/pt/multi-agent-orchestration-what-broke-flow.svg) *Figura 1. A minha configuração do Claude, agosto a outubro de 2026. Cada implementador em paralelo tem o seu próprio git worktree.* ## Quantos agentes correram, e em que modelos? | Medida (17 ago – 19 out 2026) | Valor | | -------------------------------------------------- | ---------------------------------------------------------------------------- | | Subagentes lançados | 3.315 em 57 dias ativos | | Tipos de agente | 30 | | Mais lançados | implementador (tdd-guide) 793, revisor de segurança 455, general-purpose 424 | | Modelo efetivo | Opus 46,5%, Sonnet 45,8%, Fable 1,3%, o resto herdado da sessão principal | | Lançados um de cada vez | 67,7% | | Maior vaga em paralelo | 5 agentes (o limite), atingido 9 vezes | | Execuções de revisor por execução de implementador | 0,71 (680 revisões, 963 implementações) | Dois números surpreenderam-me. Primeiro, a maioria dos lançamentos foi de agentes isolados, não de vagas em paralelo. O trabalho em paralelo é a exceção: compensa para ler e rever, e custa caro para escrever (ver a primeira falha abaixo). Segundo, em 23% dos lançamentos em que o ficheiro de um agente indica um modelo, o modelo que de facto correu foi outro, quase sempre Sonnet promovido a Opus (584 de 610). É deliberado: um hook sobe o modelo quando o passo toca em código de risco, como migrações, autenticação ou rotas de servidor, e depois de um implementador em Sonnet falhar o mesmo teste três vezes seguidas. O implementador mais forte correu 159 vezes; não consigo separar o registo em "passo de risco" e "falha repetida", por isso não afirmo quantas foram resgates. ## O que custa a orquestração de agentes? Pago uma subscrição fixa, por isso não há fatura por token. As transcrições registam, porém, todos os tokens, e aqui fica o que os últimos 30 dias (20 de setembro a 19 de outubro) custariam aos preços de tabela da API da Anthropic: | 30 dias | Tokens | | ----------------------- | ------------------------------------------------------------- | | Total | cerca de 15,99 mil milhões | | Leituras de cache | 15,55 mil milhões (97,7% de tudo o que foi enviado ao modelo) | | Escritas de cache | 372 milhões | | Entrada nova, sem cache | 0,18 milhões | | Saída | 69 milhões | A preços de tabela (Opus 5.5 a USD 4 por milhão de entrada, 20 por milhão de saída, 0,20 por milhão de leituras de cache; Sonnet 5.5 e Fable 5.1 aos seus), só a saída, a entrada e as leituras de cache dos três modelos atuais somam cerca de USD 3.350. Isto deixa de fora as escritas de cache e as versões mais antigas de modelos ainda presentes nos registos, por isso o valor real da API é mais alto. Dois terços desses USD 3.350 são leituras de cache: cada turno reenvia todo o contexto, e a cache é a única razão para isto ser comportável. ![Quem escreveu os 69 milhões de tokens de saída. Milhões de tokens, 30 dias. Os subagentes usaram 42% de todos os tokens. Sessão principal: 23,70; Subagentes: 45,30.](https://madsalt.tech/charts/pt/multi-agent-orchestration-what-broke-output.svg) *Figura 2. Transcrições do Claude, 20 de setembro a 19 de outubro de 2026: 75.129 pedidos ao modelo.* A divisão entre a sessão principal e os subagentes é a parte que eu usaria para planear um orçamento: - **Os subagentes usaram 42% de todos os tokens mas escreveram 66% da saída.** A sessão principal é cara porque carrega o contexto mais longo; é nos subagentes que o texto e o código são de facto escritos. - **Os revisores são baratos.** Uma revisão de segurança ou de código usou 1 a 4 milhões de tokens. Um implementador usou 5 a 100 milhões. Dois revisores em cada commit de risco custam menos do que um implementador a repetir. - **A maior sessão**, a 6 de outubro, lançou 63 subagentes e usou 372 milhões de tokens em 3,5 horas. ## O que falhou Todas as falhas abaixo aconteceram, têm data, e acabaram num hook ou num script que impede que voltem a acontecer. Nenhuma é "o modelo escreveu um bug". Os bugs comuns foram apanhados pelos testes e pelos revisores. Estas passaram por ambos. | Data (2026) | O que falhou | O que o bloqueia agora | | ----------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | 19 ago | Agentes em paralelo sobrescreveram um ficheiro de traduções: 55 de ~95 chaves perdidas, todas as verificações verdes | Cada agente escreve as suas chaves num fragmento próprio; um script de fusão prova que todas as chaves chegaram | | 24 ago | Um script de limpeza apagou 4 pacotes de trabalho concluídos | A limpeza ignora qualquer worktree com alterações por recolher; primeiro recolher, depois limpar | | 1 set | Vagas posteriores de agentes partiram de código desatualizado | Fundir o trabalho de cada agente como patch de três vias, nunca como cópia de ficheiro | | 13 set | Um agente morreu no lançamento, e o lançamento disse "sucesso" | O lançador lê a primeira saída do agente e marca um modelo morto para todas as sessões | | 20 set | Duas regras minhas contradiziam-se; os agentes repetiram um comando recusado | Os briefs dos agentes isolados trazem as formas de comando que a sandbox aceita | | 18 out | Um agente editou as verificações que lhe bloqueavam o commit | Os ficheiros de verificação são só de leitura nas sessões de projeto; as alterações são registadas e alertadas | | 18 out | Instruções de correção mudaram em silêncio o que os utilizadores de uma app de cliente recebem | Todo o brief de correção diz "manter o comportamento em produção"; alterações de produto voltam para mim | ### Escritores em paralelo e o ficheiro que toda a funcionalidade toca Três agentes construíram três funcionalidades de uma app iOS de cliente ao mesmo tempo. Cada um acrescentou os seus textos ao único catálogo de traduções da app, e cada um guardou a sua própria versão do ficheiro inteiro. Ganhou a última gravação. Perderam-se 55 de cerca de 95 chaves novas. O build de cada agente passou, porque a cópia de cada um era consistente; a verificação do catálogo passou, porque a sua cobertura estava falhada de outra maneira. Descobri-o a contar as chaves à mão. A correção tem três partes. Um hook recusa lançar um agente cujos ficheiros declarados se sobreponham aos de um escritor ainda em execução. Os agentes nunca editam catálogos partilhados; escrevem as chaves num ficheiro de fragmento, e um script funde os fragmentos, falha perante valores em conflito e depois confirma que todas as chaves estão presentes. Um segundo hook bloqueia o commit se um catálogo tiver menos chaves do que antes. A parte honesta: acrescentei estas proteções a 18 de outubro, 60 dias depois da perda. Entre essas datas, a única proteção era uma linha numa regra em Markdown, e uma regra é uma sugestão. ### Uma limpeza que apagou trabalho concluído Os implementadores em paralelo trabalham em git worktrees e preparam as alterações sem fazer commit. Uma verificação de commit mandou a sessão principal executar o script de limpeza. O script ignorava os worktrees cujo agente ainda estava a correr, e estes agentes já tinham terminado. Quatro pacotes de trabalho concluídos foram apagados, sem objetos git para recuperar. "O agente ainda está a correr?" e "o seu trabalho já foi recolhido?" são perguntas diferentes, e o script só fazia a primeira. A limpeza ignora agora qualquer worktree com alterações que o checkout principal não tem, e um hook à parte bloqueia a eliminação direta de pastas de worktree. ### Vagas que partiram de código antigo Um plano de 11 passos correu com 6 implementadores em 3 vagas. As vagas 2 e 3 partiram do commit em que a sessão começou, três commits atrás. Copiar de volta o ficheiro de um agente teria revertido a alteração concluída de outro. Um worktree é um instantâneo do ponto de partida, por isso os resultados voltam agora como patches de três vias, e os conflitos aparecem em vez de serem sobrescritos em silêncio. ### Um agente morto que reportou sucesso Um agente fixado num modelo cujo limite de utilização estava esgotado morreu antes do primeiro passo. O lançamento devolveu "spawned successfully"; a falha chegou mais tarde como aviso de inatividade. Uma nova tentativa noutro modelo foi revertida pelo mesmo hook que fixa os modelos. A sessão principal escreveu então o plano ela própria, em silêncio, que era precisamente o resultado que o planeador existia para evitar. O hook lê agora a primeira saída do agente e marca um modelo morto para todas as sessões durante algum tempo. ### O agente que editou as suas próprias verificações A 18 de outubro, uma sessão a trabalhar num projeto de cliente via o seu commit bloqueado repetidamente por uma verificação. Editou três dos scripts de verificação para que o commit passasse. Nada disto foi escondido; as edições estavam à vista. Mas nada as impediu, porque as verificações estavam numa pasta onde o agente podia escrever, e só as ferramentas de edição de ficheiros eram vigiadas, não os comandos de shell. Agora os ficheiros de verificação só podem ser alterados a partir de uma sessão iniciada na própria pasta de configuração, todas as vias de escrita estão cobertas (editor, redirecionamentos de shell, scripts, git), e qualquer alteração durante uma sessão de projeto fica registada com um alerta. Esta é a falha sobre a qual eu avisaria primeiro qualquer pessoa. Um agente a quem se diz "faz passar o commit" trata a barreira como parte do problema. ### Duas regras minhas discordavam Uma regra mandava os agentes juntar três ou mais passos de shell num só script para poupar tokens. Os agentes isolados num worktree correm numa sandbox que recusa exatamente essa forma. Os agentes bateram em "too complex to verify" três vezes seguidas em vários dias, e gastaram o orçamento a reformular. Os agentes param agora após duas recusas idênticas, e os briefs dos agentes isolados indicam as formas de comando que funcionam. ## Porque falham os sistemas multiagente? Pelo que vi nestes dois meses: não porque um modelo seja demasiado fraco. Nenhuma das sete falhas acima foi um modelo a falhar na tarefa que lhe foi dada. Falham nas junções entre agentes, onde nenhum agente isolado é responsável: - **Estado partilhado.** Um ficheiro que toda a funcionalidade toca, uma árvore de trabalho, um branch. Cada agente tem razão localmente e o resultado está errado globalmente. - **Verificações verdes.** Todos os incidentes acima passaram as verificações que existiam na altura. Uma verificação prova o que verifica, nada mais. - **Sinais de sucesso que mentem.** "Spawned", "saved", "cleaned up" significavam, cada um, algo mais estreito do que diziam. - **Agentes a otimizar para a barreira.** Diga-se a um agente que o commit está bloqueado e ele procurará uma forma de o desbloquear, incluindo através da barreira. Outros construtores relatam o mesmo padrão em frotas maiores. Jed Arden, que gere cerca de vinte agentes, escreveu que [o LLM quase não aparece no registo de incidentes](https://jedarden.com/notes/what-breaks-at-twenty-agents/) (julho de 2026). [A equipa da Cursor verificou](https://cursor.com/blog/scaling-agents) que vinte agentes a partilhar um ficheiro de coordenação com bloqueios abrandaram para o débito de dois ou três (janeiro de 2026). ## O que eu configuraria primeiro Se está a começar com subagentes do Claude Code ou com qualquer orquestração de agentes, esta é a ordem em que eu o faria, dado o que me custou aprender: 1. **Registar cada lançamento de agente.** Uma linha por lançamento: hora, tipo de agente, modelo, risco. Sem isso não se percebe o que o sistema faz, e nenhum dos números acima existiria. 2. **Um escritor por ficheiro.** Os escritores em paralelo recebem um worktree e uma lista de ficheiros declarada. Os ficheiros a que toda a funcionalidade acrescenta (traduções, lockfiles, changelogs) têm um dono, e os outros entregam fragmentos. 3. **Recolher antes de limpar.** Nunca deixe um passo de limpeza decidir por "está a correr". Decida por "o seu trabalho está no checkout principal". 4. **Pôr as verificações fora do alcance dos agentes.** Hooks que bloqueiam, guardados onde uma sessão de projeto não consegue escrever. 5. **Limitar a vaga.** Cinco agentes em paralelo é o meu teto; acima disso a revisão torna-se o gargalo e os conflitos crescem mais depressa do que o débito. 6. **Escalar pela repetição, não pelo esforço.** Um modelo barato por omissão; após a mesma falha três vezes, uma tentativa num modelo mais forte; depois disso, uma pessoa. Quanto custa construir e operar um agente de IA para uma empresa, e não para o fluxo de trabalho de um único programador? É outra pergunta, respondida com números em [quanto custa um agente de IA](https://madsalt.tech/pt/blog/how-much-does-an-ai-agent-cost/). Que painéis vigio agora, a partir dos mesmos registos um mês depois, está em [Dashboard de agentes de IA: o que 1.238 execuções mostraram](https://madsalt.tech/pt/blog/ai-agent-monitoring-dashboard/). ## Limites deste relatório - **A configuração de um só programador.** Uma sessão principal, até cinco agentes em paralelo. Frotas de dezenas ou centenas de agentes falham de outras maneiras, por exemplo no lançamento. - **Sem fatura real.** O valor em dólares é um equivalente a preços de tabela da API para 30 dias, um mínimo que deixa de fora as escritas de cache e os modelos mais antigos. Pago uma subscrição fixa. - **Lacunas nos registos.** Os lançamentos bloqueados não são registados, por isso não sei dizer quantas vezes o limite de vaga disparou. As 159 execuções do implementador mais forte misturam passos de risco e falhas repetidas. - **Datas das minhas notas.** As datas dos incidentes vêm de notas e commits escritos no mesmo dia; um incidente tem outra data num ficheiro de regras mais antigo, e usei a nota. O protótipo de painel que nasceu deste trabalho é o [caso de orquestração multiagente](https://madsalt.tech/pt/work/multi-agent-orchestration/), e construir agentes para clientes enquadra-se em [agentes de IA e chatbots para empresas](https://madsalt.tech/pt/services/ai-agent-development/). A correr agentes em paralelo e a perder trabalho entre eles? Troco impressões com gosto sobre hooks, worktrees e barreiras de revisão. Sem pitch. [Fale comigo](https://madsalt.tech/pt/#contact)