🎯 Diagrama Visual: Solução de Contexto Persistente
📊 Arquitetura Completa
╔═════════════════════════════════════════════════════════════════╗
║ SLACK USER ║
╚════════════════────────────┬════════════════════════════════════╝
│
"Qual é o preço?"
│
▼
╔═════════════════════════════════════════════════════════════════╗
║ SLACK_BOT.PY ║
║ Rate Limiting: 2 simultâneas, 3/min por user ║
║ Concorrência: AsyncApp + asyncio locks ║
╚════════────┬──────────────────────────────────┬────────────────╝
│ │
│ check_user_rate_limit() │
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ PASS: 1/3 ✅ │ │ FAIL: >= 3 ❌ │
│ Proceed │ │ Reject with msg │
└────────┬────────┘ └──────────────────┘
│
│ runner.run_async(user_id, session_id, msg)
│
▼
╔═════════════════════════════════════════════════════════════════╗
║ ADK RUNNER (google.adk.runners.Runner) ║
║ Orquestra Session + Memory Services ║
╚════════────┬────────────────────────────────┬──────────────────╝
│ │
Etapa 1│ session_service.get_session() │ Etapa 3
│ │ memory_service
▼ │ .add_session_...
┌──────────────────────┐ │
│ SESSION SERVICE │ │
│ (Firestore) │ │
├──────────────────────┤ │
│ 🔑 PASSO 1 │ │
│ │ │
│ Recupera session_id │ │
│ ↓ │ │
│ Carrega messages do │ │
│ Firestore │ │
│ ↓ │ │
│ Converte para Event │ │
│ objects │ │
│ ↓ │ │
│ Popula session.events│ │
│ ↓ │ │
│ Return Session ✅ │ │
│ with events │ │
└─────────┬────────────┘ │
│ │
│ Session(events=[...]) │
│ │
▼ │
┌──────────────────────┐ │
│ ROOT_AGENT │ │
│ (LlmAgent) │ │
├──────────────────────┤ │
│ Instruction: "Buscar │ │
│ produtos..." │ │
│ │ │
│ Tools: │ │
│ • PreloadMemoryTool │───────┐ │
│ • busca_produtos │ │ │
│ • calcular_preco │ │ │
│ • ... │ │ │
│ │ │ │
│ Agent vê: │ │ │
│ • session.events = [ │ │ │ Etapa 2
│ "Preço?", │ │ │ Agent
│ "R$ 100" │ │ chama │ pode
│ ] │ │ buscar │ buscar
│ • user_id = "user123"│ │ histórico
│ │ │ │
│ Responde com contexto│ │ │
│ "Você perguntou..." │ │ │
└─────────┬────────────┘ │ │
│ │ │
Evento (user + │ │
agent response) │ │
│ │ │
▼ │ │
┌──────────────────────┐ │ │
│ append_event() │ │ │
│ [x2 calls] │ │ │
│ │ │ │
│ EVENT 1: User msg │ │ │
│ EVENT 2: Agent resp │ │ │
│ │ │ │
│ Salva no Firestore │ │ │
│ session.messages ✅ │ │ │
└──────────┬───────────┘ │ │
│ │ │
│ │ │
│ Session( │ │
│ events=[...], │ │
│ messages: [ │ │
│ {msg1}, │ │
│ {msg2} │ │
│ ]) │ │
│ │ │
└──────────┬────────┼─────────┘
│ │
│ │
▼ ▼
┌────────────────────────────────┐
│ MEMORY SERVICE │
│ (Firestore) │
├────────────────────────────────┤
│ 🔑 PASSO 2 │
│ │
│ add_session_to_memory() │
│ ↓ │
│ Extrai content relevante: │
│ "P: Qual é o preço?" │
│ "R: R$ 100" │
│ ↓ │
│ Salva em collection: │
│ agente_busca_produtos_memory │
│ ↓ │
│ user_id + timestamp = key ✅ │
│ │
│ search_memory() │
│ ↓ │
│ Busca por keyword: │
│ "preço" → encontra! ✅ │
└────────────┬────────────────────┘
│
│ SearchMemoryResponse
│ [resultado1, ...]
│
▼
┌────────────────────────────────┐
│ Agent Usa Resultado │
│ │
│ PreloadMemoryTool("preço") │
│ ↓ │
│ "Ah sim, você perguntou sobre │
│ preço antes e era R$ 100" │
│ │
│ Personalizacão! ✅ │
└────────────────────────────────┘
🔄 Fluxo Temporal: 2 Conversas Mesma Session
TEMPO ───────────────────────────────────────────────────────────>
T0: Usuário começa conversa
user123 em channel#produtos
session_id = "user123_slack_products"
│
├─> runner.run_async(user_id, session_id, "Produtos de viagem?")
│
├─> get_session() ← Carrega eventos
│ │ Firestore: messages = []
│ │ session.events = []
│ └─> Retorna Session vazio (primeira vez)
│
├─> Agent processa
│ ├─> PreloadMemoryTool("viagem")
│ │ └─> search_memory() ← Busca histórico anterior
│ │ └─> "Nenhum resultado" (primeira conversa)
│ │
│ └─> busca_produtos_tool("viagem")
│ └─> "Temos Safari, Cruzeiro, Ski"
│
├─> append_event(evento_user) ← Salva pergunta
├─> append_event(evento_agent) ← Salva resposta
│ │ Firestore: messages = [{user_msg}, {agent_msg}]
│ │
│ └─> add_session_to_memory() ← Extrai conhecimento
│ └─> memory collection = [{content: "P:Viagem? R:Safari..."}]
│
└─> Resposta ao Slack: "Temos Safari, Cruzeiro, Ski"
────────────────────────────────────────────────────────────────
(segundos depois)
────────────────────────────────────────────────────────────────
T1: Usuário faz pergunta 2
user123 em channel#produtos
session_id = "user123_slack_products" (MESMA)
│
├─> runner.run_async(user_id, session_id, "Qual é mais barato?")
│
├─> get_session() ← Carrega eventos
│ │ Firestore: messages = [{user_msg1}, {agent_msg1}]
│ │ session.events = [Event(user_msg1), Event(agent_msg1)]
│ └─> Retorna Session COM histórico! ✅
│
├─> Agent processa
│ ├─> Vê session.events = [pergunta1, resposta1]
│ │ └─> Agent entende contexto! "Eles perguntaram sobre viagem"
│ │
│ ├─> PreloadMemoryTool("viagem barato")
│ │ └─> "Cruzeiro é mais barato"
│ │
│ └─> calcular_preco_tool(safari, cruzeiro, ski)
│ └─> "Safari $2000, Cruzeiro $800, Ski $1500"
│
├─> append_event(evento_user)
├─> append_event(evento_agent)
│ └─> Firestore: messages = [{user_msg1}, {agent_msg1},
│ {user_msg2}, {agent_msg2}]
│
└─> Resposta: "Cruzeiro é mais barato a $800"
────────────────────────────────────────────────────────────────
(dias depois, novo canal)
────────────────────────────────────────────────────────────────
T2: Usuário volta em novo canal
user123 em channel#suporte (DIFERENTE!)
session_id = "user123_slack_suporte" (NOVA SESSION)
│
├─> runner.run_async(user_id, session_id, "Lembra de mim?")
│
├─> get_session() ← Carrega eventos
│ │ Firestore: messages = [] (nova sessão!)
│ │ session.events = []
│ └─> Retorna Session vazio
│
├─> Agent processa
│ ├─> Vê session.events = [] (vazio, nova sessão)
│ │ └─> Agent não tem contexto desta sessão
│ │
│ ├─> PreloadMemoryTool("histórico") ← Busca MEMÓRIA! 🧠
│ │ │ search_memory(user_id, query)
│ │ │ ├─> Busca em memory collection
│ │ │ └─> Encontra: "Conversas sobre viagem, Safari $2000..."
│ │ │
│ │ └─> SearchMemoryResponse([resultado1, resultado2])
│ │
│ └─> Agent responde com contexto de LONGO PRAZO!
│ "Sim! Você perguntou sobre viagens. Recomendei Safari ($2000),
│ Cruzeiro ($800), Ski ($1500). Cruzeiro era mais barato."
│
└─> Resposta: "Claro! Você tinha interesse em viagens..."
🎯 Comparação: Antes vs Depois
❌ ANTES (Sem Contexto)
Request 1:
User: "Produtos de viagem?"
Agent: "Temos Safari, Cruzeiro, Ski" ✓
Request 2 (MESMA SESSION):
User: "Qual é mais barato?"
Agent: "Desculpe, preciso saber qual produto você quer comparar" ❌
(Agent não lembrava das opções!)
Request 3 (NOVA SESSION):
User: "Lembra de mim?"
Agent: "Desculpe, é a primeira vez que conversamos" ❌
(Agent perdia todo histórico!)
✅ DEPOIS (Com Contexto)
Request 1:
User: "Produtos de viagem?"
Agent: "Temos Safari, Cruzeiro, Ski" ✓
[Salvo em session.events + memory]
Request 2 (MESMA SESSION):
User: "Qual é mais barato?"
Agent: "Cruzeiro é mais barato a $800" ✅
(Agent viu session.events!)
Request 3 (NOVA SESSION):
User: "Lembra de mim?"
Agent: "Sim! Você perguntou sobre viagens.
Recomendei Safari, Cruzeiro e Ski.
Cruzeiro era o mais barato a $800" ✅
(Agent usou PreloadMemoryTool!)
🧠 Modelo Mental: 2 Níveis de Memória
┌──────────────────────────────────────┐
│ SHORT-TERM MEMORY (Session) │
│ │
│ session.events = [ │
│ Event(role="user", ...), │
│ Event(role="assistant", ...), │
│ Event(role="user", ...), │
│ Event(role="assistant", ...) │
│ ] │
│ │
│ Válido por: Duração da conversa │
│ Armazenado em: SessionService │
│ Acessado por: Automaticamente (Runner)
│ │
│ Exemplo: "O que você respondeu │
│ na primeira mensagem?" │
└──────────────────────────────────────┘
│
│ (quando conversa termina)
▼
┌──────────────────────────────────────┐
│ LONG-TERM MEMORY (MemoryService) │
│ │
│ memory_content = "P: Viagens? │
│ R: Safari, Cruzeiro, Ski" │
│ │
│ Válido por: Indefinido │
│ Armazenado em: MemoryService │
│ Acessado por: Agent com tool │
│ (PreloadMemoryTool) │
│ │
│ Exemplo: "O que você me recomendou │
│ semana passada?" │
└──────────────────────────────────────┘
🔐 Segurança & Privacidade
┌─────────────────────────────────────────┐
│ SESSION DATA (Firestore) │
│ collection: agente_busca_produtos_... │
│ │
│ document: {user_id}_slack_{channel_id} │
│ ├─ messages: [...] │
│ ├─ updated_at: timestamp │
│ ├─ expires_at: timestamp (60 minutos) │
│ └─ TTL: Auto-delete após expiração ✅ │
│ │
│ Proteção: Dados antigos deletados │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ MEMORY DATA (Firestore) │
│ collection: agente_busca_produtos_... │
│ │
│ document: {user_id}_{timestamp} │
│ ├─ content: extracted text │
│ ├─ user_id: indexed para busca │
│ └─ created_at: timestamp │
│ │
│ Proteção: Acesso por user_id │
│ (isolamento entre usuários) │
└─────────────────────────────────────────┘