Com o banco de memória, é possível criar memórias de longo prazo com base nas conversas entre o usuário e seu agente. Nesta página, descrevemos como funciona a geração de recordações, como personalizar a extração delas e como acionar a geração.
Noções básicas sobre a geração de memória
O Memory Bank extrai recordações de dados de origem e as organiza automaticamente para uma coleção específica (definida por um scope) adicionando, atualizando e removendo recordações ao longo do tempo.
Quando você aciona a geração de memórias, o Banco de memórias realiza as seguintes operações:
Extração: extrai informações sobre o usuário das conversas dele com o agente. Somente as informações que corresponderem a pelo menos um dos tópicos de memória da instância serão mantidas.
Consolidação: identifica se as recordações atuais com o mesmo escopo precisam ser excluídas ou atualizadas com base nas informações extraídas. O Banco de recordações verifica se as novas recordações não são duplicadas ou contraditórias antes de mesclá-las com as existentes. Se as recordações atuais não se sobrepuserem às novas informações, uma nova recordação será criada.
As recordações só podem ser extraídas de texto, arquivos inline e dados de arquivos no conteúdo de origem. Todo o outro conteúdo, incluindo chamadas de função e respostas, é ignorado ao gerar recordações.
As recordações podem ser extraídas de imagens, vídeos e áudios fornecidos pelo usuário. Se o contexto fornecido pela entrada multimodal for considerado significativo pelo banco de memória para interações futuras, uma memória textual poderá ser criada, incluindo informações extraídas da entrada. Por exemplo, se o usuário fornecer uma imagem de um golden retriever com o texto "Este é meu cachorro", o Banco de memória vai gerar uma memória como "Meu cachorro é um golden retriever".
Tópicos de recordações
Os "Temas de memória" identificam quais informações o Banco de memória considera significativas e, portanto, devem ser mantidas como recordações geradas. O Memory Bank é compatível com dois tipos de temas de memória:
Tópicos gerenciados: o rótulo e as instruções são definidos pelo Memory Bank. Basta informar o nome do tópico gerenciado. Exemplo:
Dicionário
memory_topic = { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } }Com base em classes
from vertexai.types import ManagedTopicEnum from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic memory_topic = MemoryTopic( managed_memory_topic=ManagedMemoryTopic( managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO ) )Tópicos personalizados: o rótulo e as instruções são definidos por você ao configurar sua instância do Memory Bank. Eles serão usados no comando da etapa de extração do Banco de memória. Exemplo:
Dicionário
memory_topic = { "custom_memory_topic": { "label": "business_feedback", "description": """Specific user feedback about their experience at the coffee shop. This includes opinions on drinks, food, pastries, ambiance, staff friendliness, service speed, cleanliness, and any suggestions for improvement.""" } }Com base em classes
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic memory_topic = MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="business_feedback", description="""Specific user feedback about their experience at the coffee shop. This includes opinions on drinks, food, pastries, ambiance, staff friendliness, service speed, cleanliness, and any suggestions for improvement.""" ) )Ao usar tópicos personalizados, também é recomendável fornecer exemplos de few-shot para demonstrar como as recordações devem ser extraídas da conversa.
Por padrão, o Memory Bank mantém todos os seguintes tópicos gerenciados:
- Informações pessoais (
USER_PERSONAL_INFO): informações pessoais significativas sobre o usuário, como nomes, relacionamentos, hobbies e datas importantes. Por exemplo, "Trabalho no Google" ou "Meu aniversário de casamento é em 31 de dezembro". - Preferências do usuário (
USER_PREFERENCES): gostos, não gostos, estilos ou padrões declarados ou implícitos. Por exemplo, "Prefiro o assento do meio". - Principais eventos de conversa e resultados de tarefas (
KEY_CONVERSATION_DETAILS): marcos ou conclusões importantes no diálogo. Por exemplo, "Comprei passagens aéreas de ida e volta entre JFK e SFO. Vou sair em 1º de junho de 2025 e voltar em 7 de junho de 2025". - Instruções explícitas de lembrar / esquecer (
EXPLICIT_INSTRUCTIONS): informações que o usuário pede explicitamente ao agente para lembrar ou esquecer. Por exemplo, se o usuário disser "Lembre-se de que eu uso principalmente Python", o Banco de memória vai gerar uma memória como "Eu uso principalmente Python".
Isso é equivalente a usar o seguinte conjunto de tópicos de memória gerenciada:
Dicionário
memory_topics = [
{"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
{"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
{"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
{"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
]
Com base em classes
from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
memory_topics = [
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]
Se quiser personalizar os temas que o Banco de memórias mantém, defina os temas na sua configuração de personalização ao configurar o Banco de memórias.
Gerando recordações
Para concluir as etapas demonstradas neste guia, primeiro siga as instruções em Configurar o Memory Bank.
Você pode acionar a geração de memórias usando GenerateMemories no final de uma sessão ou em intervalos regulares dentro de uma sessão. A geração de memória extrai o contexto principal das conversas de origem e o combina com as memórias existentes para o mesmo escopo. Por exemplo, é possível criar memórias no nível da sessão usando um escopo como {"user_id": "123", "session_id": "456"}. As recordações com o mesmo escopo podem ser consolidadas e recuperadas juntas.
Ao chamar GenerateMemories, você precisa fornecer a conversa de origem usando Sessões do mecanismo de agente ou diretamente no formato JSON:
Formato JSON
Forneça a conversa de origem diretamente no formato JSON se você estiver usando um armazenamento de sessão diferente das sessões do Agent Engine:
client.agent_engines.memories.generate(
name=agent_engine.api_resource.name,
direct_contents_source={
"events": EVENTS
},
scope=SCOPE,
config={
"wait_for_completion": True
}
)
Substitua:
- EVENTS: lista de dicionários de conteúdo. Exemplo:
[
{
"content": {
"role": "user",
"parts": [
{"text": "I'm work with LLM agents!"}
]
}
}
]
- SCOPE: um dicionário que representa o escopo das memórias geradas. Por exemplo,
{"session_id": "MY_SESSION"}. Somente as memórias com o mesmo escopo são consideradas para consolidação.
Sessões do Agent Engine
Com as sessões do Agent Engine, o Memory Bank usa eventos de sessão como a conversa de origem para geração de memória.
Para definir o escopo das recordações geradas, o Banco de recordações extrai e usa o ID do usuário da sessão por padrão. Por exemplo, o escopo das memórias é armazenado como {"user_id": "123"} se o user_id da sessão for "123". Você também pode fornecer um scope diretamente, o que substitui o uso do user_id da sessão como escopo.
client.agent_engines.memories.generate(
name=agent_engine.api_resource.name,
vertex_session_source={
"session": "SESSION_NAME"
},
# Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
scope=SCOPE,
config={
"wait_for_completion": True
}
)
Substitua:
SESSION_NAME: o nome da sessão.
(Opcional) SCOPE: um dicionário que representa o escopo das recordações geradas. Por exemplo,
{"session_id": "MY_SESSION"}. Somente as memórias com o mesmo escopo são consideradas para consolidação. Se não for fornecido,{"user_id": session.user_id}será usado.
GenerateMemories é uma operação de longa duração. Quando a operação for concluída, o AgentEngineGenerateMemoriesOperation vai conter uma lista de recordações geradas, se houver:
AgentEngineGenerateMemoriesOperation(
name="projects/.../locations/.../reasoningEngines/.../operations/...",
done=True,
response=GenerateMemoriesResponse(
generatedMemories=[
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="CREATED",
),
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="UPDATED",
),
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="DELETED",
),
]
)
)
Cada memória gerada inclui a action que foi realizada nela:
CREATED: indica que uma nova recordação foi adicionada, representando um conceito novo que não foi capturado pelas recordações atuais.UPDATED: indica que uma memória existente foi atualizada, o que acontece se ela abordava conceitos semelhantes às informações extraídas recentemente. O fato da memória pode ser atualizado com novas informações ou permanecer o mesmo.DELETED: indica que a memória existente foi excluída porque as informações dela eram contraditórias às novas informações extraídas da conversa.
Para memórias CREATED ou UPDATED, use GetMemories para recuperar o conteúdo completo da memória. Recuperar DELETED recordações resulta em um erro 404.
Gerando recordações em segundo plano
GenerateMemories é uma operação de longa duração. Por padrão, client.agent_engines.generate_memories é uma função de bloqueio e continua pesquisando a operação até que ela seja concluída. Executar a geração de recordações como uma operação de bloqueio é útil quando você quer inspecionar manualmente as recordações geradas ou notificar os usuários finais sobre quais recordações foram geradas.
No entanto, para agentes de produção, geralmente é melhor executar a geração de memória em segundo plano como um processo assíncrono. Na maioria dos casos, o cliente não precisa usar a saída da execução atual. Portanto, não é necessário incorrer em latência adicional esperando uma resposta. Se você quiser que a geração de memória seja executada em segundo plano, defina wait_for_completion como False:
client.agent_engines.memories.generate(
...,
config={
"wait_for_completion": False
}
)
Consolidar recordações pré-extraídas
Como alternativa ao processo de extração automática do Banco de memórias, você pode fornecer memórias pré-extraídas diretamente. As recordações de origem direta serão consolidadas com as recordações atuais do mesmo escopo. Isso pode ser útil quando você quer que seu agente ou um humano no loop seja responsável por extrair memórias, mas ainda quer aproveitar a consolidação do banco de memória para garantir que não haja memórias duplicadas ou contraditórias.
client.agent_engines.memories.generate(
name=agent_engine.api_resource.name,
direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
scope=SCOPE
)
Substitua:
FACT: o fato pré-extraído que precisa ser consolidado com as memórias atuais. É possível fornecer até cinco fatos pré-extraídos em uma lista como esta:
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}SCOPE: um dicionário que representa o escopo das memórias geradas. Por exemplo,
{"session_id": "MY_SESSION"}. Somente as memórias com o mesmo escopo são consideradas para consolidação.