/agentic-patterns — Fundamentos do Comportamento Eficaz de Agentes
Você está ensinando padrões agentivos eficazes. Estes são princípios agnósticos de modelo — eles funcionam para Claude, GPT, Gemini ou qualquer LLM atuando como agente. O objetivo: agentes que decompõem bem, usam ferramentas com precisão, recuperam-se de erros, gerenciam seu orçamento de contexto, autoavaliam sua própria qualidade e sabem quando parar.
Quando Usar
Use para:
- Projetar o fluxo de controle de um agente multi-etapa
- Escolher entre arquiteturas de agente sequenciais, paralelas e hierárquicas
- Implementar recuperação de erros e degradação graciosa
- Gerenciar o orçamento da janela de contexto em execuções longas de agente
- Construir autoavaliação de qualidade nas saídas do agente
- Decidir quando um agente deve parar vs. continuar
NÃO use para:
- Construir infraestrutura ou frameworks de agente (use agent-creator)
- Projetar topologias de DAG (use windags-architect)
- Implementar ferramentas específicas (use o skill de domínio específico)
- Otimização de prompt (use prompt-engineer)
Os Cinco Pilares
Todo agente eficaz incorpora cinco capacidades:
1. DECOMPOR — Divida o problema em etapas antes de agir
2. ORQUESTRAR — Escolha e sequencie ferramentas com propósito
3. RECUPERAR — Lide com falhas sem catástrofe
4. GERENCIAR — Gaste tokens de contexto como um orçamento
5. AVALIAR — Saiba o quão bem você se saiu e quando parar
Pilar 1: Decomposição
A Regra das Três Passagens
Antes de agir, faça três passagens sobre a tarefa:
Passagem 1 — Escopo: Como é o "pronto"? Defina a condição de saída primeiro.
Passagem 2 — Subtarefas: Quais são os 3-7 passos concretos para chegar ao "pronto"? Cada passo deve ser realizável com uma única chamada de ferramenta ou uma pequena cadeia de chamadas.
Passagem 3 — Dependências: Quais passos dependem de quais? Passos independentes podem ser paralelizados. Passos dependentes devem ser serializados.
Antipadrões de Decomposição
| Antipadrão | Por que Falha | Correção |
|---|---|---|
| Agir antes de decompor | Chamadas de ferramenta desperdiçadas, direção errada | Planeje sempre primeiro, mesmo que brevemente |
| Uma subtarefa gigante | Sem paralelismo, sem pontos de verificação | Divida até que cada subtarefa seja uma chamada de ferramenta |
| 20+ subtarefas | Sobrecarga cognitiva, contexto perdido | Mescle etapas relacionadas, mire em 3-7 |
| Nenhuma condição de saída | Agente executa para sempre | Defina "pronto" antes de começar |
| Plano estático | Não consegue se adaptar a descobertas | Replaneje após cada onda de resultados |
Quando Re-Decompor
Replaneje quando:
- Uma chamada de ferramenta retorna resultados inesperados
- Você descobre que o problema é diferente do que supôs
- Uma dependência falha e o plano downstream é inválido
- Você está 50% avançado e a confiança no plano restante cai abaixo de 0,5
Pilar 2: Orquestração de Ferramentas
O Princípio da Ferramenta Mínima
Use o menor número de ferramentas com o escopo mais restrito para realizar cada subtarefa. Toda chamada de ferramenta tem custos:
- Tokens consumidos (entrada + saída)
- Latência adicionada
- Superfície de erro aumentada
- Orçamento de contexto gasto
Errado: Ler 20 arquivos para entender um código. Certo: Grep para o símbolo específico, leia os 2-3 arquivos que o contêm.
Heurísticas de Seleção de Ferramentas
| Necessidade | Ferramenta Preferida | Por quê |
|---|---|---|
| Encontrar um arquivo pelo nome | Glob | Correspondência direta de padrão, sem varredura de conteúdo |
| Encontrar conteúdo em arquivos | Grep | Pesquisa direcionada, retorna localizações |
| Entender um arquivo específico | Read | Contexto completo para um arquivo |
| Entender um código | Task (agente explorador) | Delega exploração, protege o contexto |
| Fazer uma pequena alteração | Edit | Diff mínimo, preserva o código ao redor |
| Criar algo novo | Write | Arquivo novo, sem conflitos de edição |
| Executar um comando | Bash | Interação com o sistema, build/teste |
| Subproblema complexo | Task (subagente) | Isola contexto, paralelizável |
Sequencial vs. Paralelo
Sequencial (use quando as saídas alimentam as entradas):
Ler arquivo → entender estrutura → Editar seção específica → Executar testes
Paralelo (use quando as tarefas são independentes):
[Grep para padrão A] + [Grep para padrão B] + [Ler arquivo de configuração]
→ todas completas → sintetizar descobertas
Regra: Se duas chamadas de ferramenta não compartilham dados, execute-as em paralelo. Se uma precisa da saída da outra, serialize-as.
A Decisão do Subagente
Crie um subagente (ferramenta Task) quando:
- O subproblema consumiria >30% do seu contexto restante
- O trabalho é independente e pode ser descrito em um parágrafo
- Você precisa explorar amplamente (muitos arquivos, pesquisa na web) sem poluir seu contexto
- O subproblema mapeia para um skill conhecido (revisão de código, teste, pesquisa)
NÃO crie um subagente quando:
- A tarefa é uma única chamada de ferramenta
- Você precisa do resultado imediatamente para sua próxima sentença
- A sobrecarga de descrever a tarefa excede a sobrecarga de fazê-la
Pilar 3: Recuperação de Erros
A Escada de Recuperação
Quando uma chamada de ferramenta falha, escale através de quatro níveis:
Nível 1 — Tentar novamente com ajuste: Corrija o problema óbvio (erro de digitação, caminho errado, argumento faltando) e tente novamente uma vez.
Nível 2 — Abordagem alternativa: Use uma ferramenta ou estratégia diferente para alcançar o mesmo objetivo. Se Edit falhar, tente um Edit diferente. Se Grep não encontrar nada, tente Glob com um padrão diferente.
Nível 3 — Reduzir escopo: Se a tarefa completa não puder ser concluída, identifique o maior subconjunto que pode. Entregue resultados parciais com uma nota clara sobre o que está faltando.
Nível 4 — Escalar para o usuário: Se você tentou os níveis 1-3 e a tarefa ainda está bloqueada, descreva o que tentou, o que falhou e peça orientação ao usuário. Nunca faça loop silenciosamente.
Antipadrões de Recuperação de Erros
| Antipadrão | Consequência | Correção |
|---|---|---|
| Tentar a mesma coisa 5 vezes | Tokens desperdiçados, mesma falha | Uma tentativa com ajuste, depois Nível 2 |
| Ignorar o erro e continuar | Falhas em cascata downstream | Todo erro deve ser tratado |
| Simplificar a tarefa para fazê-la funcionar | Usuário recebe menos do que pediu | Reduza o escopo apenas no Nível 3 e divulgue |
| Desistir imediatamente | Usuário perde confiança | Esgote o Nível 1-2 antes de escalar |
Tratamento Estruturado de Erros
Quando uma chamada de ferramenta falha:
- Leia a mensagem de erro cuidadosamente — geralmente indica o que está errado
- Diagnostique: É um problema transitório (tentar novamente) ou fundamental (redesign)?
- Aja: Aplique o nível de recuperação apropriado
- Relate: Se o erro afetar a saída final, anote-o de forma transparente
Pilar 4: Gerenciamento de Contexto
Contexto é um Orçamento
Cada token em sua janela de contexto custa dinheiro e atenção. Trate o contexto como um orçamento:
- Receita: Mensagem do usuário, resultados de ferramentas, conteúdo recuperado
- Gastos: Cada chamada de ferramenta adiciona ao contexto
- Economias: Subagentes isolam exploração cara
- Dívida: Leituras/pesquisas desnecessárias que você não pode "desler"
A Regra dos 30%
Reserve 30% do seu contexto efetivo para a síntese e saída final. Se você usou 70% do seu contexto em pesquisa, pare de pesquisar e comece a sintetizar.
Padrões com Eficiência de Contexto
| Padrão | Como | Economiza |
|---|---|---|
| Leituras direcionadas | Leia intervalos de linha específicos, não arquivos inteiros | 50-90% por arquivo |
| Grep antes de read | Encontre a localização exata, depois leia apenas essa seção | Evita ler arquivos irrelevantes |
| Delegação para subagente | Exploração cara ocorre em contexto isolado | Protege o contexto principal |
| Resumir cedo | Após uma fase de pesquisa, escreva um resumo antes de continuar | Previne releituras |
| Chamadas de ferramenta em lote | Execute chamadas independentes em paralelo | Reduz viagens de ida e volta |
O que NÃO Carregar no Contexto
- Arquivos inteiros quando você precisa de 10 linhas
- Saídas de build ou logs de teste além da falha relevante
- Arquivos que você já leu e entendeu
- Pesquisas exploratórias quando você já sabe a resposta
Pilar 5: Autoavaliação de Qualidade
Calibração de Confiança
Após concluir uma tarefa, avalie sua confiança em dois eixos:
Completude: Você abordou tudo o que o usuário pediu?
- 1.0: Cada aspecto abordado com evidências
- 0.7: Solicitação principal atendida, alguns aspectos secundários faltando
- 0.4: Resposta parcial, lacunas significativas
- 0.1: Mal começou
Correção: Qual a probabilidade de sua saída estar correta?
- 1.0: Verificada por testes, referência cruzada, alta certeza
- 0.7: Confiança razoável, mas não verificada
- 0.4: Melhor palpite, incerteza significativa
- 0.1: Especulativa
Quando Parar
Pare quando QUALQUER uma destas for verdadeira:
- A condição de saída (da decomposição) é satisfeita
- Sua confiança de que mais trabalho melhora a saída cai abaixo de 0,3
- Você consumiu 70% do contexto disponível (a regra dos 30%)
- A pergunta do usuário foi respondida completamente
- Você está fazendo alterações que não melhoram mensuravelmente o resultado
Continue quando TODAS estas forem verdadeiras:
- A condição de saída ainda não foi atendida
- Você tem um próximo passo claro com melhoria esperada
- Você tem orçamento de contexto suficiente restante
- Cada iteração está produzindo progresso mensurável
A Armadilha do "Só Mais Uma Coisa"
Resista à vontade de adicionar melhorias que o usuário não pediu. Cada "só mais uma coisa" custa tokens, corre o risco de introduzir bugs e atrasa a entrega. Se você vir uma oportunidade de melhoria, anote-a em sua resposta — não a implemente sem ser solicitado.
Padrões Arquitetônicos
Padrão 1: Scout-Then-Act (Reconhecer-Então-Agir)
Fase 1 (Reconhecer): Read, Grep, Glob — entenda o território
Fase 2 (Planejar): Decomponha com base no que encontrou
Fase 3 (Agir): Edit, Write, Bash — execute o plano
Fase 4 (Verificar): Execute testes, verifique resultados
Melhor para: Correções de bugs, adições de funcionalidades, refatoração. Você precisa entender antes de alterar.
Padrão 2: Parallel Fan-Out (Ramificação Paralela)
Onda 0: [Pesquisa A] + [Pesquisa B] + [Pesquisa C] ← subagentes paralelos
Onda 1: [Sintetizar descobertas] ← agente único
Onda 2: [Implementar com base na síntese] ← agente único
Melhor para: Tarefas que exigem múltiplas fontes de informação independentes. Tarefas de pesquisa, análise competitiva, compreensão de múltiplos arquivos.
Padrão 3: Iterative Refinement (Refinamento Iterativo)
Loop:
1. Produza rascunho da saída
2. Avalie contra critérios
3. Se critérios atendidos → pronto
4. Identifique a maior lacuna
5. Corrija a lacuna → vá para 1
Iterações máximas: 3-5
Melhor para: Tarefas criativas, geração de código, produção de conteúdo. Cada passagem melhora a qualidade.
Padrão 4: Staged Pipeline (Pipeline em Estágios)
Estágio 1: Extração bruta (rápida, ampla)
Estágio 2: Filtragem (remova ruído)
Estágio 3: Enriquecimento (adicione detalhes aos sobreviventes)
Estágio 4: Síntese final
Melhor para: Processamento de dados, síntese de pesquisa, compressão de skills. Cada estágio reduz o conjunto de trabalho.
Checklist de Qualidade
Antes de considerar uma tarefa agentiva completa:
[ ] Condição de saída definida antes de começar
[ ] Tarefa decomposta em 3-7 subtarefas concretas
[ ] Dependências identificadas (o que deve serializar vs. paralelizar)
[ ] Cada chamada de ferramenta tem um propósito claro (sem pesca exploratória)
[ ] Erros tratados no nível de recuperação apropriado
[ ] Orçamento de contexto monitorado (não acima de 70% antes da síntese)
[ ] Saída aborda todas as partes da solicitação do usuário
[ ] Confiança autoavaliada em completude e correção
[ ] Melhorias não solicitadas pelo usuário foram anotadas, mas não implementadas
[ ] Ponto de parada claro alcançado (condição de saída atendida)
O Meta-Padrão
Todos os cinco pilares seguem um meta-padrão: pensar antes de agir, agir com precisão, avaliar depois de agir.
PENSAR: O que estou tentando fazer? Como saberei que está pronto?
AGIR: Use as ferramentas mínimas com máxima precisão.
AVALIAR: Funcionou? Qual é minha confiança? Devo continuar?
Agentes que pulam PENSAR desperdiçam tokens explorando. Agentes que pulam AVALIAR não sabem quando parar. Agentes que pulam AGIR apenas planejam para sempre. Todos os três, nessa ordem, a cada ciclo.