From 7a5e1bc76a7fc1c138cc020e301170cd61856089 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= Date: Mon, 2 Feb 2026 16:03:23 -0300 Subject: [PATCH] =?UTF-8?q?docs(prd/todo):=20Refinamento=20de=20Persona,?= =?UTF-8?q?=20Onboarding=20e=20Regras=20de=20Escala=C3=A7=C3=A3o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PORQUE FOI FEITA ESSA ALTERAÇÃO? Planejamento e Definição de UX. Atualização do PRD para incluir a persona 'Especialista Empático', lógica de saudação por horário, regras de segurança para não-clientes e critérios de escalação baseados em confiança (75%) e comportamento. Sincronização do roadmap (TODO) com a nova Fase 8 de refinamento. QUAIS TESTES FORAM FEITOS? Revisão de consistência técnica dos requisitos e validação da formatação Markdown dos arquivos .gemini/PRD_Suporte_Tecnico_N2.md e .gemini/TODO_Arthur.md. A ALTERAÇÃO GEROU UM NOVO TESTE? Não diretamente no código, mas estabelece os critérios de aceitação para os testes de integração da Fase 8. --- .gemini/PRD_Suporte_Tecnico_N2.md | 52 ++++++++++++++++++++++++++----- .gemini/TODO_Arthur.md | 45 ++++++++++++++++---------- 2 files changed, 72 insertions(+), 25 deletions(-) diff --git a/.gemini/PRD_Suporte_Tecnico_N2.md b/.gemini/PRD_Suporte_Tecnico_N2.md index 7d1e4b5..668b756 100644 --- a/.gemini/PRD_Suporte_Tecnico_N2.md +++ b/.gemini/PRD_Suporte_Tecnico_N2.md @@ -80,14 +80,50 @@ Esta tabela detalha o consumo esperado para cada parte do sistema em estado de o **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) -1. **Captura via E-mail ou Alerta Crítico:** Arthur monitora a caixa de entrada ou recebe gatilhos de alertas críticos filtrados pelo Zabbix. -2. **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). -3. **Triagem e Coleta (Modelo 1B + Dispatcher):** O modelo 1B decide as ferramentas de busca. O sistema agrupa alertas correlacionados em um único contexto. -4. **Análise e Resposta (Modelo 8B):** O especialista formula o diagnóstico consolidado e a solução, enviando o e-mail auditável. -5. **Ciclo de Feedback e Aprendizado:** Encerramento via resposta do técnico ou normalização do monitoramento, alimentando a memória episódica. +1. **Captura via E-mail ou Telegram:** Arthur monitora canais oficiais e gatilhos de alertas críticos. +2. **Triagem Inicial (Modelo 1B):** Extração de entidades (Host, Tecnologia, Problema). +3. **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. +4. **Análise de Causa Raiz e Vizinhança:** Consulta telemetria Zabbix e correlação de eventos. +5. **Análise Especialista (Modelo 8B):** Formulação do diagnóstico baseado em RAG e telemetria. +6. **Entrega de Resposta:** Formatação adaptada ao canal (Formal p/ E-mail, Ágil p/ Telegram). +7. **Ciclo de Feedback:** Aprendizado via resposta do técnico ou confirmação de resolução. -## 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. +## 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; o modelo 1B as "descobre" via System Prompt. +- **Modularidade:** Novas ferramentas são registradas no Dispatcher. diff --git a/.gemini/TODO_Arthur.md b/.gemini/TODO_Arthur.md index 70892ec..cd0a16c 100644 --- a/.gemini/TODO_Arthur.md +++ b/.gemini/TODO_Arthur.md @@ -113,23 +113,34 @@ Este documento serve como o roteiro técnico detalhado para a implementação do - Resultado: [AUDIT_DEEP_DIVE.md](file:///C:/Users/joao.goncalves/.gemini/antigravity/brain/0ae8ff87-2359-49bb-951c-6f6c593ee5db/AUDIT_DEEP_DIVE.md) - [x] 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 +## Fase 7: Integração Telegram e Homologação ✅ +- [x] **Pivot de Canal:** Substituição de Email por Telegram Bot para interface ágil. +- [x] **Deploy Langfuse Local:** Tracing habilitado e funcional. +- [x] **Executar Validação de Homologação:** + - [x] Check de Banco de Dados, Ollama (1B/8B), Qdrant e Zabbix OK. + - [x] Novo check de API do Telegram integrado na homologação. + +## Fase 8: Refinamento de Persona e UX Conversacional (PRÉ GO-LIVE) 🔄 +- [ ] **Onboarding e Reconhecimento de Usuário:** + - [ ] Lógica de saudação consciente do horário (Bom dia/Tarde/Noite). + - [ ] Fluxo de captura de Nome e Empresa para usuários desconhecidos (Telegram). + - [ ] Persistência de dados do usuário na Memória Episódica. +- [ ] **Aprimoramento do Fluxo de Escalação:** + - [ ] Implementar cálculo de confiança (Confidence Score) no SpecialistAgent. + - [ ] Lógica de "consultar colega" (transição suave) para confiança < 75%. + - [ ] Detecção de sentimento (irritação/impaciência) como gatilho de escalação. + - [ ] Timeout de 2 minutos para escalação automática em atendimentos sem progresso. +- [ ] **Camada de Atendimento para Não-Clientes:** + - [ ] Implementar modo "Mensageiro Passivo" para empresas não cadastradas. + - [ ] Bloqueio estrito de fornecimento de informações para perfis não autenticados. + +## Fase 9: Go-Live Final ⏳ +- [ ] **Finalização de Ambiente:** + - [ ] Migrar Arthur para servidor de produção (18 cores). + - [ ] Configuração final de variáveis de ambiente de produção. +- [ ] **Monitoramento Pós-Live:** + - [ ] Acompanhamento via Langfuse das primeiras 24h. + - [ ] Validação de isolamento de dados com usuários reais. --- ### Diretrizes para Agentes de Execução: