Como construir um agente de IA com memória persistente usando MongoDB Atlas, Voyage e LangGraph

Por que a maioria das demos de agentes para antes da memória

A maior parte das demonstrações de agentes de IA faz o seguinte: recebe um prompt, gera uma resposta plausível e termina. Mas um operador real — como o gestor de um evento com milhares de visitantes — precisa de um agente que lembre o que aconteceu em eventos anteriores, recupere contexto relevante sobre visitantes e infraestrutura, responda a mudanças operacionais em tempo real e escreva o resultado de volta como memória para a próxima situação semelhante.

Este tutorial da MongoDB mostra exatamente como construir esse tipo de agente, usando MongoDB Atlas, Voyage AI embeddings, LangGraph e rastreamento opcional com Langfuse. O cenário é o MongoDB Open, um torneio de tênis premium fictício no sexto dia de competição. A chuva se aproxima, a capacidade da área VIP coberta é limitada, e o operador precisa gerenciar duas jornadas de visitantes distintas simultaneamente.

Arquitetura: por que tudo no mesmo banco

A decisão de arquitetura mais importante deste tutorial é manter toda a memória do agente no MongoDB Atlas — estado operacional, memória semântica, embeddings de documentos visuais, ações do agente e checkpoints do LangGraph. A velocidade importa: se a chuva está a 20 minutos e o espaço VIP está lotando, o agente não pode esperar um pipeline de analytics em batch.

O Atlas funciona como sistema de registro e camada de recuperação simultaneamente. O agente não precisa sincronizar dados entre um banco operacional e um banco vetorial separado — o loop percebe-muda-age-reflete acontece inteiro em uma única camada de dados:

• Registros operacionais: visitantes, reservas, status do local, eventos climáticos
• Memória semântica: embeddings da Voyage AI com busca vetorial no Atlas
• Documentos visuais: imagens operacionais com embeddings multimodais
• Estado do agente: checkpoints do LangGraph

Pré-requisitos

Para rodar o projeto, você precisa de:

• Python 3.12 ou superior
• uv (gerenciador de pacotes)
• Cluster MongoDB Atlas com Vector Search habilitado (gratuito para começar)
• Chave de API da Anthropic (ou qualquer LLM de sua preferência)
• Chave de API da Voyage AI (gratuita)

Passo a passo de instalação

1. Clone o repositório e instale dependências:

git clone https://github.com/mongodb-developer/event-venue-operator.git
cd event-venue-operator
uv sync

2. Configure as variáveis de ambiente:

cp .env.example .env
# Edite .env com suas credenciais:
# MONGODB_URI, ANTHROPIC_API_KEY, VOYAGE_API_KEY

3. Inicialize o Atlas e popule os dados:

uv run python scripts/setup_atlas.py
uv run python scripts/seed_data.py
uv run python scripts/seed_visual_docs.py

4. Inicie o servidor:

uv run python -m event_venue_operator.server
# Acesse http://127.0.0.1:8000/

O design da memória em três camadas

O componente mais interessante do tutorial é o design da memória do agente. Em vez de um armazenamento vetorial genérico, o sistema usa namespaces para separar diferentes tipos de memória:

• (“guests”, guest_id): memória específica de cada visitante — histórico de eventos, preferências, interações anteriores
• (“fleet”, event_id): padrões operacionais do evento como um todo
• (“docs”, event_id): documentos visuais operacionais — mapas, plantas, documentos escaneados

Essa separação permite que o agente faça recuperação com escopo — buscar apenas a memória relevante para o visitante certo, no evento certo — sem precisar de múltiplos bancos de dados. O Atlas gerencia tudo com um modelo de dados flexível e busca vetorial integrada.

O que você constrói ao final

O projeto entrega uma aplicação FastAPI completa com:

• Interface guiada com quatro abas (dashboard, cenário, resultados e validação)
• Coleções no Atlas para estado operacional, memória semântica, ações e checkpoints
• Embeddings multimodais da Voyage armazenados no Atlas
• Busca vetorial para recuperação de memória
• Endpoint de recuperação híbrida (similaridade vetorial + pontuação lexical)
• Vision RAG que recupera documentos visuais e os passa para Claude Vision
• Script LangGraph executável que segue o cenário de chuva
• Configuração de deploy no Vercel

O repositório está disponível com licença MIT e deve ser tratado como demo de referência, não como plataforma de produção — não há autenticação, CI ou endpoint público do agente LangGraph.

Por que este padrão importa

O que torna este tutorial relevante para julho de 2026 é que ele resolve o problema que a maioria dos agentes ainda enfrenta: memória persistente que sobrevive a cada execução. Agentes que não escrevem de volta o que aprenderam são essencialmente stateless — recomeçam do zero a cada interação. O padrão MongoDB Atlas + LangGraph mostrado aqui é replicável para qualquer domínio operacional: logística, saúde, varejo, suporte ao cliente.

Para times brasileiros construindo agentes em produção, a combinação de embeddings Voyage (que têm suporte robusto a português) com Atlas Vector Search oferece um caminho maduro e bem documentado.