AgentLoop:Usar um memory store

1. Selecionar uma fonte de dados

Insira um Memory Store Name e uma Description opcional e selecione o tipo de fonte de dados.

Clique em Next. Não é possível alterar o tipo de fonte de dados após a criação do memory store. Defina como preparar os dados antes de prosseguir.

2. Configurar condições de filtro ou schema

{
  "sourceId": "conversation-001",
  "messages": [{"role": "user", "content": "I prefer light, mildly spicy dishes."}],
  "timestamp": 1788796800,
  "userId": "user-001",
  "agentId": "cooking-assistant",
  "appId": "cooking-app",
  "runId": "",
  "metadata": {},
  "lineage": {"sourceKind": "dataset"}
}

3. Configurar estratégias

Para a verificação inicial, selecione Fact Extraction e Merge Update e mantenha os parâmetros padrão. Para acumular perfis de usuário com base em hábitos, selecione Consumer User Profile. Para armazenar contexto de negócios corporativos, escolha Enterprise Digital Twin. Para definir objetivos específicos de extração, opte por Custom Instructions.

Em Scope and Audit, especifique um tipo de identificador de negócios obrigatório para recuperação, como userId. Para detalhes sobre os parâmetros e as diferenças entre os dois modos de armazenamento, consulte Configure memory extraction and storage strategies.

4. Visualizar e criar

Verifique a fonte de dados, as condições de filtro e o resumo da estratégia em Preview and Confirm. Cole uma amostra representativa e clique em Run Preview para visualizar fatos extraídos, ações de armazenamento e motivos para ignorar conteúdo. Para fontes de agent trace ou Dataset, também é possível amostrar dados da fonte configurada sem colar uma amostra.

Uma pré-visualização não grava memórias formais. Se a pré-visualização falhar, corrija a configuração ou a entrada e execute-a novamente. Após confirmar, clique em Create Memory Store. Para o formato da amostra, consulte Configure memory extraction and storage strategies.

Depois que o memory store for criado, acesse a página Overview para verificar o status do memory store e da fonte de dados. Para fontes de agent trace ou Dataset, visualize o progresso do consumo, a janela de consumo mais recente e o erro mais recente. Clique em Pause Consumption ou Resume Consumption para controlar leituras subsequentes.

Criar uma chave de API

Acesse a aba API Key do memory store, crie e copie uma chave de API. A credencial vincula-se ao espaço e ao memory store correspondentes. Vá até a aba Integration e copie o endpoint da região de destino. Ao usar as APIs de memória, não é necessário especificar o nome do espaço ou do memory store nas solicitações.

Armazene a credencial em uma variável de ambiente do lado do servidor ou em um gerenciador de segredos. O exemplo a seguir usa a API HTTP. Substitua os espaços reservados pela configuração fornecida na página atual:

export AGENTLOOP_ENDPOINT="<Endpoint copied from the Integration tab>"
export AGENTLOOP_API_KEY="<API key of the current memory store>"

Novos recursos precisam de tempo para ficarem prontos. Antes da primeira chamada, siga as instruções na aba Integration para confirmar que o recurso está disponível.

Gravar uma conversa

A solicitação a seguir associa uma conversa ao usuário de negócios user-001 e usa infer: true para solicitar a extração de memória de longo prazo.

curl -X POST "$AGENTLOOP_ENDPOINT/v1/memories" \
  -H "Authorization: Token $AGENTLOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "I prefer light, mildly spicy home-style dishes."},
      {"role": "assistant", "content": "I will consider your preferences when recommending dishes."}
    ],
    "user_id": "user-001",
    "infer": true
  }'

Primeiro, verifique se a resposta foi bem-sucedida. Após a aceitação de uma solicitação de gravação, as memórias de longo prazo ainda precisam passar por extração e armazenamento assíncronos. Uma mensagem do assistente informando que a informação foi memorizada não substitui a verificação do resultado no lado do servidor.

Recuperar memórias na aplicação

curl -X POST "$AGENTLOOP_ENDPOINT/v2/memories/search" \
  -H "Authorization: Token $AGENTLOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are this user's dietary preferences?",
    "user_id": "user-001",
    "top_k": 5
  }'

O valor de user_id deve ser igual ao usado durante a operação de gravação. top_k especifica o número máximo de resultados a retornar. Também é possível usar a API a seguir para listar memórias por usuário de negócios e verificar se os dados foram gravados.

curl -X POST "$AGENTLOOP_ENDPOINT/v2/memories" \
  -H "Authorization: Token $AGENTLOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-001", "limit": 20}'

Para uma aplicação Python, escolha Integration > Python SDK, instale e inicialize o MemoryClient com base no exemplo da página. Utilize a versão, os métodos e os parâmetros fornecidos na página.

Verificar resultados de recuperação

Acesse a aba Long-term Memory Retrieval, insira "What are this user's dietary preferences?", defina User ID como user-001, configure topK e clique em Start Retrieval.

Adicione condições de filtro como App ID, Agent ID, Run ID, kind e category conforme necessário. O operador AND combina múltiplos IDs de negócios. Para consultar preferências entre sessões de um usuário, não adicione um ID de execução não relacionado à memória alvo.

Os cartões de resultados exibem o conteúdo da memória e informações disponíveis sobre classificação, revisão, origem, edição manual e status de revisão. Verifique se o significado corresponde à entrada. O modelo não precisa reproduzir mensagens palavra por palavra nem gerar um número fixo de memórias. Uma pontuação indica relevância da recuperação, não precisão factual.

Editar e excluir memórias

Abra os detalhes de uma memória, clique em Edit, modifique o conteúdo da memória e clique em Save. Após salvar com sucesso, atualize os resultados e verifique o conteúdo mais recente. Se um conflito de revisão for relatado, reabra os detalhes para ler a versão mais recente antes de decidir como modificar a memória.

Use a operação de exclusão em um cartão de memória para remover conteúdos desnecessários. Verifique a memória alvo antes de confirmar. Não trate a exclusão de dados de origem, a exclusão de uma memória de longo prazo e a exclusão de um memory store inteiro como a mesma operação.

Após ativar a proteção contra edição manual, novas alterações propostas pela extração automática para conteúdo revisado manualmente entram no estado de revisão pendente, e o conteúdo original é retido. Consulte a origem e os registros de auditoria para determinar o motivo. Para detalhes da estratégia, consulte Configure memory extraction and storage strategies.

Visualizar registros de origem e recuperação

Se um registro de memória fornecer informações de origem e existir um log de gravação correspondente, use a entrada de origem para visualizar a entrada. Se a página retornar um ID de evento de recuperação, acesse Audit Details para inspecionar a consulta. Para uma visão geral, consulte View memory audits and statistics.

Por que não há resultados disponíveis após uma gravação bem-sucedida?

Primeiro, confirme o memory store e a região associados à chave de API. Em seguida, verifique se o mesmo identificador de usuário está sendo usado para gravação e recuperação e se filtros adicionais excessivos estão aplicados. Para escrita manual, verifique eventos de entrada. Para fontes de agent trace e Dataset, examine o status de consumo, condições de filtro, posição inicial e o erro mais recente. Depois, use as auditorias de extração e armazenamento para determinar se o processamento está em andamento, se o conteúdo foi excluído por uma estratégia ou se está pendente de revisão.

Por que consigo visualizar resultados na pré-visualização, mas não consigo recuperá-los?

Uma pré-visualização de amostra não grava memórias formais. Envie uma entrada real ou permita que a fonte de dados consuma o registro correspondente e recupere memórias somente após a conclusão do armazenamento.

Alterar uma estratégia reprocessa todos os dados históricos?

Após salvar uma estratégia, visualize a nova versão no histórico de versões. Memórias históricas não são reconstruídas automaticamente na íntegra ao salvar a estratégia. Para verificar o efeito de uma nova estratégia, execute primeiro uma pré-visualização de amostra e observe as entradas reais subsequentes.

O que fazer se o consumo parar após alterações nos campos do dataset de origem?

Verifique o erro mais recente na página Overview e confirme se os nomes e tipos dos campos fixos e dos campos adicionais em uso ainda atendem às convenções especificadas durante a criação. Não retome o consumo repetidamente para contornar erros de schema. Corrija os dados primeiro e depois verifique o status do consumo.