Subagents (Субагенты и делегирование)

1. Visão geral do conceito e problema sistêmico

Em tarefas complexas de desenvolvimento, uma parte significativa do tempo é consumida por trabalho exploratório "sujo": buscas por palavras-chave em centenas de arquivos, leitura de documentação, inspeção de logs do sistema ou verificação de dezenas de dependências.

Se todas essas operações forem executadas por um único agente principal dentro de um mesmo diálogo:

1. Poluição catastrófica do contexto (Context Pollution): Milhares de linhas de código bruto e logs deslocam as instruções sistemáticas originais do usuário.
2. Degradação da atenção (Lost-in-the-Middle): O agente começa a se confundir com seus próprios rascunhos intermediários, perdendo o objetivo primário.
3. Gargalo sequencial (Sequential Bottleneck): O agente é forçado a revisar cada fonte em série, gastando minutos onde seria possível paralelizar o trabalho em segundos.

O padrão de subagentes (Subagents) implementa o princípio de isolamento do contexto de execução: o agente pai gera (spawns) executores filhos individuais com uma janela de atenção limpa, delega-lhes a rotina e recebe de volta apenas uma conclusão refinada e estruturada.

2. Taxonomia arquitetural e modelo mental

Com base na forma como o trabalho dos subagentes é organizado, destacam-se três topologias principais:

• 1. Fork-Join (Padrão Map-Reduce): O agente pai divide uma grande tarefa em $N$ partes independentes (por exemplo, análise de 4 microsserviços distintos), lança simultaneamente 4 subagentes paralelos (Fork), aguarda sua conclusão e mescla os resultados em um relatório unificado (Join).
• 2. Transient Deep-Dive Worker (Explorador descartável): Um subagente é gerado para uma operação específica única: por exemplo, acessar um site de documentação, realizar a autenticação, encontrar um exemplo de uso de endpoint e retornar apenas 5 linhas de código. Após isso, o container do subagente é destruído.
• 3. Árvore hierárquica com limite de profundidade (Bounded Delegation Tree): O processo pai gerencia subagentes de primeiro nível, que, quando necessário, podem gerar workers de segundo nível. Para evitar consumo descontrolado de recursos, a profundidade da recursão é estritamente limitada (max_depth = 2).

3. Pipeline técnico e mecânica interna

O ciclo de vida do trabalho de um subagente:

1. Chamada de Delegação (Delegation Call): O agente principal invoca uma ferramenta especial de lançamento: invoke_subagent(task_name="grep_auth_logs", prompt="...", tools=["grep", "cat"]).
2. Isolamento do Sandbox de Contexto (Context Sandbox Isolation): O runtime inicia uma nova sessão LLM com contexto limpo. Nele são injetados apenas a instrução para a subtarefa e uma lista limitada de ferramentas permitidas.
3. Execução Autônoma (Autonomous Execution): O subagente roda seu próprio ciclo ReAct, comete erros, testa hipóteses e formula o resultado final, sem perturbar o agente pai com mensagens intermediárias.
4. Síntese e Coleta de Lixo (Synthesis & Garbage Collection): O log bruto do diálogo do subagente é arquivado ou destruído. O agente principal recebe uma mensagem da ferramenta com um resumo curto (por exemplo: «Encontrados 2 vazamentos de memória no arquivo worker.ts: linhas 14 e 89»).

4. Cenários de engenharia prática em produção

01. Auditoria de segurança paralela de um monorepo grande

O arquiteto principal gera três subagentes simultaneamente:

• Worker 1: escaneia o backend em busca de injeções SQL e queries cruas inseguras.
• Worker 2: verifica o frontend quanto a XSS e chamadas perigosas de dangerouslySetInnerHTML.
• Worker 3: analisa arquivos de configuração Docker e CI/CD procurando portas abertas e imagens não hardenadas. Cada subagente lê centenas de arquivos, mas o arquiteto principal recebe uma tabela compacta consolidada com três pontos críticos.

02. Análise em background de logs massivos de servidor

Em vez de passar 50 megabytes de logs do Nginx para o contexto principal, é lançado um subagente analista. Ele filtra localmente os logs via grep/awk, encontra picos anômalos de status code 500 e retorna ao agente principal apenas o stacktrace destacado.

03. Pesquisa de bibliotecas externas sem perda de foco

Enquanto o agente de código projeta a arquitetura do serviço, ele envia um subagente para ler a documentação oficial da Stripe API. O subagente decifra a sintaxe dos checkouts e retorna um exemplo mínimo de código pronto.

5. Armadilhas, erros comuns e segurança

• Tempestade de tokens e Rate Limits (TPM Spikes): Lançar 10 subagentes simultaneamente cria um enorme pico de requisições ao provedor, resultando em erros cascata 429 Too Many Requests. Use sempre filas de tarefas com limitação de pool (por exemplo, máximo de 3 workers simultâneos).
• Conflitos de escrita paralela (Race Conditions): Se dois subagentes tentarem editar o mesmo arquivo no repositório simultaneamente, ocorrerá sobrescrita ou corrupção de código. Conceda aos subagentes de pesquisa direitos exclusivamente Read-Only.
• Recursão infinita de delegação (Fork Bomb): Um subagente decide que a tarefa é muito complexa e gera mais 5 subagentes, cada um fazendo o mesmo. Proíba sempre que agentes filhos invoquem a ferramenta invoke_subagent.