artubss Despachando Agentes em Paralelo
Visão Geral
Quando você tem múltiplas falhas não relacionadas (arquivos de teste diferentes, subsistemas diferentes, bugs diferentes), investigá-las sequencialmente desperdiça tempo. Cada investigação é independente e pode acontecer em paralelo.
Princípio central: Despache um agente por domínio de problema independente. Deixe-os trabalhar simultaneamente.
Quando Usar
digraph when_to_use {
"Múltiplas falhas?" [shape=diamond];
"São independentes?" [shape=diamond];
"Um agente investiga tudo" [shape=box];
"Um agente por domínio" [shape=box];
"Podem trabalhar em paralelo?" [shape=diamond];
"Agentes sequenciais" [shape=box];
"Despacho em paralelo" [shape=box];
"Múltiplas falhas?" -> "São independentes?" [label="sim"];
"São independentes?" -> "Um agente investiga tudo" [label="não - relacionadas"];
"São independentes?" -> "Podem trabalhar em paralelo?" [label="sim"];
"Podem trabalhar em paralelo?" -> "Despacho em paralelo" [label="sim"];
"Podem trabalhar em paralelo?" -> "Agentes sequenciais" [label="não - estado compartilhado"];
}
Use quando:
- 3+ arquivos de teste falhando com causas raiz diferentes
- Múltiplos subsistemas quebrados independentemente
- Cada problema pode ser entendido sem contexto dos outros
- Sem estado compartilhado entre investigações
Não use quando:
- Falhas são relacionadas (corrigir uma pode corrigir outras)
- Precisa entender o estado completo do sistema
- Agentes interfeririam um com o outro
O Padrão
1. Identifique Domínios Independentes
Agrupe falhas pelo que está quebrado:
- Testes do Arquivo A: Fluxo de aprovação de ferramenta
- Testes do Arquivo B: Comportamento de conclusão em lote
- Testes do Arquivo C: Funcionalidade de abortar
Cada domínio é independente – corrigir aprovação de ferramenta não afeta testes de aborto.
2. Crie Tarefas de Agente Focadas
Cada agente recebe:
- Escopo específico: Um arquivo de teste ou subsistema
- Objetivo claro: Fazer esses testes passarem
- Restrições: Não altere outro código
- Output esperado: Resumo do que você encontrou e corrigiu
3. Despache em Paralelo
// Em Claude Code / ambiente AI
Task("Corrigir falhas em agent-tool-abort.test.ts")
Task("Corrigir falhas em batch-completion-behavior.test.ts")
Task("Corrigir falhas em tool-approval-race-conditions.test.ts")
// Os três rodam concorrentemente
4. Revise e Integre
Quando agentes retornam:
- Leia cada resumo
- Verifique se os corrigios não entram em conflito
- Execute a suite de testes completa
- Integre todas as mudanças
Estrutura de Prompt de Agente
Bons prompts de agente são:
- Focados - Um domínio de problema claro
- Autossuficientes - Todo contexto necessário para entender o problema
- Específicos sobre output - O que o agente deve retornar?
Corrija os 3 testes falhando em src/agents/agent-tool-abort.test.ts:
1. "should abort tool with partial output capture" - espera 'interrupted at' na mensagem
2. "should handle mixed completed and aborted tools" - ferramenta rápida foi abortada em vez de concluída
3. "should properly track pendingToolCount" - espera 3 resultados mas recebe 0
Estes são problemas de timing/race condition. Sua tarefa:
1. Leia o arquivo de teste e entenda o que cada teste verifica
2. Identifique a causa raiz – problemas de timing ou bugs reais?
3. Corrija:
- Substituindo timeouts arbitrários por espera baseada em eventos
- Corrigindo bugs na implementação de aborto se encontrados
- Ajustando expectativas de teste se o comportamento mudou
Não apenas aumente timeouts – encontre o problema real.
Retorne: Resumo do que você encontrou e do que você corrigiu.
Erros Comuns
❌ Muito amplo: "Corrija todos os testes" - agente fica perdido ✅ Específico: "Corrija agent-tool-abort.test.ts" - escopo focado
❌ Sem contexto: "Corrija a race condition" - agente não sabe onde ✅ Contexto: Cole as mensagens de erro e nomes de testes
❌ Sem restrições: Agente pode refatorar tudo ✅ Restrições: "NÃO altere código de produção" ou "Corrija apenas testes"
❌ Output vago: "Corrija" - você não sabe o que mudou ✅ Específico: "Retorne resumo da causa raiz e mudanças"
Quando NÃO Usar
Falhas relacionadas: Corrigir uma pode corrigir outras - investigue junto primeiro Precisa de contexto completo: Entender requer ver todo o sistema Debugging exploratório: Você não sabe o que está quebrado ainda Estado compartilhado: Agentes interfeririam (editando mesmos arquivos, usando mesmos recursos)
Exemplo Real de Sessão
Cenário: 6 falhas de teste em 3 arquivos após refatoração maior
Falhas:
- agent-tool-abort.test.ts: 3 falhas (problemas de timing)
- batch-completion-behavior.test.ts: 2 falhas (ferramentas não executando)
- tool-approval-race-conditions.test.ts: 1 falha (contagem de execução = 0)
Decisão: Domínios independentes - lógica de aborto separada de conclusão em lote separada de race conditions
Despacho:
Agente 1 → Corrigir agent-tool-abort.test.ts
Agente 2 → Corrigir batch-completion-behavior.test.ts
Agente 3 → Corrigir tool-approval-race-conditions.test.ts
Resultados:
- Agente 1: Substituiu timeouts por espera baseada em eventos
- Agente 2: Corrigiu bug de estrutura de evento (threadId no lugar errado)
- Agente 3: Adicionou espera para conclusão de execução assíncrona de ferramenta
Integração: Todos os corrigios independentes, sem conflitos, suite completa verde
Tempo economizado: 3 problemas resolvidos em paralelo vs sequencialmente
Benefícios Principais
- Paralelização - Múltiplas investigações acontecem simultaneamente
- Foco - Cada agente tem escopo estreito, menos contexto para rastrear
- Independência - Agentes não interferem um com o outro
- Velocidade - 3 problemas resolvidos no tempo de 1
Verificação
Depois que agentes retornam:
- Revise cada resumo - Entenda o que mudou
- Verifique conflitos - Agentes editaram o mesmo código?
- Execute suite completa - Verifique se todos os corrigios funcionam juntos
- Verificação pontual - Agentes podem cometer erros sistemáticos
Impacto no Mundo Real
Da sessão de debugging (2025-10-03):
- 6 falhas em 3 arquivos
- 3 agentes despachados em paralelo
- Todas as investigações completadas concorrentemente
- Todos os corrigios integrados com sucesso
- Zero conflitos entre mudanças de agentes