Ensinando Meus Agentes a Lembrar do Ontem

Meu cluster doméstico executa uma pequena frota de agentes. Eles me dizem qual lixeira deve ser levada para fora esta noite, o que está em promoção no supermercado e quantos artigos estão no meu repositório de blog. Eles são genuinamente úteis e têm a memória de um peixe dourado.

Cada mensagem começa do zero. Pergunte "o que eu te perguntei ontem?" e o roteador responde, com total confiança, que não tem acesso a nenhum histórico. Ele não está errado. Não havia histórico — apenas rastros se acumulando em uma ferramenta de observabilidade que nenhum agente poderia ler.

A solução é um banco de dados vetorial — Qdrant, neste caso. A parte interessante não é a solução. São as quatro coisas entre "Qdrant está em execução" e "Qdrant realmente responde", nenhuma das quais está na documentação de ninguém.

Por que Cloud, e por que a URL importa

O cluster é composto por três Raspberry Pis. Eles têm opiniões sobre serem solicitados a executar um banco de dados vetorial, fazer backup e criar instantâneas. Qdrant Cloud tem um nível gratuito com um gigabyte de armazenamento, que para memória conversacional é praticamente para sempre, e move armazenamento e backups de hardware que não tem nada a oferecer.

Você obtém um cluster e um endpoint. O endpoint se parece com isto:

https://11111111-2222-3333-4444-555555555555.eu-west-1-0.aws.cloud.qdrant.io:6333

Aquele :6333 final é a primeira coisa que custará uma tarde. O console mostra apenas o nome do host, e um nome de host simples resolve para a porta 443, onde a API REST não está ouvindo. O cliente não te diz que você está falando com a porta errada — ele simplesmente falha ao conectar, e você começa a olhar para políticas de rede e DNS em vez de para a string que você colou.

O nome do host não é um segredo. A chave da API é, e ela vive em um Secret criado fora de banda, exatamente como todas as outras credenciais neste cluster:

kubectl create secret generic qdrant-cloud -n kmcp-system \
  --from-literal=QDRANT_API_KEY='<key>'

Não está no repositório. Não está em um arquivo de valores. O repositório conhece o nome do segredo e nada mais.

A arquitetura

flowchart TD
    A["agentes kagent — porta de entrada do Telegram"] -->|"emitir spans OTLP"| B["Coletor — descarta ruído do framework"]
    B -->|"HTTPS"| C[("Langfuse Cloud — armazenamento de rastros")]
    D["CronJob — a cada 30 minutos"] -->|"API de leitura pública"| C
    D -->|"incorporar com FastEmbed — 384 dims"| E[("Qdrant Cloud — conversas")]
    F["servidor MCP — somente leitura"] -->|"qdrant-find"| E
    G["Agente de Recordação"] -->|"MCP sobre HTTP"| F
    H["Agente Roteador"] -->|"delegação A2A"| G
    A -.->|"mesma frota"| H

Duas rotas, deliberadamente separadas. Escritas vêm de um trabalho agendado que lê rastros que os agentes já emitem. Leituras passam por um servidor MCP que qualquer agente na frota pode chamar.

A alternativa seria deixar cada agente salvar sua própria conversa à medida que avança. Parece mais limpo e é pior: depende do modelo lembrar de chamar uma ferramenta, escreve a mesma conversa várias vezes quando um agente delega a outro e adiciona uma viagem de ida e volta de incorporação a cada resposta que o usuário está aguardando. Ler rastros que já existem não custa nada para os agentes e não pode ser esquecido.

Para as pessoas que aprovam isso

Salte para a próxima seção se você gosta de rastros de pilha.

Três coisas que vale a pena saber antes que alguém aprove uma construção semelhante.

Os dados já estavam lá. Nada novo está sendo coletado. Os agentes já estavam emitindo rastros para observabilidade; isso lê os mesmos rastros e os torna pesquisáveis. Nenhuma nova superfície de consentimento, nenhuma nova fonte de verdade, uma localização de armazenamento adicionada.

O custo de execução é zero e permanece assim. Nível gratuito em ambas as extremidades — um gigabyte de vetores e uma cota de rastros que uma casa não ameaça. As incorporações são calculadas em hardware que já foi pago. A linha de custo que importa não é a conta, é a meia hora por mês que alguém gasta quando uma versão precisa ser movida.

O escopo honesto. Isso torna "o que decidimos sobre X" respondível a partir de uma caixa de pesquisa em vez de da memória de alguém. Em escala doméstica, isso é um truque legal. Em escala de equipe — runbooks, decisões de arquitetura, relatórios de incidentes, integração — a mesma forma deixa de ser um truque, porque o custo de não tê-lo é cinco pessoas fazendo a mesma pergunta a cada trimestre e recebendo quatro respostas diferentes.

Onde a conversa realmente vive

A primeira versão do trabalho de ingestão leu input e output de cada rastro, os incorporou e armazenou zero pontos. Ambos os campos eram null em todos os 97 rastros.

Eles são null porque kagent não os define no nível do rastro. A conversa está nas observações — 57 delas para uma única pergunta, a maioria das quais são tubulações do framework. A troca voltada para o usuário está no punhado de GENERATION observações cujo input é uma lista de mensagens de chat:

def conversation_turn(observation):
    raw_input = observation.get("input")
    if not isinstance(raw_input, list) or not raw_input:
        return None
    # Chamadas internas do modelo carregam uma system_instruction e retornam um
    # function_call. Incorporar isso preenche o índice com prompt
    # boilerplate em vez de qualquer coisa que um humano disse.

Há uma segunda camada a ser descascada. A vez do usuário chega duplamente codificada — uma string JSON contendo uma lista de blocos de conteúdo — então o campo bruto é '[{"type": "text", "text": "qual lixeira deve ser levada para fora esta noite?"}]'. Incorpore isso literalmente e você terá incorporado a pontuação tanto quanto a pergunta.

A lição se generaliza além deste stack: olhe para um registro real antes de escrever o parser. Eu escrevi um parser plausível contra um esquema plausível, e o esquema era ficção.

Deduplicação que você não pode esquecer de fazer

Cada execução olha para trás em uma janela mais ampla do que sua própria programação, então uma execução falhada se recupera na próxima. Isso só funciona se reler um rastro for gratuito:

POINT_NAMESPACE = uuid.UUID("6f9619ff-8b86-d011-b42d-00c04fc