joao.goncalves
/
minions-ai-agents
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
minions-ai-agents/.gemini/TODO_Arthur.md

7.1 KiB
Raw Blame History

TODO - Projeto Arthur (Agente de Suporte Técnico N2)

Este documento serve como o roteiro técnico detalhado para a implementação do Agente Arthur. O foco é soberania (local-only), otimização de CPU e integração auditável via e-mail.

Fase 1: Planejamento e Arquitetura de Dados ✅

  • Consolidação do PRD N2: Definição de escopo, hardware e lógica de atendimento.
  • Mapeamento do Tenant Resolver (Financeiro):
    • MockFinancialClient implementado em src/clients/mock_financial.py
    • Esquema Pydantic TenantContext em src/models/tenant.py
  • Design do Schema de Auditoria:
    • Modelo AuditLog em src/models/audit.py (PostgreSQL)
    • Migrations em src/database/migrations.py
  • Mapeamento de Segredos:
    • SecretsManager em src/security/secrets_manager.py
    • Suporte a Docker Secrets + variáveis de ambiente

Fase 2: Infraestrutura e Conectores Core ✅

  • Ambiente de Inferência Local:
    • OllamaClient em src/clients/ollama_client.py
    • Suporte a Llama 3.2 1B (Triagem) e Llama 3.1 8B (Especialista)
  • Configuração do Qdrant Multitenant:
    • QdrantMultitenant em src/clients/qdrant_client.py
    • Persistência on_disk: true + filtro por tenant_id
  • Conector Zabbix API:
    • ZabbixConnector em src/clients/zabbix_connector.py
    • Funções: get_host_status, get_active_problems, get_neighbor_alerts
  • Segurança de Infraestrutura:
    • Docker Secrets configurado
    • DLPFilter em src/security/dlp_filter.py (redação de CPF/CNPJ/senhas)
  • Módulo de Comunicação (Mail Client):
    • ⏳ Aguardando senha do email arthur.servicedesk@itguys.com.br

Fase 3: Orquestração e Raciocínio (Cérebro) ✅

  • Implementação do Agente de Triagem (1B):
    • TriageAgent em src/agents/triage_agent.py
    • Prompt Engineering para extração de entidades + fallback regex
    • Classificação de prioridade/categoria
  • Implementação do Agente Especialista (8B):
    • SpecialistAgent em src/agents/specialist_agent.py
    • Coleta de contexto Zabbix + RAG
    • Geração de diagnóstico e resposta
  • Pipeline de Processamento:
    • TicketPipeline em src/agents/pipeline.py
    • Orquestração triage → specialist → audit
  • Desenvolvimento do Multi-Agent Dispatcher:
    • MultiAgentDispatcher em src/agents/dispatcher.py
    • State machine: RECEIVED → TRIAGING → ENRICHING → ANALYZING → VALIDATING → RESPONDING
    • Integração com RateLimiter
  • Rate Limiter por Tenant:
    • RateLimiter em src/agents/rate_limiter.py
    • Sliding window (por minuto/hora)
    • Limite de requisições simultâneas
    • Prioridade por tier de cliente
  • Camada de Validação e Segurança (Self-Correction):
    • SelfCorrectionLayer em src/agents/validators.py
    • Validação de domínios permitidos
    • Bloqueio de comandos perigosos (rm -rf, DROP DATABASE, etc.)
    • Threshold de confiança com escalação automática
  • Desenvolvimento do Analista de Causa Raiz:
    • RootCauseAnalyzer em src/agents/root_cause_analyzer.py
    • Correlação de alertas por similaridade e keywords
    • Detecção de problemas de infraestrutura compartilhada

Fase 4: Flywheel e Qualidade (Aprendizado) ✅

  • Pipeline de Ingestão de RAG:
    • RAGIngestionPipeline em src/flywheel/rag_pipeline.py
    • Processamento de Markdown/TXT, chunking e indexação Qdrant
    • Sanitização de conteúdo (remoção de scripts, base64)
    • Detecção automática de tecnologia
  • Parser de Feedback de Encerramento:
    • FeedbackParser em src/flywheel/feedback_parser.py
    • Detecta: Resolvido, Reaberto, Escalação, Esclarecimento
    • Análise de sentimento e satisfação
  • Módulo de Memória Episódica:
    • EpisodicMemory em src/flywheel/episodic_memory.py
    • Armazenamento de lições aprendidas
    • Antipadrões (o que NÃO fazer)
    • Busca por similaridade

Fase 5: Implantação e Monitoramento ✅

  • Configuração do Langfuse Local:
    • LangfuseClient em src/deployment/langfuse_client.py
    • Docker Compose em docker/langfuse-compose.yml
    • Tracing com context managers (trace/span)
  • Teste de Stress e Latência:
    • StressTester em src/deployment/stress_tester.py
    • Métricas: p50, p95, p99, RPS
    • Scripts: run_dispatcher_stress_test, run_rate_limiter_stress_test
  • Ferramentas de Homologação:
    • HomologationValidator em src/deployment/homologation.py
    • Validações: DB, Qdrant, Ollama, Zabbix, Financeiro, Email, RateLimiter
    • Relatório formatado com status por check

Fase 6: Auditoria e Otimização com IA 🔄

  • Mapeamento de Alterações por Fase:
    • Listar commits e arquivos modificados em cada uma das fases (1-5)
    • Gerar manifesto de auditoria: AUDIT_MANIFEST.md
  • Execução de Agente de Qualidade:
    • Análise "ponto a ponto" do código mapeado
    • Focos: Otimizações, Falhas de Segurança, Bugs Lógicos, Code Quality
    • Resultado: AUDIT_REPORT.md
  • Soluções de Auditoria (Fixes):
    • Crítico: Criar src/clients/financial_client.py (Mock) para desbloquear homologação
    • Crítico: Implementar Embeddings Reais (BGE/Ollama) no RAG e Memória
    • Alta: Persistir AuditLog no PostgreSQL (Pipeline)
    • Alta: Refatorar Config para uso consistente de SecretsManager
    • Média: Otimizar N+1 queries no zabbix_connector.py
    • Baixa: Validação dinâmica de domínios em validators.py
  • Refinamento e Correção:
    • Verificar todas as alterações
    • Segunda Passagem de Auditoria (Deep Dive):
      • Análise de regressão e pontos cegos pós-correção
    • Validar ausência de regressões

Fase 7: Homologação e Go-Live 🔄

  • Obter Credenciais:
    • Senha do email arthur.servicedesk@itguys.com.br
  • Deploy Langfuse:
    • Executar docker compose -f docker/langfuse-compose.yml up -d
    • Configurar variáveis LANGFUSE_PUBLIC_KEY e LANGFUSE_SECRET_KEY
  • Executar Validação de Homologação:
    • Rodar run_homologation("staging") e garantir todos checks passando
  • Teste de Stress em Staging:
    • Validar latência com 5+ chamados simultâneos
    • Confirmar P95 < 5000ms
  • Validação com Clientes Reais:
    • Testar com emails de OESTEPAN e ENSEG
    • Confirmar isolamento de dados entre tenants
  • Go-Live:
    • Migrar Arthur para produção
    • Monitorar primeiras 24h via Langfuse

Diretrizes para Agentes de Execução:

  1. CPU Only: Nunca tente usar bibliotecas que exijam CUDA/GPU sem autorização expressa.
  2. Auditabilidade: Toda decisão do Arthur deve gerar um log no PostgreSQL.
  3. Isolamento: Garanta que os dados da ENSEG nunca vazem para um diagnóstico da OESTEPAN via filtros de Payload no Qdrant.