O argumento estratégico para usar PostgreSQL como default de produção para memória de agentes é simples. O erro de implementação começa logo a seguir, quando a equipa coloca todo o estado do agente num documento oversized e chama-lhe esquema.
Se quer memória de agentes durável em produção, separe a verdade operacional dos payloads flexíveis. O PostgreSQL funciona melhor quando sessões, mensagens, execuções de ferramentas e resumos de memória têm ownership claro no esquema em vez de ficarem enterrados num único blob gigante.
Este tutorial é o passo prático seguinte ao nosso artigo sobre Redis vs PostgreSQL para memória de agentes e estado de sessão. O objetivo aqui não é pureza académica de base de dados. É ajudar equipas a desenhar um esquema fácil de operar, fácil de depurar e suficientemente flexível para workflows de agentes em evolução.
Porque os esquemas ingênuos falham em produção
A primeira versão mais comum da persistência de agentes é simples: uma tabela, uma chave primária e uma coluna JSON com tudo sobre a conversa, memória, estado das ferramentas e algum metadata de retrieval. Parece conveniente porque o runtime do agente pode escrever um único objeto com pouco esforço de modelação.
Essa conveniência desaparece quando o produto se torna real. As equipas começam a precisar de responder a perguntas como que sessões estão ativas, que chamada de ferramenta falhou, o que mudou entre um resumo de memória e o seguinte, e que estado tem de ser preservado para retoma e retry.
O problema não é o JSON em si. O problema é não distinguir verdade durável do workflow de dados de payload flexíveis. Quando essas preocupações ficam misturadas, as leituras ficam pesadas, a auditabilidade enfraquece e as atualizações parciais tornam-se confusas.
As tabelas base a criar primeiro
Um melhor ponto de partida em produção é dividir o modelo em algumas responsabilidades claras. A maioria das equipas não precisa de um esquema elaborado no primeiro dia. Precisa de um esquema que reflita como o sistema realmente se comporta.
agent_sessions
Esta tabela é o plano de controlo de cada conversa ou instância de workflow. Deve guardar a identidade durável da sessão, ligação ao tenant, estado do ciclo de vida, timestamps e um pequeno conjunto de campos de resumo úteis para operações.
session_messages
Esta tabela guarda o histórico cronológico das mensagens. Mantenha uma linha por mensagem ou transição de estado que tenha de poder ser reconstruída mais tarde. É muito mais fácil de inspecionar, replay e depurar do que mutar repetidamente um único transcript monolítico.
tool_runs
A execução de ferramentas merece a sua própria tabela. Se uma invocação falhar, fizer retry ou devolver output estruturado, isso não deve ficar escondido num transcript de chat. Operacionalmente, tool runs comportam-se mais como jobs do que como mensagens.
memory_snapshots
Agentes de longa duração precisam muitas vezes de um resumo durável ou de um estado de memória comprimido que evolui com o tempo. Mantenha isso separado das mensagens brutas. Assim consegue inspecionar como a memória mudou sem reconstruir tudo do transcript em cada leitura.
session_events
Esta tabela opcional torna-se útil mais cedo do que muitas equipas imaginam. Regista transições como handoff triggered, memória reconstruída, retry agendado, escalonamento aberto ou revisão humana pedida. É excelente para observabilidade e análise pós-incidente.
Quando usar JSONB e quando não usar
JSONB é útil, mas deve ser usado de forma deliberada. Use-o para payloads flexíveis que são incómodos de normalizar completamente e cuja estrutura pode evoluir com o tempo. Bons exemplos incluem inputs brutos de ferramentas, outputs de modelos, atributos de resumos de memória ou anotações de sessão que não são dimensões centrais de consulta.
Não use JSONB como desculpa para evitar modelar os campos que já sabe que precisa de filtrar, juntar, ordenar ou auditar. Estado, tenant, timestamps, sequence numbers, nomes de ferramentas, estados de erro e marcadores de versão devem normalmente ser colunas de primeira classe.
Como manter escritas simples e leituras úteis
Muitas equipas otimizam demasiado cedo para conveniência de escrita porque o runtime do agente gera estado rapidamente. Isso é compreensível, mas sistemas de produção não são avaliados apenas por throughput de escrita. São avaliados pela facilidade com que a equipa responde a perguntas durante incidentes, escalations de clientes e mudanças de produto.
Um bom compromisso é manter o caminho de escrita favorável a append: inserir uma linha de sessão uma vez, acrescentar mensagens como linhas, acrescentar tool runs como linhas e gravar memory snapshots como registos versionados em vez de os sobrescrever cegamente.
Onde o pgvector encaixa e onde não encaixa
As equipas confundem frequentemente dois problemas diferentes: estado de sessão durável e retrieval semântico. O pgvector pode ser útil se quiser embeddings dentro de PostgreSQL para retrieval, ranking ou lookups de memória. Isso não significa que a verdade principal da sessão deva tornar-se um problema de vetores.
A abordagem mais limpa é manter memória vetorizada ou artefactos de retrieval como uma preocupação separada. A verdade da sessão diz-lhe o que aconteceu. A infraestrutura de retrieval ajuda a encontrar o que pode ser relevante. São coisas relacionadas, mas não iguais.
Erros comuns de esquema
- guardar todo o estado num único objeto JSON porque parece rápido no primeiro dia,
- usar JSONB para campos que a equipa de operações precisa de filtrar constantemente,
- sobrescrever resumos de memória em vez de os versionar,
- esconder falhas de tool runs dentro dos logs de mensagens,
- e misturar estruturas de retrieval diretamente na verdade central da sessão.
O padrão vencedor não é normalização máxima. É clareza de fronteiras operacionais. O PostgreSQL torna-se poderoso para memória de agentes quando o esquema reflete como o workflow realmente precisa de ser operado.
References
Fale com a Alongside
Se a sua equipa está a passar de protótipo de IA para sistema de produção, o modelo de dados por trás do estado de sessão e da memória dos agentes torna-se uma decisão de engenharia com consequências de produto, cloud e segurança. A Alongside ajuda equipas a desenhar arquiteturas prontas para delivery que são mais fáceis de escalar, governar e operar sob restrições reais.