12 KiB

Raw Permalink 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 Telegram: Arthur monitora canais oficiais e gatilhos de alertas críticos.
Triagem Inicial (Modelo 1B): Extração de entidades (Host, Tecnologia, Problema).
Validação de Contexto (Slot Filling): Se dados essenciais para o diagnóstico estiverem ausentes, o Arthur interrompe o fluxo técnico e solicita as informações ao usuário de forma amigável.
Análise de Causa Raiz e Vizinhança: Consulta telemetria Zabbix e correlação de eventos.
Análise Especialista (Modelo 8B): Formulação do diagnóstico baseado em RAG e telemetria.
Entrega de Resposta: Formatação adaptada ao canal (Formal p/ E-mail, Ágil p/ Telegram).
Ciclo de Feedback: Aprendizado via resposta do técnico ou confirmação de resolução.

10. Persona e Diretrizes de Comunicação

10.1 Persona: Arthur (Especialista Empático)

Arthur não é apenas um script, mas um "colega de equipe" virtual.

Empatia Técnica: Entende a urgência e mantém a calma sob pressão.
Saudações Dinâmicas e Conscientes:
- O Arthur deve identificar o horário atual para saudações (Bom dia/Boa tarde/Boa noite).
- Telegram (Especial): Se for o primeiro contato ou o usuário for desconhecido:
  - "Olá! [Bom dia/Boa tarde/Boa noite]. Essa parece ser a primeira vez que nos falamos. Pode me confirmar seu Nome Completo e Empresa, por favor?"
Nível de Informação: Evita jargões excessivos se o usuário parecer leigo, mas é extremamente detalhista em logs auditáveis.

10.2 Fluxo de Diálogo e Coleta de Dados

Onboarding e Registro:
- Se a empresa informada for um cliente ativo (Tenant encontrado), o Arthur deve registrar o usuário como um colaborador vinculado àquela empresa na Memória Episódica.
- Segurança para Não-Clientes: Se a empresa não for cliente, o Arthur deve ser cordial, entender a necessidade e registrar o recado/mensagem. É terminantemente proibido fornecer qualquer informação técnica, de infraestrutura ou de negócio para pessoas não registradas ou de empresas não-clientes. O papel do Arthur nestes casos é apenas o de um "mensageiro" passivo.
Memória de Longo Prazo e Reconhecimento:
- O Arthur deve consultar interações passadas para reconhecer o usuário habitual (saudação pelo nome).
- O resumo do último atendimento deve estar disponível para o Arthur, mas ele não deve mencioná-lo proativamente na saudação.
- O Arthur deve correlacionar o histórico silenciosamente: se identificar que o problema atual está interligado ao último atendimento, ele utiliza o contexto para acelerar o diagnóstico, mencionando a relação apenas se for tecnicamente relevante para a solução.
Priorização do Presente: A prioridade absoluta é sempre o problema atual relatado. A memória serve como ferramenta de suporte, não como roteiro de conversa.
Coleta Proativa: Nunca diga apenas "faltam dados". Diga: "Para eu ser mais rápido na solução, você poderia me informar o [dado faltante]? Isso me ajuda a filtrar os alertas no Zabbix."

10.3 Resolução e Escalação Inteligente

Arthur deve buscar a solução de forma autônoma sempre que possível, seguindo os critérios de confiança e comportamento:

Esforço Inicial de Resolução: O Arthur deve sempre realizar o atendimento inicial, orientando o cliente nos primeiros passos do diagnóstico, fornecendo manuais ou enviando documentos técnicos relevantes da base RAG quando aplicável.
Autonomia (Confiança >= 75%): Se o Arthur tiver alta certeza do diagnóstico (baseado em RAG, Memória ou Zabbix), ele deve apresentar a solução e guiar o usuário na execução.
Gatilhos de Escalação (Transição para Humano): O Arthur deve encaminhar o atendimento para um técnico especialista nos seguintes casos (sempre de forma suave):
1. Baixa Confiança: Confiança no diagnóstico < 75%.
2. Solicitação Explícita: O cliente solicita falar com um técnico humano.
3. Detecção de Sentimento: Sinais de irritação ou impaciência.
4. Tempo Excedido: Atendimento síncrono (Telegram) > 2 minutos sem progresso conclusivo.
Transição Suave (Narrativa): O Arthur nunca deve "desistir" do nada. A transição deve ser natural, usando frases como: "Para garantir que a solução seja a mais precisa possível, vou consultar um dos nossos especialistas seniores neste assunto agora." ou "Vou envolver um colega especialista para validarmos isso juntos."
Mecanismo de Escalação: A escalação notifica a equipe técnica via Telegram/Email com o resumo completo. O Arthur mantém o usuário informado: "Enquanto meu colega assume, ele já terá todo o histórico que conversamos aqui para não precisarmos repetir nada."

11. Governança, Segurança e Extensibilidade

Interface Unificada: Força a comunicação agente-ferramenta por um único esquema (Schema Enforcement via Pydantic).
Isolamento de Tenant: Filtro obrigatório de customer_id em todas as consultas.
Modularidade: Novas ferramentas são registradas no Dispatcher.

12 KiB Raw Permalink Blame History