🎯 Por que especializar agentes
A especialização não é sobre divisão de trabalho por conveniência — é sobre eficiência econômica e qualidade técnica. Um agente com escopo restrito precisa de menos contexto, usa um modelo mais barato, produz resultados mais consistentes e é muito mais fácil de avaliar.
Agente Generalista (o problema)
- ✗Prompt enorme com instruções para todos os domínios
- ✗Modelo mais caro necessário para manter qualidade
- ✗Hallucination mais frequente (contexto extenso confunde)
- ✗Difícil de avaliar — por qual critério você julga?
- ✗Impossível de substituir parcialmente sem refazer tudo
Agentes Especializados (a solução)
- ✓Prompt conciso e focado no domínio específico
- ✓Modelo mais barato — tarefas simples não precisam de opus
- ✓Menos hallucination — contexto mínimo, instrução clara
- ✓Avaliação por critério específico do domínio
- ✓Substituível individualmente sem afetar outros
📊 O impacto no custo
Um agente generalista usando Claude Opus 4 para cada tarefa pode custar $0.50 por execução. O mesmo sistema com agentes especializados — Opus para planejamento, Haiku para pesquisa, Sonnet para análise — pode custar $0.08. 6x mais barato com qualidade igual ou superior em cada especialidade.
🧭 Agente Planejador
O Planejador é o arquiteto do sistema — recebe o objetivo complexo e produz um plano estruturado executável pelos outros agentes. É o único agente que justifica um modelo de alto custo, porque um plano ruim contamina toda a execução seguinte.
🧭 Características do Agente Planejador
Exemplo de output do Planejador (JSON)
{
"objective_summary": "Análise de 5 concorrentes com relatório executivo",
"tasks": [
{
"id": "T1", "description": "Identificar top 5 concorrentes",
"agent": "researcher", "dependencies": [],
"success_criteria": "Lista JSON com nome, URL e categoria de 5 empresas"
}
],
"estimated_cost_usd": 0.45,
"estimated_duration_min": 12
}⚙️ Agente Executor
O Executor é o agente que mais executa e mais consome tokens. Recebe uma tarefa específica, usa suas ferramentas para completá-la e retorna resultado estruturado. É aqui que o custo do sistema é gerado — e onde a otimização de modelo tem maior impacto.
⚙️ O loop do Executor
💡 Seleção de modelo por tarefa
Pesquisa web: claude-haiku-3 — rápido e barato
Análise estruturada: claude-sonnet-4 — bom equilíbrio
Raciocínio complexo: claude-opus-4 — quando precisa
Geração de código: claude-sonnet-4 — excelente para código
⚠️ max_iterations é obrigatório
Um Executor sem limite de iterações pode entrar em loop tentando satisfazer um critério impossível de atingir. Defina sempre max_iterations=5 (ou similar) — após o limite, retorna resultado parcial com flag de falha.
🔍 Agente Revisor
O Revisor é o controle de qualidade automático do sistema. Sem ele, você entrega ao usuário final resultados de qualidade variável sem filtro. Com ele, cada resultado passa por avaliação criteriosa antes de prosseguir no pipeline.
Input
Resultado do Executor + acceptance_criteria definido pelo Planejador
Processo
Avalia qualidade por critério específico, atribui score e gera feedback estruturado
Output
approved: true/false, score: 0-10, feedback: "o que está faltando"
🔄 O ciclo Executor → Revisor
for attempt in range(max_revision_cycles):
result = executor.run(task, context)
review = revisor.evaluate(result, criteria)
if review.approved:
return result # aprovado
# Executor recebe feedback e tenta de novo
context.add_feedback(review.feedback)
return escalate_to_human(result) # esgotou revisões
📊 Agente Auditor
O Auditor não participa da execução — ele observa e registra. Em ambientes enterprise, o audit trail não é opcional: é um requisito de compliance, segurança e governança. O Auditor é o agente que torna o sistema explicável.
📊 O que o Auditor registra
📋 Requisitos de compliance
- •SOC2: audit trail de todas as operações
- •LGPD/GDPR: log de acesso a dados pessoais
- •HIPAA: audit completo de acesso a dados de saúde
💡 Implementação: append-only log
O audit trail é um log append-only com hash de integridade (cada entrada referencia o hash da anterior). Impossível alterar retroativamente. Pode exportar para SIEM corporativo.
📜 Contratos entre agentes
Contratos formais entre agentes são o que transforma um conjunto de scripts acoplados em um sistema substituível e testável. Com contratos explícitos, você pode trocar o Executor A pelo Executor B sem tocar no Revisor ou no Planejador — desde que ambos respeitem o mesmo contrato.
📜 Anatomia de um contrato de agente
class ExecutorContract(BaseModel):
# Input schema (o que o Executor aceita)
task_description: str
context: Dict[str, Any]
acceptance_criteria: str
max_cost_usd: float = Field(gt=0, le=5.0)
timeout_seconds: int = Field(ge=10, le=300)
# Output schema (o que o Executor sempre retorna)
class ExecutorResult(BaseModel):
result: Any
confidence_score: float # 0.0 - 1.0
cost_usd: float
iterations: int
status: Literal["done", "partial", "failed"]
✓ Com contratos formais
- ✓Substituição de agente sem modificar outros
- ✓Testes unitários por agente isolado
- ✓Validação automática de output antes de usar
- ✓Documentação gerada automaticamente do schema
✗ Sem contratos formais
- ✗Acoplamento implícito descoberto só em produção
- ✗Mudança em um agente quebra outro silenciosamente
- ✗Impossível testar agente de forma isolada
- ✗Ninguém sabe o que cada agente realmente precisa
💡 Use Pydantic para contratos em Python
Pydantic valida automaticamente que o input do agente é válido antes de executar, e que o output é válido antes de passar para o próximo. Quando o output é inválido, você recebe um ValidationError com o campo específico — não um resultado silenciosamente errado descoberto 10 etapas depois.
✅ Resumo do Módulo 4.4
Próximo Módulo:
4.5 — Gerenciamento de Estado: quando múltiplos agentes precisam ler e escrever o mesmo dado, o que acontece? Redis, locks, versionamento e recovery.