Arquiteto de Design de Agentes de IA

## PERGUNTAS PARA ESCLARECIMENTO Antes de projetar o agente, preciso confirmar: 1. **Escopo do processo**: O processo descrito em `${process}` envolve manipulação de dados não estruturados (e-mails, mensagens) ou apenas dados estruturados (planilhas, CRMs)? 2. **Volume esperado**: Quantas execuções por dia/semana? Qual o tamanho médio dos dados processados? 3. **Criticidade**: Uma falha silenciosa é aceitável ou toda execução precisa de confirmação explícita? 4. **Ambiente**: O agente rodará em servidor dedicado, contêiner Docker, ou máquina local? 5. **Acesso humano**: Existe um operador disponível para aprovações manuais em horário comercial? 6. **Idioma dos dados**: Os dados de entrada estão em português, inglês, ou mistos? 7. **Orçamento de API**: Existe limite mensal de custo para chamadas de LLM? --- ## ARQUITETURA DO SISTEMA ### Visão Geral ``` ┌─────────────────────────────────────────────────────────────────────┐ │ ORQUESTRADOR PRINCIPAL │ │ (Python + LangGraph ou State Machine) │ └─────────────────────────────────────────────────────────────────────┘ │ ┌───────────────┬───────────┴───────────┬───────────────┐ ▼ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ INGESTÃO │ │ PROCESSAMENTO│ │ VERIFICAÇÃO │ │ ENTREGA │ │ (coletores) │ │ (LLM) │ │ (regras + │ │ (saída) │ │ │ │ │ │ validação) │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │ │ │ │ └───────────────┴───────────┬───────────┴───────────────┘ ▼ ┌───────────────────────┐ │ ESTADO + MEMÓRIA │ │ (SQLite + JSON) │ └───────────────────────┘ │ ┌───────────┴───────────┐ │ LOGS + MÉTRICAS │ │ (JSONL + Prometheus) │ └───────────────────────┘ ``` ### Diagrama de Fluxo de Dados ``` [Fonte: Site/CRM/Email/Telegram] │ ▼ ┌─────────────────┐ │ Coletor (cron) │ → Dados brutos → /data/raw/ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Normalizador │ → Dados limpos → /data/processed/ │ (script puro) │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Extrator LLM │ → Campos estruturados (JSON) │ (prompt fixo) │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Validador │ → Regras + schema → OK/ERRO │ (script puro) │ └─────────────────┘ │ │ OK ERRO │ │ ▼ ▼ ┌────────┐ ┌────────────┐ │ Entrega│ │ Retry/ │ │ (API) │ │ Fallback │ └────────┘ └────────────┘ ``` --- ## LISTA COMPLETA DE FERRAMENTAS E APIs | Categoria | Ferramenta | Uso | Custo | |-----------|-----------|-----|-------| | LLM | GPT-4o-mini ou Claude Haiku | Extração e sumarização | Baixo | | LLM (fallback) | GPT-3.5-turbo | Retry com modelo mais barato | Mínimo | | Banco de dados | SQLite | Estado, memória, histórico | Grátis | | Agendamento | cron / APScheduler | Execução periódica | Grátis | | Orquestração | LangGraph ou State Machine manual | Controle de fluxo | Grátis | | Coleta | requests + BeautifulSoup | Scraping de sites | Grátis | | Coleta | python-telegram-bot | Mensagens do Telegram | Grátis | | Coleta | IMAPClient | Leitura de e-mail | Grátis | | Integração | API REST do CRM | Leitura/escrita | Conforme fornecedor | | Monitoramento | Prometheus + Grafana | Métricas e alertas | Grátis | | Logging | structlog + JSONL | Logs estruturados | Grátis | | Segredos | python-dotenv + .env | Credenciais | Grátis | | Testes | pytest + unittest.mock | Testes automatizados | Grátis | --- ## PSEUDOCÓDIGO DO LOOP PRINCIPAL ``` FUNÇÃO executar_ciclo(): # 1. INGESTÃO dados_brutos = coletar_de_todas_fontes() salvar(dados_brutos, "/data/raw/") # 2. NORMALIZAÇÃO (sem LLM) dados_limpos = normalizar(dados_brutos) salvar(dados_limpos, "/data/processed/") # 3. PROCESSAMENTO LLM PARA CADA item EM dados_limpos: resultado = chamar_llm( prompt=construir_prompt(item), modelo=config.modelo_principal, max_tokens=config.max_tokens ) validar_formato_json(resultado) salvar(resultado, "/data/output/") # 4. VERIFICAÇÃO PARA CADA resultado EM saídas: erros = validar_contra_schema(resultado) SE erros: marcar_para_retry(resultado, erros) SENÃO: marcar_como_verificado(resultado) # 5. RETRY (máx. 2 tentativas) PARA CADA item_para_retry: resultado = chamar_llm( prompt=construir_prompt_corrigido(item, erros_anteriores), modelo=config.modelo_fallback ) SE ainda_inválido: mover_para_fila_aprovacao_humana() # 6. ENTREGA PARA CADA resultado_verificado: enviar_para_destino(resultado) # CRM, email, etc. # 7. LOGS E MÉTRICAS registrar_metricas( total_processados, taxa_sucesso, tempo_total, custo_llm ) # 8. ATUALIZAR ESTADO atualizar_memoria(resultados, erros, métricas) FUNÇÃO principal(): config = carregar_config() inicializar_logging() conectar_servicos() SE config.modo == "agendado": agendar(executar_ciclo, intervalo=config.intervalo) SENÃO SE config.modo == "evento": registrar_webhook(executar_ciclo) SENÃO: executar_ciclo() # manual aguardar_encerramento() ``` --- ## ESTRUTURA DE PASTAS RECOMENDADA ``` agent/ ├── config/ │ ├── settings.yaml # Configuração principal │ ├── prompts.yaml # Prompts versionados │ └── .env # Credenciais (nunca versionar) ├── src/ │ ├── __init__.py │ ├── main.py # Ponto de entrada │ ├── orchestrator.py # Loop principal │ ├── collectors/ │ │ ├── __init__.py │ │ ├── website.py │ │ ├── telegram.py │ │ ├── email.py │ │ └── crm.py │ ├── processors/ │ │ ├── __init__.py │ │ ├── normalizer.py # Sem LLM │ │ ├── llm_extractor.py # Com LLM │ │ └── validator.py # Regras de validação │ ├── delivery/ │ │ ├── __init__.py │ │ └── output_handlers.py │ ├── memory/ │ │ ├── __init__.py │ │ ├── state_manager.py │ │ └── schema.py │ ├── monitoring/ │ │ ├── __init__.py │ │ ├── metrics.py │ │ └── alerts.py │ └── utils/ │ ├── __init__.py │ ├── logging_setup.py │ └── retry.py ├── data/ │ ├── raw/ # Dados brutos │ ├── processed/ # Dados normalizados │ ├── output/ # Resultados finais │ └── state/ # Banco SQLite ├── tests/ │ ├── __init__.py │ ├── test_collectors.py │ ├── test_processors.py │ ├── test_validator.py │ └── fixtures/ ├── scripts/ │ ├── setup.sh │ ├── backup.sh │ └── health_check.sh ├── docker/ │ ├── Dockerfile │ └── docker-compose.yml ├── requirements.txt ├── README.md └── .gitignore ``` --- ## ROTEIRO DE DESENVOLVIMENTO PASSO A PASSO ### Fase 1 - Fundação (Dias 1-3) 1. Configurar ambiente Python + dependências 2. Criar estrutura de pastas 3. Implementar logging estruturado 4. Configurar carregamento de config e credenciais 5. Escrever testes unitários para utils básicos ### Fase 2 - Coleta (Dias 4-6) 6. Implementar coletor de websites (requests + BeautifulSoup) 7. Implementar coletor de e-mail (IMAP) 8. Implementar coletor de Telegram 9. Implementar integração com CRM (API REST) 10. Testar cada coletor com dados reais ### Fase 3 - Processamento (Dias 7-10) 11. Implementar normalizador (regex + limpeza) 12. Definir prompts para extração LLM 13. Implementar chamada LLM com retry e timeout 14. Implementar validador de schema 15. Testar pipeline completo com dados de exemplo ### Fase 4 - Entrega e Orquestração (Dias 11-13) 16. Implementar handlers de saída 17. Implementar loop principal com state machine 18. Adicionar mecanismo de retry e fallback 19. Configurar agendamento (cron) 20. Teste de integração completo ### Fase 5 - Monitoramento e Robustez (Dias 14-16) 21. Implementar métricas (tempo, custo, taxa de sucesso) 22. Configurar alertas (email/Telegram) 23. Implementar fila de aprovação humana 24. Testes de falha (simular erros de API, timeouts) 25. Documentar procedimentos operacionais ### Fase 6 - Produção (Dias 17-20) 26. Deploy em servidor/contêiner 27. Monitoramento em produção (período de observação) 28. Ajustar prompts com base em erros reais 29. Configurar backup do estado 30. Documentação final + handover --- ## CHECKLIST DE SEGURANÇA - [ ] Credenciais armazenadas apenas em `.env` (nunca no código) - [ ] `.env` adicionado ao `.gitignore` - [ ] Permissões de arquivo restritas (600 para `.env`) - [ ] Comunicação com APIs via HTTPS obrigatório - [ ] Rate limiting implementado para todas as APIs externas - [ ] Timeout em todas as chamadas de rede (máx. 30s) - [ ] Validação de entrada para prevenir injeção de prompt - [ ] Sanitização de saída antes de enviar para sistemas externos - [ ] Logs não contêm dados sensíveis (mascarar e-mails, CPFs) - [ ] Backup automático do banco de estado (diário) - [ ] Acesso ao servidor via SSH com chave (sem senha) - [ ] Atualização regular de dependências (mensal) - [ ] Plano de resposta a incidentes documentado --- ## CHECKLIST DE TESTES ### Testes Unitários - [ ] Normalizador: entradas com formatos variados - [ ] Validador: casos válidos e inválidos - [ ] Retry: comportamento com falhas simuladas - [ ] Parsing de resposta LLM (JSON malformado) ### Testes de Integração - [ ] Coletor → Normalizador → LLM → Validador → Entrega - [ ] Falha em cada etapa não interrompe o ciclo - [ ] Dados duplicados são detectados e ignorados - [ ] Rate limit da API é respeitado ### Testes de Falha - [ ] API do LLM indisponível → fallback ativado - [ ] Timeout de rede → retry com backoff - [ ] Dados de entrada vazios → ciclo termina sem erro - [ ] Formato inesperado nos dados → item vai para fila humana - [ ] Banco de dados corrompido → recuperação automática ### Testes de Performance - [ ] 100 itens processados em < 5 minutos - [ ] Consumo de memória estável (sem vazamentos) - [ ] Custo por ciclo dentro do orçamento definido ### Testes de Aceitação - [ ] 95% dos itens processados sem intervenção humana - [ ] 100% dos itens entregues são validados - [ ] Alertas funcionam corretamente - [ ] Operador consegue revisar e aprovar itens pendentes --- ## CRITÉRIOS DE PRONTIDÃO DO AGENTE O agente está pronto para produção quando: 1. **Precisão**: ≥ 95% dos itens processados corretamente sem intervenção 2. **Confiabilidade**: Zero falhas silenciosas em 7 dias de teste contínuo 3. **Recuperação**: Consegue se recuperar automaticamente de todos os cenários de falha testados 4. **Observabilidade**: Todas as execuções são rastreáveis via logs e métricas 5. **Custo**: Custo mensal estimado ≤ orçamento definido 6. **Segurança**: Checklist de segurança 100% aprovado 7. **Documentação**: Procedimentos operacionais e de recuperação documentados 8. **Testes**: Suite de testes com cobertura ≥ 80% do código crítico 9. **Backup**: Backup do estado testado e restaurado com sucesso 10. **Handover**: Pelo menos um operador treinado para monitorar e intervir --- ## VERSÕES DO AGENTE ### GREEN MVP (3-5 dias) - Coleta de uma única fonte (ex: e-mail) - Extração LLM com prompt simples - Saída em arquivo CSV/JSON - Execução manual via script - Sem monitoramento ou retry avançado - Logs básicos em arquivo ### YELLOW STABLE (2-3 semanas) - Todas as fontes de dados configuradas - Validação de schema obrigatória - Retry com fallback de modelo - Agendamento automático (cron) - Métricas básicas (tempo, sucesso, custo) - Fila de aprovação humana para casos duvidosos - Alertas via email/Telegram ### BLUE PRO (1-2 meses) - Memória de longo prazo (SQLite) com histórico de decisões - Auto-aprendizado: análise de erros passados para melhorar prompts - Dashboard Grafana completo - Detecção de drift nos dados de entrada - Múltiplos modelos LLM com roteamento inteligente - API de gerenciamento para operadores - Versionamento de prompts com rollback automático