Design de Agentes de IA
Filosofia Central
Agentes não são mágica — são sistemas com entradas, saídas, memória, ferramentas e lógica de decisão. Projete-os com o mesmo rigor que qualquer software de produção. Todo agente deve ter um propósito claro, limites definidos e modos de falha explícitos.
Princípios de Design de Agentes
1. Esclareça a Intenção Antes de Agir
Um agente deve fazer perguntas esclarecedoras quando a intenção do usuário é ambígua — antes de executar qualquer ação irreversível. Use este padrão:
- O objetivo está claro? Se não, faça uma pergunta focada.
- As restrições são conhecidas? (escopo, formato de saída, fontes de dados)
- Como é o sucesso?
2. Especificação Antes do Código
Antes de escrever a lógica do agente, gere um arquivo de especificação ou lista de tarefas:
- Defina o papel e as responsabilidades do agente
- Liste todas as ferramentas às quais ele precisa ter acesso
- Defina os contratos de entrada/saída
- Identifique os modos de falha e o comportamento de fallback
- Então escreva o código
3. Responsabilidade Única
Cada agente deve fazer bem uma coisa. Prefira uma equipe de agentes especializados a um único agente de propósito geral.
Padrões de Orquestração
| Padrão | Quando Usar | Descrição |
|---|---|---|
| Sequencial | Pipelines lineares | Agentes encadeados em ordem fixa (rascunho → revisão → publicação) |
| Supervisor | Tarefas complexas com vários módulos | Agente líder roteia para trabalhadores especializados |
| ReAct | Resolução autônoma de problemas | Combina raciocínio (Pensamento) + ação (Uso de Ferramenta) |
| Chat em Grupo | Tarefas colaborativas | Comunicação multiagente com supervisão humana |
| DAG | Fluxos de trabalho com estado | Grafo acíclico dirigido para orquestração cíclica e com estado |
Guia de Seleção de Frameworks
| Framework | Melhor Para | Status |
|---|---|---|
| LangGraph | Agentes complexos com estado, fluxos de trabalho cíclicos, orquestração multiagente, nível de produção | ✅ Ativo — GA Maio 2025 |
| LangChain | Pipelines RAG simples, fluxos de trabalho lineares, protótipos rápidos | ✅ Ativo — use para RAG, não para agentes |
| CrewAI | Equipes multiagente baseadas em papéis ("Gerente", "Pesquisador", "Escritor") | ✅ Ativo |
| Microsoft Agent Framework | Agentes empresariais no ecossistema Azure — substitui AutoGen + Semantic Kernel | ✅ Ativo — Visualização Pública Out 2025, GA previsto para Q1 2026 |
| AutoGen | Legado — ainda funciona, mas sem novos recursos | ⚠️ Modo de manutenção desde Out 2025 |
| Personalizado (MCP) | Ferramentas de agente leves, portáteis e interoperáveis via padrão aberto | ✅ Ativo |
LangChain vs LangGraph — Qual Usar
A equipe do LangChain agora recomenda explicitamente esta divisão:
- LangGraph → para agentes: com estado, cíclicos, multiagente, tarefas de longa duração
- LangChain → para RAG e pipelines lineares: perguntas e respostas simples sobre documentos, transformações passo a passo
LangGraph é construído sobre o LangChain — você pode usar ambos juntos, começando com LangChain e migrando para LangGraph quando precisar de mais controle.
Design de Pipeline RAG
Fluxo RAG Padrão
Consulta do Usuário → Incorporar Consulta → Busca Vetorial → Recuperar Trechos → Aumentar Prompt → LLM → Resposta
Estratégia de Fragmentação (Melhor Prática 2026)
- Use fragmentação semântica — divida por significado, não por contagem de caracteres
- Tamanho do fragmento: 256–512 tokens para precisão; 1024 para conteúdo narrativo
- Sempre inclua metadados: fonte, página, seção, timestamp
Busca Híbrida (Recomendada)
Combine vetores densos (semânticos) + vetores esparsos (palavras-chave) para melhor recall:
Pontuação Final = α × Pontuação Densa + (1 - α) × Pontuação Esparsa
Seleção de Banco de Dados Vetorial
| BD | Melhor Para |
|---|---|
| pgvector | Pilha PostgreSQL existente, casos de uso simples |
| Pinecone | Gerenciado, escala de produção, operações mínimas |
| Weaviate | Multimodal, busca híbrida integrada |
| Milvus | Alto desempenho, auto-hospedado, grande escala |
| Chroma | Desenvolvimento local, prototipagem |
Arquitetura de Memória do Agente
| Tipo | Descrição | Implementação |
|---|---|---|
| No contexto | Janela de conversa atual | Array de histórico de chat |
| Externa de curto prazo | Memória com escopo de sessão | Redis / armazenamento em memória |
| Externa de longo prazo | Persistente entre sessões | BD Vetorial + metadados |
| Episódica | Interações passadas resumidas | Cadeia de sumarização → armazenamento vetorial |
Aviso de Apodrecimento de Contexto: Janelas de contexto longas degradam a qualidade do agente com o tempo. Implemente uma etapa de sumarização a cada N turnos para manter a relevância.
Uso de Ferramentas e Chamada de Funções
Padrão de Definição de Ferramenta
Toda ferramenta precisa:
name: nome_descritivo_da_ferramenta
description: Quando usar esta ferramenta e o que ela faz (seja explícito)
parameters:
- name: nome_do_parametro
type: string
description: O que este parâmetro espera
required: true
Melhores Práticas de Uso de Ferramentas
- Ferramentas devem ser idempotentes sempre que possível
- Sempre valide as saídas da ferramenta antes de passar para a próxima etapa
- Implemente timeouts e novas tentativas para chamadas de ferramentas externas
- Registre todas as invocações de ferramentas para depuração
Padrões de Comunicação entre Agentes
Protocolo de Esclarecimento de Intenção
Quando um agente recebe uma solicitação ambígua:
- Identifique a ambiguidade — o que exatamente não está claro?
- Faça uma pergunta — a mais importante, não todas elas
- Proponha um padrão — "Vou assumir X, a menos que você me diga o contrário"
- Confirme antes de ações irreversíveis — sempre pergunte antes de deletar, publicar ou enviar
Relatório de Progresso
Para tarefas de longa duração, os agentes devem relatar:
[Passo 1/4] Buscando documentos... ✓
[Passo 2/4] Fragmentando e incorporando... ✓
[Passo 3/4] Consultando o armazenamento vetorial...
Comunicação de Erros
✗ Ferramenta falhou: [nome_da_ferramenta]
Motivo: [erro específico]
Fallback: [o que estou fazendo em vez disso]
MCP (Model Context Protocol)
MCP é o padrão aberto para conectar agentes a ferramentas e fontes de dados externas. Use-o ao construir ferramentas de agente portáteis e interoperáveis.
Estrutura do Servidor MCP
meu-servidor-mcp/
├── server.py (ou index.ts)
├── tools/
│ └── minha_ferramenta.py
└── README.md
Quando Usar MCP vs Integração Direta
- Use MCP quando a ferramenta precisar ser reutilizável em vários agentes/plataformas
- Use integração direta para implementações de ferramentas específicas de projeto e pontuais
Consulte a habilidade mcp-builder para obter orientação detalhada sobre implementação de servidor MCP.
Segurança
- Nunca permita que agentes executem código arbitrário sem sandboxing
- Implemente limitação de taxa em todas as chamadas de API LLM
- Valide e sanitize todas as entradas antes de passá-las para as ferramentas
- Registre todas as decisões do agente para auditabilidade
- Implemente barreiras de proteção para evitar custos excessivos de tokens ou loops recursivos
- Use proteção contra injeção no prompt do sistema — separe a entrada do usuário das instruções do sistema com delimitadores claros
Design de Agente Resiliente (Auto-Cura)
Agentes falham em produção. Projete para recuperação desde o início.
Loop de Validar e Repetir (Padrão LoopAgent)
Gerar saída → Validar saída → Se inválido: feedback + regerar
Máximo de iterações: 3 ← disjuntor para evitar loops infinitos
Planejar–Validar–Executar–Observar–Replanejar
PLANEJAR: Gerar plano, verificar viabilidade antes de agir
EXECUTAR: Agir
OBSERVAR: Teve sucesso? Verificar saídas, executar testes
REPLANEJAR: Se a observação mostrar falha → ajustar e tentar novamente
PARAR: Se o máximo de tentativas for atingido → relatar falha claramente, pedir ajuda
Hierarquia de Fallback do Agente
Abordagem primária falha → Tentar abordagem alternativa
Alternativa falha → Solicitar esclarecimento ao desenvolvedor
Esclarecimento ausente → Ação padrão segura ou parada graciosa
Validação de Saída Antes de Apresentar
- Execute testes/lint no código gerado antes de apresentar
- Verifique se o formato da saída corresponde aos requisitos
- Use uma etapa de validador separada (modelo ou prompt diferente) para verificar a saída do gerador
- Nunca apresente saída não verificada como concluída
Disjuntor para Agentes
Defina limites rígidos para evitar comportamento descontrolado:
- Máximo de iterações de chamada de ferramenta por tarefa (ex.: 10)
- Gasto máximo de tokens por sessão
- Máximo de novas tentativas por etapa com falha (ex.: 3)
- Timeout por invocação de ferramenta
Consulte a habilidade self-healing-mindset para obter a filosofia completa de resiliência e padrões de código.