8.6 KiB

Raw Blame History

PRD - Agente de Suporte Técnico N2 (Arthur)

1. Visão Geral

O Agente Arthur é um sistema de IA soberano projetado para Suporte Técnico N2 de alta performance, operando exclusivamente em CPU com máxima eficiência de memória. Ele atua como um orquestrador que correlaciona dados em tempo real (Zabbix), histórico de eventos recentes e bases de conhecimento técnico para fornecer diagnósticos precisos e remediação assistida em ambientes multitenant (múltiplos clientes).

2. Objetivos do Produto

Otimização Extrema (CPU-Only): Utilizar modelos quantizados e estratégias de extração de dados para manter o consumo de RAM mínimo sem perder capacidade lógica.
Rastreabilidade e Auditabilidade: Utilizar o E-mail como canal oficial para garantir logs permanentes e auditáveis de cada diagnóstico e interação.
Raciocínio Correlacional: Identificar se um problema atual está vinculado a alertas gerais de infraestrutura ou a chamados abertos nas últimas 24 horas.
Isolamento Multitenant: Gerenciar conhecimentos específicos de diferentes empresas (ex: OESTEPAN, ENSEG) garantindo o isolamento de dados.
Integração de Dados Direta: Utilizar APIs diretas (Zabbix) para evitar o overhead de protocolos intermediários.

3. Escopo

3.1 Incluso

Interface via E-mail (IMAP/SMTP): Monitoramento de caixa postal (mail.itguys.com.br) e resposta de chamados com trilha de auditoria.
RAG Multitenant: Base de conhecimento segmentada por cliente com suporte a ingestão de manuais.
Correlação Temporal (24h): Análise de eventos recentes para identificar problemas globais ou recorrentes.
Dispatcher Unificado: Chamada de ferramentas (Zabbix, DB) via interface padronizada.
Ciclo de Feedback: Encerramento de chamados e aprendizado via interpretação de respostas de técnicos.

3.2 Não Incluso

Treinamento de Base Model: O projeto utiliza modelos pré-treinados (Llama, Phi, Qwen) e aplica fine-tuning via LoRA, não o treinamento do zero.
Suporte Nível 1 (Básico): O foco é em problemas que exigem raciocínio técnico e acesso a monitoramento.
Segurança de E-mail (Spoofing): A validação de SPF/DKIM/DMARC e a garantia de que o remetente não é forjado é responsabilidade do servidor de e-mail (MTA) e não do código do agente.

3.3 Requisitos de Segurança Detalhados

Gestão de Segredos: Proibido uso de credenciais hardcoded. Obrigatório uso de Docker Secrets.
Princípio do Menor Privilégio: Permissões de APIs e Bando de Dados devem ser estritamente Read-Only (Leitura) para o Agente. Escrita permitida apenas no canal de resposta (SMTP) e log de auditoria.
Sanitização de Input (Sandbox): Todo anexo ou dado externo não estruturado deve ser pré-processado em ambiente isolado (Sandbox) para remover scripts ou instruções maliciosas antes de ser lido pelos modelos (Mitigação de Indirect Prompt Injection).
Controle de Fluxo: As ferramentas devem ter destinos de saída imutáveis, impedindo o agente de exfiltrar dados para locais não autorizados.
Redação de Dados (DLP Leve): Implementar filtro baseado em Regex de alta performance para mascarar credenciais (Senhas, Keys) e PII antes de qualquer processamento ou armazenamento.
Rate Limiting de Aplicação: Definir limite lógico de requisições por Tenant para evitar exaustão de recursos da CPU (Proteção DoS).

4. Funcionalidades Principais

ID	Funcionalidade	Descrição
FR01	Integração Zabbix via API	Conexão direta via JSON-RPC para telemetria em tempo real e verificação de saúde da infraestrutura.
FR02	Ferramenta de Ingestão de RAG	CLI ou endpoint específico para processar manuais técnicos (.md, .pdf) e injetá-los na base do cliente correto.
FR03	Correlação de Eventos Cruzados	Capacidade de consultar chamados de outros colaboradores do mesmo cliente nas últimas 24h para identificar padrões.
FR04	Dispatcher de Ferramentas Unificado	Interface única de comunicação onde o modelo 1B gera chamadas padronizadas, reduzindo erros de sintaxe e consumo de tokens.
FR05	Memória Histórica Comparativa	Verifica se o chamado atual é uma reincidência ou se possui relação com problemas globais registrados.
FR06	Biblioteca de Ferramentas Extensível	Estrutura modular que permite adicionar novas integrações (AD, Firewall, M365) sem necessidade de retreinar os modelos.
FR07	Agrupamento e Deduplicação	Capacidade de correlacionar múltiplos alertas do Zabbix em um único diagnóstico de causa raiz, reduzindo o ruído e notificações duplicadas.
FR08	Validação de Output e Reflexão	Mecanismo de auto-crítica (Reflection Loop) onde o agente valida tecnicamente sua própria sugestão (ex: existência do host) antes de enviar a resposta.

5. Requisitos Não Funcionais (NFR)

NFR01 - Soberania: 100% de execução local sem dependências de APIs de nuvem externas.
NFR02 - Latência: Resposta inicial (TTFT) abaixo de 800ms para modelos de 8B e instantânea para modelos 1B.
NFR03 - Segurança: Implementação de Llama Guard para filtrar inputs maliciosos e Human-in-the-loop para ações críticas.
NFR04 - Estabilidade: Isolamento de processos via Docker para garantir resiliência.

6. Stack Tecnológica

Linguagem: Python 3.11/3.12.
LLMs (Local): Llama 3.1 (8B), Qwen 2.5 (7B), Llama 3.2 (1B) via Ollama/llama.cpp.
Orquestração: LangGraph para fluxos cíclicos e PydanticAI para validação de output.
Banco Vetorial: Qdrant (com suporte a On-Disk storage para economia de RAM).
Integração: Model Context Protocol (MCP) e zabbix_utils.
Monitoramento de IA: Langfuse (local) para tracing de execução.

7. Arquitetura de Hardware (Referência)

CPU: Intel Xeon E5-2699 v3 (18 Cores / 36 Threads).
RAM: 128 GB DDR4 ECC (Foco em largura de banda).
Storage: SSD NVMe (Mínimo 3000MB/s leitura) - Essencial para on_disk do Qdrant.
Rede: Interna Gbit (Baixa latência para chamadas de API Zabbix).

8. Estimativa de Recursos por Componente

Esta tabela detalha o consumo esperado para cada parte do sistema em estado de operação, permitindo identificar gargalos de otimização.

Componente	CPU (Threads)	RAM (Est.)	Disco (I/O)	Observação de Otimização
Inferência 1B (Triagem)	2 - 4	800MB - 1.2GB	Baixo	Modelo Q8 (Quantizado) para máxima precisão na extração.
Inferência 8B (N2)	8 - 12	5GB - 8GB	Médio	Modelo Q4_K_M. Otimizado para GGUF/llama.cpp.
Qdrant (Vector DB)	2 - 4	1GB - 2GB*	Alto	*Com `on_disk: true`. Exige alta performance de IOPS do NVMe.
Orquestrador (Python)	1	256MB - 512MB	Irrelevante	Apenas gestão de fluxo e chamadas de API.
PostgreSQL (Histórico)	1 - 2	1GB - 2GB	Baixo	Armazena metadados e histórico de chamados curtos.
Langfuse (Tracing/IA)	2	2GB - 4GB	Médio	Pode ser desligado em produção se o hardware estiver no limite.

Capacidade de Escalabilidade: Com 128GB de RAM, o sistema suporta até 10 instâncias simultâneas do Arthur (cada uma com seu próprio contexto 8B) sem atingir o limite de memória. O gargalo real será a contenção de threads na CPU Xeon durante a geração de texto.

9. Lógica de Atendimento e Encerramento (Workflow do Arthur)

Captura via E-mail ou Alerta Crítico: Arthur monitora a caixa de entrada ou recebe gatilhos de alertas críticos filtrados pelo Zabbix.
Análise de Causa Raiz e Vizinhança (Python): Antes de processar, o sistema consulta hosts vizinhos no Zabbix para identificar se o alerta é um sintoma de uma falha central (ex: queda de switch ou link).
Triagem e Coleta (Modelo 1B + Dispatcher): O modelo 1B decide as ferramentas de busca. O sistema agrupa alertas correlacionados em um único contexto.
Análise e Resposta (Modelo 8B): O especialista formula o diagnóstico consolidado e a solução, enviando o e-mail auditável.
Ciclo de Feedback e Aprendizado: Encerramento via resposta do técnico ou normalização do monitoramento, alimentando a memória episódica.

10. Governança, Segurança e Extensibilidade

Interface Unificada: Força a comunicação agente-ferramenta por um único esquema (Schema Enforcement via Pydantic), eliminando alucinações de formato.
Isolamento de Tenant: Filtro obrigatório de customer_id em todas as consultas.
Modularidade: Novas ferramentas são registradas no Dispatcher; o modelo 1B as "descobre" via System Prompt.

8.6 KiB Raw Blame History