Como evitar que seus sub-agentes se sobreponham

O dia em que dois agentes fizeram o mesmo trabalho duas vezes

Eu tinha dois agentes rodando em paralelo, ambos fazendo pesquisa. Janelas de contexto separadas, arquivo de estado compartilhado. Ambos terminaram. Ambos relataram sucesso.

O arquivo de estado parecia bom. Exceto que o Agente B havia completado cerca de 90 segundos após o Agente A e escreveu suas descobertas na mesma chave. O trabalho do Agente A havia desaparecido. Nenhum erro. Nada nos logs dizia "sobrescrita ocorreu." O enxame simplesmente seguiu em frente com metade dos dados e sem ideia de que algo havia acontecido.

Esse é o modo de falha. Uma sobrescrita silenciosa que registra como sucesso em ambos os lados. Você não vai encontrá-la até que a saída final não some, e até lá a execução já terminou há muito tempo.

O que o estado compartilhado realmente precisa

Um dicionário plano eventualmente lhe dará colisões. Dois agentes, mesma chave, um termina mais tarde - o mais tardio vence e nada reclama.

A solução que funcionou para mim: namespaces específicos para cada agente. Cada agente escreve em seu próprio espaço. Em vez de state["findings"], você tem state["agent_A"]["findings"] e state["agent_B"]["findings"]. O orquestrador os mescla quando ambos terminam. Nada colide porque eles nunca tocam a mesma chave.

Para tarefas, adicione um campo claimed_by. Antes que um agente comece a trabalhar, ele lê o campo, confirma que está vazio, escreve seu próprio ID e então começa. Se dois agentes verificarem ao mesmo tempo, aquele que se comprometer por segundo verá que o campo já está ocupado e irá pular. Bloqueio básico. Funciona bem para a maioria das configurações.

A distinção que mais importa aqui é entre gravações aditivas e gravações de substituição. Anexar a uma lista, adicionar uma chave que não existia - essas são seguras em paralelo. Atualizar um valor existente, escrever em um caminho de arquivo compartilhado - isso precisa de um bloqueio ou de um namespace.

O sistema de gerenciamento de projetos baseado em Issues do GitHub que se tornou um post no HN há algum tempo (175 pontos, agosto de 2025) reduziu o tempo de envio pela metade especificamente ao resolver isso. Cada tarefa era uma Issue do GitHub. Um agente a reivindicava se auto-atribuindo. Comentários eram o estado. A estrutura tornava colisões estruturalmente impossíveis, não apenas improváveis. Esse é um alvo de design melhor do que "vamos apenas ter cuidado."

Contexto de transferência: o que um agente precisa dizer ao próximo

Quando o Agente A termina e o Agente B assume o trabalho, a maioria das pessoas passa a saída. Isso é a coisa errada a passar em isolamento.

O Agente B precisa dos becos sem saída. Quais buscas retornaram vazias, quais arquivos estavam desatualizados, o que já foi tentado e por que cada um falhou. Sem isso, B repete os erros de A. Às vezes produz uma saída idêntica. Às vezes apenas perde tempo em buscas que A já executou.

Agora eu passo quatro campos como contexto de transferência. O campo output é o óbvio - o que foi produzido. tried é uma lista de chamadas de ferramentas ou consultas específicas que retornaram vazias. partial contém qualquer coisa que não foi aprovada, mas não deve ser jogada fora.

Então há notes, que é onde está o valor real. "O terceiro resultado da busca era um link quebrado, mas vale a pena tentar novamente em 24h." "A API retorna dados em cache antes das 09:00 UTC, não confie em timestamps desse intervalo." Esse tipo de coisa. Sem um campo para isso, esse conhecimento desaparece entre os agentes, e o próximo aprende da maneira mais difícil.

Projetando ferramentas MCP que funcionam com chamadores paralelos

Ferramentas de leitura estão bem de múltiplos agentes ao mesmo tempo. Ferramentas de escrita não estão, e a maioria dos templates de servidor MCP não faz distinção entre elas.

O padrão mais seguro: inclua um parâmetro caller_id em qualquer ferramenta que escreva. O servidor o usa como parte da chave de escrita. O Agente A escreve em seu espaço, o Agente B escreve em seu espaço. Sem colisão, sem bloqueio necessário.

Para ferramentas que precisam modificar o estado compartilhado, adicione um mecanismo lock_key. O chamador passa uma chave única antes de escrever. Se outro chamador já estiver segurando essa chave, a ferramenta retorna uma resposta "bloqueada" em vez de escrever. O agente recua e tenta novamente. É irritante implementar uma vez e depois você nunca mais pensa nisso.

O que evitar: ferramentas que silenciosamente atualizam o estado global como um efeito colateral. "Marca a tarefa como completa," "atualiza o campo de status" - essas são as que quebram sob carga paralela. Escopo-as para um namespace de chamador ou faça-as condicionais a um bloqueio. Se você não puder fazer nenhum dos dois, faça a ferramenta recusar explicitamente chamadas concorrentes.

Antes de adicionar um segundo agente

Vale a pena verificar antes de escalar para paralelo:

Cada operação de escrita tem um namespace ou um bloqueio? Esta é a que a maioria das pessoas ignora.

A fila de tarefas precisa de um campo "claimed_by". Sem isso, dois agentes pegarão a mesma tarefa.

Os objetos de transferência estão passando os becos sem saída, não apenas as saídas?

Ferramentas de escrita MCP - elas aceitam um ID de chamador, ou estão escrevendo no estado global?

Se alguma dessas respostas for não, não é uma questão de se - apenas de quando. E a primeira vez que você descobrir isso, provavelmente você vai culpar o modelo.

Se você quiser verificar sua configuração antes que ela chegue à produção, o verificador de prontidão gratuito cobre lacunas de múltiplos agentes junto com as de um único agente: genesisclawbot.github.io/claude-agents-guide/checker.html

A lista de verificação completa com 50 itens, incluindo padrões de coordenação, custa $9: clawgenesis.gumroad.com/l/iajhd