arquitetura-de-agente-sempre-ativo

/arquitetura-de-agente-sempre-ativo — Construindo Agentes Que Nunca Esquecem

Você está projetando a arquitetura para um agente de IA sempre ativo com memória episódica. Isto não é um chatbot com uma longa janela de contexto. Isto é um sistema que persiste estado entre sessões, gerencia sua própria hierarquia de memória, executa como um serviço e mantém identidade por semanas e meses. O insight central: trate o LLM como uma CPU que opera em memória gerenciada, não como uma função sem estado.

Pontos de Decisão

Árvore de Seleção de Framework de Memória

Q1: Você quer um runtime de agente completo (servidor, APIs, ferramentas)?
├─ Sim → Use Letta (mais completo, pronto para produção)
└─ Não, eu tenho meu próprio loop de agente
   ├─ Q2: Você precisa de rastreamento temporal/de relacionamentos?
   │  ├─ Sim → Use Zep/Graphiti (melhor grafo de conhecimento temporal)
   │  └─ Não → Vá para Q3
   │     ├─ Q3: Você precisa de híbrido grafo + vetorial?
   │     │  ├─ Sim → Use Mem0 (modo grafo)
   │     │  └─ Não → Vá para Q4
   │     │     ├─ Q4: Já está usando LangGraph?
   │     │     │  ├─ Sim → Use LangMem
   │     │     │  └─ Não → Use pgvector ou Chroma
   └─ Quer zero dependências? → SQLite personalizado + embeddings locais

Gatilhos Centrais de Remoção de Memória

Gatilho	Limiar	Ação
Estouro de Tamanho	Memória núcleo > 4KB	Sumarizar bloco menos recente, mover resumo para arquivo
Decaimento por Idade	Dados não usados > 30 dias	Marcar para revisão de compactação
Queda de Relevância	Pontuação de acesso < 0,3	Mover para memória de arquivo com tag de decaimento
Substituição pelo Usuário	Usuário diz "esqueça X"	Remoção imediata + lápide de arquivo
Detecção de Conflito	Fatos contraditórios armazenados	Solicitar que o agente reconcilie ou pergunte ao usuário

Critérios de Seleção de BD Vetorial

Se latência_de_consulta_necessária < 10ms E tamanho_dos_dados > 100M vetores:
    → Use Qdrant (otimizado para velocidade)
Senão se já_usa_postgresql:
    → Use pgvector (banco único, operações mais simples)
Senão se precisa_de_busca_híbrida (palavra-chave + semântica):
    → Use Weaviate (melhor híbrido)
Senão se prefere_zero_ops:
    → Use Pinecone (totalmente gerenciado)
Senão:
    → Use Chroma (local primeiro, API simples)

Decisão de Roteamento de Nível de Memória

Entrada: Mensagem do usuário ou observação do agente
│
├─ Contém atualização de identidade/preferência?
│  └─ Sim → Atualizar memória núcleo, persistir imediatamente
├─ Requer contexto de conversa?
│  └─ Sim → Pesquisar memória de recordação (histórico da conversa)
├─ Precisa de conhecimento factual?
│  └─ Sim → Pesquisar memória de arquivo (armazenamento vetorial)
└─ Dados externos necessários?
   └─ Sim → Usar ferramentas externas (APIs, arquivos, etc.)

Modos de Falha

Cascata de Corrupção de Memória

Sintomas: Deriva de personalidade do agente, respostas contraditórias, conflitos na memória núcleo Causa Raiz: Escritas concorrentes na memória núcleo sem bloqueio, ou atualizações parciais com falha Regra de Detecção: Se o tamanho da memória núcleo cair subitamente >50% ou contiver JSON/YAML malformado Procedimento de Recuperação:

1. Parar o agente imediatamente para evitar mais corrupção
2. Restaurar memória núcleo do último backup válido (< 1hr de idade)
3. Reexecutar o registro de conversa desde o backup para reconstruir atualizações perdidas
4. Implementar bloqueios de escrita em atualizações de memória núcleo antes de reiniciar

Degradação da Busca Vetorial

Sintomas: Resultados de busca cada vez menos relevantes, agente não consegue encontrar fatos armazenados recentemente Causa Raiz: Deriva do modelo de embedding, corrupção do índice, ou nenhuma compactação de memória Regra de Detecção: Se a similaridade cosseno média dos 3 principais resultados < 0,7 para consultas conhecidas Procedimento de Recuperação:

1. Executar verificação de consistência de embedding em uma amostra aleatória de 100 vetores
2. Se >10% mostrarem embeddings anômalos, reconstruir todo o índice
3. Implementar fixação da versão do modelo de embedding
4. Adicionar monitoramento de deriva de embedding para prevenir recorrência

Deadlock na Camada de Persistência

Sintomas: Agente trava em operações de memória, timeouts de conexão com banco de dados Causa Raiz: Leitura/escrita simultâneas nos mesmos blocos de memória, pool de conexões insuficiente Regra de Detecção: Se a operação de memória levar >30s ou o banco de dados mostrar timeouts de espera de bloqueio Procedimento de Recuperação:

1. Matar conexões pendentes para liberar bloqueios
2. Implementar lógica de retry com backoff exponencial para operações de memória
3. Adicionar pool de conexões com limites máximos de conexão
4. Revisar níveis de isolamento de transação para atualizações de memória

Explosão da Janela de Contexto

Sintomas: Custos de API disparam, latência de resposta aumenta, erros de limite de tokens Causa Raiz: Inchaço da memória núcleo, recuperação de muitos blocos de arquivo por consulta Regra de Detecção: Se a média de tokens por requisição > 80% do limite de contexto do modelo Procedimento de Recuperação:

1. Auditar tamanho da memória núcleo - comprimir ou arquivar blocos superdimensionados
2. Reduzir contagem de resultados de busca de arquivo do padrão (10 → 5)
3. Implementar contagem de tokens antes de chamadas LLM
4. Adicionar alertas de monitoramento de custo para >$1/conversa

Vazamento de Memória - Crescimento Ilimitado

Sintomas: Tamanho do banco de dados cresce linearmente, desempenho de busca degrada ao longo do tempo Causa Raiz: Sem compactação de memória, inserção de fatos duplicados, coleta de lixo ausente Regra de Detecção: Se o tamanho total da memória crescer >100MB/mês com uso normal Procedimento de Recuperação:

1. Executar deduplicação de fatos na memória de arquivo (similaridade cosseno > 0,92)
2. Implementar sumarização de conversas para memória de recordação >7 dias de idade
3. Adicionar pontuação de relevância com poda automática de memórias de baixa pontuação
4. Agendar trabalhos de compactação semanais

Exemplos Práticos

Exemplo: Construindo um Assistente de Pesquisa Pessoal

Cenário: Projetar arquitetura para um agente que ajuda com pesquisa técnica, lembra suas preferências e constrói conhecimento ao longo de meses.

Passo 1 - Design de Níveis de Memória

Memória Núcleo (2KB):
- Nome do usuário: "Sarah"
- Domínios de pesquisa: ["aprendizado de máquina", "sistemas distribuídos"]
- Fontes de artigo preferidas: ["arxiv", "acm digital library"]
- Estilo de escrita: "detalhado com exemplos de código"
- Projeto atual: "otimização de treinamento distribuído"

Memória de Recordação:
- Todas as conversas em PostgreSQL com busca de texto completo
- Janela de retenção de 30 dias, depois sumarizado

Memória de Arquivo:
- Resumos de artigos, insights extraídos, trechos de código
- pgvector no PostgreSQL (já usando para recordação)
- nomic-embed-text para embedding local (privacidade + custo)

Passo 2 - Decisão de Seleção de Framework Seguindo a árvore de decisão:

• Precisa de runtime completo de agente? Não (construindo customizado)
• Precisa de rastreamento temporal? Não (fatos de pesquisa são principalmente atemporais)
• Precisa de grafo+vetorial? Não (busca semântica simples é suficiente)
• Já está usando LangGraph? Não
• → Decisão: pgvector + PostgreSQL

Passo 3 - Implementação do Loop do Agente

async def passo_de_pesquisa(consulta_do_usuario: str):
    # Carregar memória núcleo
    nucleo = carregar_memoria_nucleo()  # Prefs do usuário, projeto ativo
    
    # Verificar se consulta se relaciona ao projeto atual
    if "otimização" in consulta_do_usuario.lower():
        # Pesquisar arquivo para conhecimento específico do projeto
        artigos_relevantes = pesquisar_arquivo("otimização de treinamento distribuído")
        contexto = f"Contexto do projeto atual: {artigos_relevantes}"
    else:
        # Pesquisar conhecimento geral do domínio
        contexto = pesquisar_arquivo(consulta_do_usuario)
    
    # Construir prompt com memória núcleo + contexto recuperado
    prompt_sistema = f"""
    Você é o assistente de pesquisa de Sarah.
    Preferências do usuário: {nucleo['preferencias']}
    Projeto atual: {nucleo['projeto_atual']}
    
    Contexto recuperado: {contexto}
    """
    
    resposta = await llm.chat([
        {"role": "system", "content": prompt_sistema},
        {"role": "user", "content": consulta_do_usuario}
    ])
    
    # Persistir interação
    salvar_em_recordacao(consulta_do_usuario, resposta)
    
    return resposta

O que um novato deixaria passar:

• Armazenar artigos brutos em vez de insights extraídos no arquivo
• Não implementar busca de conversa (memória de recordação)
• Colocar muita coisa na memória núcleo (lista de domínios de pesquisa com 50 entradas)
• Nenhuma estratégia de compactação de memória

O que um especialista percebe:

• Memória núcleo permanece focada em "identidade de trabalho", não em conhecimento
• Memória de arquivo recebe fatos selecionados, não documentos brutos
• Implementa busca antes da recuperação (agente decide o que é relevante)
• Planeja crescimento de memória desde o primeiro dia

Portões de Qualidade

Lista de Verificação de Validação de Implantação

• SLO de Latência de Memória: Memória núcleo carrega em <100ms, busca de arquivo completa em <500ms
• Consistência de Memória: Memória núcleo sobrevive a reinicialização do agente sem corrupção (testar com morte deliberada)
• Relevância de Busca: Os 3 principais resultados de arquivo têm similaridade cosseno >0,6 para consultas conhecidas
• Regras de Dimensionamento de Memória: Memória núcleo ≤4KB, retenção de recordação ≤30 dias, blocos de arquivo ≤1KB cada
• Durabilidade de Persistência: Todas as atualizações de memória sobrevivem à reinicialização do banco de dados (conformidade ACID verificada)
• Controles de Custo: Operações de memória custam <$0,01/conversa a 100 conversas/dia
• Cronograma de Compactação: Compactação de memória é executada semanalmente e reduz o tamanho total em ≥10%
• Consistência de Identidade: Personalidade do agente permanece estável em mais de 50 sessões de conversa
• Recuperação de Inicialização a Frio: Agente lida graciosamente com estado de memória vazia (fluxo de integração funciona)
• Verificação de Backup: Backup de memória restaura com sucesso e preserva a identidade do agente

Limites NÃO-PARA

NÃO use este skill para:

• Escolher dados de treinamento do agente → Use /sempre-ativo-entradas-do-agente - esse skill cobre quais dados alimentar o agente, este cobre como armazená-los e recuperá-los
• Brainstorming de aplicações do agente → Use /sempre-ativo-aplicacoes-do-agente - esse skill cobre ideação de casos de uso, este cobre implementação técnica
• Segurança e privacidade do agente → Use /sempre-ativo-seguranca-do-agente - esse skill cobre governança de dados, consentimento e segurança; este assume que esses já estão projetados
• Padrões agenticos gerais → Use /padroes- agenticos - esse skill cobre loops ReAct, uso de ferramentas, planejamento; este cobre a camada de persistência subjacente
• Tarefas de agente de uso único → Use /criador-de-agente - se o agente não precisa lembrar entre sessões, você não precisa de arquitetura sempre ativa
• Design de esquema de banco de dados → Este skill assume que você entende conceitos básicos de banco de dados; use skills específicas de banco de dados para otimização de esquema
• Estratégias de otimização de custo → Este skill menciona considerações de custo, mas não aprofunda otimização; delegue a skills específicas de custo