diff --git a/docs/FLUXO_PERSONAS.md b/docs/FLUXO_PERSONAS.md new file mode 100644 index 0000000..3ae4b14 --- /dev/null +++ b/docs/FLUXO_PERSONAS.md @@ -0,0 +1,169 @@ +# Fluxo de Trabalho das Personas + +Este documento descreve o fluxo atual de trabalho das personas no sistema Antigravity Brain e o problema identificado na transição de "voz" entre agentes. + +--- + +## 📊 Arquitetura Atual + +```mermaid +flowchart TD + subgraph Interface["💬 Interface Chainlit"] + User([Usuário]) + Gnarl["🧙 Gnarl
(Mensagem de Boas-Vindas)"] + end + + subgraph Core["⚙️ Core System"] + Router["SmartRouter
(classifica a requisição)"] + Crews["CrewDefinitions
(monta a crew apropriada)"] + end + + subgraph CrewsAvailable["🎭 Crews Disponíveis"] + C1["Infra Engineering (Zabbix)
Arthur Mendes + Gus Fring"] + C2["Security Audit
Elliot Alderson + Devil"] + C3["HR & Evolution
The Architect + Sherlock Holmes"] + C4["Sales Growth
(não implementado)"] + C5["Business Strategy
Harvey Specter (fallback)"] + end + + User -->|"mensagem"| Gnarl + Gnarl -->|"passa para"| Router + Router -->|"seleciona"| Crews + Crews -->|"monta"| C1 + Crews -->|"monta"| C2 + Crews -->|"monta"| C3 + Crews -->|"monta"| C4 + Crews -->|"monta"| C5 +``` + +--- + +## ❌ Problema Atual: Transição de Voz + +### Sintoma +O **Gnarl** cumprimenta o usuário na mensagem inicial, mas quando uma task é executada, os agentes especializados (Arthur, Harvey, Elliot, etc.) respondem diretamente **sem indicação de quem está falando**. + +### Fluxo Atual (Problemático) + +| Etapa | Quem Fala | O que Aparece | +|-------|-----------|---------------| +| 1. Início | Gnarl | "Gnarl Online. Mestre, estou pronto..." | +| 2. Usuário pergunta | - | "Como monitoro um servidor?" | +| 3. Processamento | (invisível) | "Pensando..." | +| 4. Resposta | **???** | "Para monitorar um servidor você precisa..." | + +**Problema:** Na etapa 4, o usuário não sabe que a resposta veio do **Arthur Mendes** (especialista em infraestrutura) e não do Gnarl. + +### Impacto na UX +- Confusão sobre quem está respondendo +- Perda de "personalidade" dos agentes especializados +- Usuário não entende a expertise por trás de cada resposta + +--- + +## 🎯 Personas Disponíveis (27 total) + +### Por Crew + +| Crew | Agentes | Função | +|------|---------|--------| +| **Infra Engineering** | Arthur Mendes, Gus Fring | Zabbix, monitoramento, infraestrutura | +| **Security Audit** | Elliot Alderson, Devil | Pentesting, vulnerabilidades | +| **HR & Evolution** | The Architect, Sherlock Holmes | Criar agentes, aprender políticas | +| **Business Strategy** | Harvey Specter | Fallback genérico, ROI, compliance | +| **Sales Growth** | (não implementado ainda) | - | + +### Lista Completa de Personas + +``` +ari-gold, arthur-mendes, chris-gardner, devil, don-draper, elliot-alderson, +gordon-ramsay, gremlin, gus-fring, hannibal-lecter, harvey-specter, +jerry-maguire, jim-halpert, kevin-oleary, leslie-knope, linus-torvalds, +marie-kondo, olivia-pope, react-expert, saul-goodman, sherlock-holmes, +steve-jobs, ted-lasso, the-architect, tony-stark, tyrion-lannister, walter-white +``` + +--- + +## 💡 Soluções Propostas para Discussão + +### Opção A: Gnarl como "Narrador/Tradutor" +O Gnarl permanece como a única voz visível ao usuário. Ele recebe o resultado das crews e *parafrasea* no seu estilo. + +``` +Gnarl: "Mestre, consultei Arthur Mendes sobre seu problema. + Ele diz que para monitorar um servidor você precisa..." +``` + +**Prós:** Interface consistente, uma única personalidade +**Contras:** Perde a riqueza dos personagens especializados + +--- + +### Opção B: Assinatura de Agente na Resposta +Adicionar visualmente quem está respondendo: + +``` +━━━ Arthur Mendes ━━━ +Para monitorar um servidor você precisa... +``` + +**Prós:** Clareza sobre quem fala +**Contras:** Pode parecer "robótico", quebra imersão + +--- + +### Opção C: Transição Narrativa (Recomendada) +Gnarl faz a ponte entre as vozes: + +``` +Gnarl: "Mestre, deixe-me chamar Arthur Mendes para essa questão..." + +Arthur: "Olá! Para monitorar um servidor você precisa..." + +Gnarl: "Arthur finalizou. Posso ajudar com mais algo, Mestre?" +``` + +**Prós:** Mantém narrativa fluida, mostra expertise, Gnarl como orquestrador +**Contras:** Mais verboso, requer mudanças no app.py + +--- + +### Opção D: Gnarl "Veste" a Persona +Gnarl muda seu estilo de fala baseado na crew ativa, sem trocar nome: + +``` +# Se crew é "Security Audit" (Elliot personality) +Gnarl: "Mestre... analisei a superfície de ataque. Root access em 3 minutos." + +# Se crew é "Business Strategy" (Harvey personality) +Gnarl: "Mestre, vamos fechar isso. Aqui está o que você precisa fazer..." +``` + +**Prós:** Uma voz, várias personalidades +**Contras:** Pode ser confuso, Gnarl perderia sua identidade + +--- + +## 🔧 Arquivos Relevantes para Implementação + +| Arquivo | Função | +|---------|--------| +| [app.py](file:///c:/Users/joao.goncalves/Desktop/minions-da-itguys/src/app.py) | Interface Chainlit, onde Gnarl é definido | +| [definitions.py](file:///c:/Users/joao.goncalves/Desktop/minions-da-itguys/src/crews/definitions.py) | Montagem das crews | +| [router.py](file:///c:/Users/joao.goncalves/Desktop/minions-da-itguys/src/router.py) | Lógica de roteamento | +| [factory.py](file:///c:/Users/joao.goncalves/Desktop/minions-da-itguys/src/agents/factory.py) | Criação de agentes | +| [src/agents/personas/](file:///c:/Users/joao.goncalves/Desktop/minions-da-itguys/src/agents/personas/) | Arquivos de personalidade | + +--- + +## ⏳ Próximos Passos + +1. **Decidir** qual opção de transição de voz implementar (A, B, C ou D) +2. **Implementar** as mudanças no `app.py` e possivelmente `definitions.py` +3. **Testar** o novo fluxo de conversação +4. **Documentar** o comportamento final + +--- + +*Documento criado em: 2026-01-09*