Configurar o Memory Bank da Agent Platform

Para usar o Memory Bank da Agent Platform, primeiro crie e configure uma instância da Gemini Enterprise Agent Platform. Essa instância gerencia suas memórias e pode ser integrada aos seus agentes em vários tempos de execução.

Este documento explica como configurar seu projeto do Google Cloud , instalar as bibliotecas necessárias e criar ou atualizar uma instância com configurações personalizadas como tópicos e TTL.

Primeiros passos

Antes de trabalhar com o Memory Bank, você precisa configurar seu ambiente.

Configurar o projeto do Google Cloud

Cada projeto pode ser identificado de duas formas: pelo número ou pelo ID. O PROJECT_NUMBER é criado automaticamente quando você cria o projeto, enquanto o PROJECT_ID é criado por você ou por quem criou o projeto. Para configurar um projeto:

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

Ter os papéis necessários

Para receber as permissões necessárias a fim de usar o Banco de memória, peça que o admin conceda a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Se você estiver fazendo solicitações ao Memory Bank de um agente implantado no Google Kubernetes Engine ou no Cloud Run, verifique se a conta de serviço tem as permissões necessárias. O agente de serviço do Reasoning Engine Service já tem as permissões necessárias para ler e gravar memórias. Portanto, as solicitações de saída do Agent Runtime já têm permissão para acessar o Memory Bank.

Instalar bibliotecas

Nesta seção, presumimos que você configurou um ambiente de desenvolvimento em Python ou está usando um ambiente de execução com um ambiente de desenvolvimento em Python (como o Colab).

Instale o SDK da Agent Platform:

pip install google-cloud-aiplatform>=1.111.0

Autenticação

Siga as instruções em Autenticar na Vertex AI.

Configurar um cliente do SDK da Agent Platform

Execute o código a seguir para configurar um cliente do SDK da Agent Platform:

SDK da plataforma de agentes 

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION",
)

em que

Criar ou atualizar uma instância da Agent Platform

Para começar a usar o Memory Bank, você precisa de uma instância da Agent Platform. Se você ainda não tiver uma instância, crie uma usando a configuração padrão:

agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Platform resource name. You will need the
# resource name to interact with your Agent Platform instance later on.
print(agent_engine.api_resource.name)

Se você quiser personalizar o comportamento da configuração da sua instância do Memory Bank nova ou atual, consulte Configurar sua instância do Agent Platform para o Memory Bank. Por exemplo, é possível especificar quais informações o Memory Bank considera significativas para persistir.

Sua instância da Agent Platform é compatível com sessões e Memory Bank prontos para uso. Nenhum agente é implantado quando você cria a instância. Para usar o Agent Runtime, você precisa fornecer o agente que será implantado ao criar ou atualizar a instância do Agent Platform.

Depois de ter uma instância do Agent Platform, use o nome dela para ler ou gravar memórias. Exemplo:

# Generate memories using your Memory Bank instance.
client.agent_engines.memories.generate(
  # `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
  name=agent_engine.api_resource.name,
  ...
)

Usar com o Agent Runtime

Embora o Memory Bank possa ser usado em qualquer ambiente de execução, você também pode usar o Memory Bank com o ambiente de execução do agente para ler e gravar memórias do agente implantado.

Para implantar um agente com o Memory Bank na Plataforma de Agentes, primeiro configure seu ambiente para o Agent Runtime. Em seguida, prepare seu agente para ser implantado no Agent Runtime com integração de memória. O agente implantado precisa fazer chamadas para ler e gravar memórias conforme necessário.

AdkApp

Se você estiver usando o modelo do Kit de Desenvolvimento de Agente da Plataforma de Agentes, o agente usará o VertexAiMemoryBankService por padrão quando for implantado na Agent Platform. Isso significa que as ferramentas de memória do ADK leem memórias do Memory Bank.

from google.adk.agents import Agent
from vertexai.preview.reasoning_engines import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Runtime.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

# Update an existing Agent Runtime to add or modify the Runtime.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

Substitua:

  • STAGING_BUCKET: o bucket do Cloud Storage que você vai usar para preparar o tempo de execução do agente.

Para mais informações sobre como usar o Memory Bank com o ADK, consulte o Guia de início rápido com o kit de desenvolvimento de agentes.

Agente personalizado

Você pode usar o Memory Bank com seu agente personalizado implantado no tempo de execução do agente. Nesse caso, seu agente precisa orquestrar chamadas para o Memory Bank para acionar geração de memória e recuperação de memória chamadas.

O aplicativo implantado no Agent Runtime pode ler as variáveis de ambiente GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_AGENT_ENGINE_ID para inferir o nome do Agent Runtime do ambiente:

project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

Se você estiver usando o agente de serviço padrão para seu agente no tempo de execução do agente, ele já terá permissão para ler e gravar memórias. Se você estiver usando uma conta de serviço do cliente, precisará conceder permissões à sua conta de serviço para ler e gravar memórias. As permissões necessárias dependem das operações que o agente precisa realizar. Se você só quiser que o agente recupere e gere recordações, aiplatform.memories.generate e aiplatform.memories.retrieve serão suficientes.

Usar em todos os outros ambientes de execução

Se você quiser usar o Memory Bank em um ambiente diferente, como Cloud Run ou Colab, crie um ambiente de execução do agente sem fornecer um agente. Se você não fornecer uma configuração, o Memory Bank será criado com as configurações padrão para gerenciar a geração de dados de memória e a recuperação.

agent_engine = client.agent_engines.create()

Se você já usou o Agent Platform antes, criar uma nova instância do Agent Platform sem um ambiente de execução leva apenas alguns segundos. Se esta for a primeira vez que você usa a Agent Platform, o processo pode levar mais tempo (1 a 2 minutos).

Se você quiser configurar o comportamento, forneça uma configuração do Memory Bank:

Criar

agent_engine = client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Atualizar

Se quiser mudar a configuração do Memory Bank, atualize a instância da Agent Platform.

agent_engine = client.agent_engines.update(
  # You can access the name using `agent_engine.api_resource.name` for an AgentEngine object.
  name="AGENT_ENGINE_NAME",
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Substitua:

  • RUNTIME_NAME: o nome do ambiente de execução do agente. Ele precisa estar no formato projects/.../locations/.../reasoningEngines/.... Consulte as regiões compatíveis para Memory Bank.

É possível usar o Memory Bank em qualquer ambiente com permissão para ler e gravar recordações. Por exemplo, para usar o Memory Bank com o Cloud Run, conceda permissões à identidade do serviço do Cloud Run para ler e gravar memórias. As permissões necessárias dependem das operações que o agente precisa poder realizar. Se você quiser apenas que o agente recupere e gere memórias, aiplatform.memories.generate e aiplatform.memories.retrieve são suficientes.

Configurar sua instância do Agent Platform para o Memory Bank

É possível configurar o Memory Bank para personalizar como as memórias são geradas e gerenciadas. Se você não fornecer a configuração, o Memory Bank vai usar as configurações padrão para cada tipo de configuração.

É possível configurar as seguintes opções do Memory Bank para sua instância:

A amostra a seguir mostra o Memory Bank padrão:

Dicionário

memory_bank_config = {
  "generation_config": {
    # `gemini-2.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
  },
  "similarity_search_config": {
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    "embedding_model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  },
  "ttl_config": {
    # Default TTL for memory revisions is 365 days.
    "memory_revision_default_ttl": f"{365 * 24 * 60 * 60}s"
  },
  "customization_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "memory_topics": [
        {"managed_memory_topic": "USER_PERSONAL_INFO"},
        {"managed_memory_topic": "USER_PREFERENCES"},
        {"managed_memory_topic": "KEY_CONVERSATION_DETAILS"},
        {"managed_memory_topic": "EXPLICIT_INSTRUCTIONS"}
      ],
      "consolidation_config": {
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        "revisions_per_candidate_count": 1
      },
      # Only use the pre-defined set of examples.
      "generate_memories_examples": [],
      # Generate memories in the first person.
      "enable_third_person_memories": False
    }
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  "disable_memory_revisions": False
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    # `gemini-2.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
  ),
  similarity_search_config=SimilaritySearchConfig(
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    embedding_model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  ),
  ttl_config=TtlConfig(
    # Default TTL for memory revisions is 365 days.
    memory_revision_default_ttl=f"{365 * 24 * 60 * 60}s"
  ),
  customization_configs=[
    CustomizationConfig(
      # Extract personal information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      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))
      ],
      # Only use the pre-defined set of examples.
      generate_memories_examples=[],
      consolidation_config=ConsolidationConfig(
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        revisions_per_candidate_count=1
      ),
      # Generate memories in the first person.
      enable_third_person_memories=False,
    )
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  disable_memory_revisions=False
)

É possível ajustar a configuração do Memory Bank ao criar ou atualizar sua instância do Agent Platform. O exemplo a seguir demonstra como criar ou atualizar uma instância com uma configuração específica do Memory Bank.

client.agent_engines.create(
      ...,
      config={
            "context_spec": {
                  "memory_bank_config": memory_bank_config
            }
      }
)

# Alternatively, update an existing Agent Platform instance's Memory Bank config.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      config={
          "context_spec": {
                "memory_bank_config": memory_bank_config
          }
      }
)

Configuração de personalização de memória em linguagem natural

Para personalizar como o Memory Bank extrai memórias de linguagem natural, configure o comportamento de extração ao configurar sua instância. Use as opções a seguir para personalizar o comportamento:

Você pode personalizar o comportamento de extração do seu Banco de Memórias em duas etapas: dizer e mostrar. Os temas da Memória informam ao Memory Bank quais informações devem ser mantidas. Os poucos exemplos mostram ao Memory Bank que tipo de informação deve resultar em uma memória específica, ajudando a aprender os padrões, as nuances e as frases que você espera que ele entenda.

Você também pode configurar comportamentos diferentes para níveis de escopo diferentes. Por exemplo, os tópicos relevantes para recordações no nível da sessão podem não ser relevantes para recordações no nível do usuário (em várias sessões). Para configurar o comportamento de um determinado subconjunto de memórias, defina as chaves de escopo da configuração de personalização. Somente as solicitações GenerateMemories que incluem essas chaves de escopo usam essa configuração. Também é possível configurar o comportamento padrão (aplicado a todos os conjuntos de chaves de escopo) omitindo o campo scope_key. Essa configuração será aplicada a todas as solicitações que não tiverem uma configuração que corresponda exatamente às chaves de escopo de outra configuração de personalização.

Por exemplo, o user_level_config só se aplicaria a solicitações GenerateMemories que usam exatamente a chave de escopo user_id (ou seja, scope={"user_id": "123"} sem chaves adicionais). default_config seria aplicado a outras solicitações:

Dicionário 


user_level_config = {
  "scope_keys": ["user_id"],
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

default_config = {
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

memory_bank_config = {
  "customization_configs": [
    user_level_config,
    default_config
  ]
}

Com base em classes 

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

user_level_config = CustomizationConfig(
  scope_keys=["user_id"],
  memory_topics=[...],
  generate_memories_examples=[...]
)

Como configurar tópicos de memória

Os "Temas de memória" identificam quais informações o Memory Bank considera significativas e, portanto, devem ser mantidas como memórias 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. Você só precisa informar o nome do tópico gerenciado. Por 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
    )
)

    O Memory Bank oferece suporte aos seguintes tópicos gerenciados:

    • Informações do usuário (USER_PERSONAL_INFO): informações 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 preferidos 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 para 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 Memory Bank vai gerar uma memória como "Eu uso principalmente Python".

  • 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 na solicitação para a etapa de extração do Memory Bank. Por 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 few-shot que mostrem como as memórias devem ser extraídas da conversa.

Com a personalização, é possível usar qualquer combinação de temas de memória. Por exemplo, você pode usar um subconjunto dos temas de memória gerenciada disponíveis:

Dicionário

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    { "managed_memory_topic": { "managed_topic_enum": "USER_PREFERENCES" } }
  ]
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  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)
      ),
  ]
)

Você também pode usar uma combinação de temas gerenciados e personalizados (ou apenas temas personalizados):

Dicionário

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    {
      "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 MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      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."""
          )
    )
  ]
)

Exemplos few-shot

Com os exemplos de poucos disparos, você demonstra o comportamento esperado de extração de memória para o Memory Bank. Por exemplo, é possível fornecer uma conversa de entrada de amostra e as memórias que devem ser extraídas dessa conversa.

Recomendamos sempre usar poucos exemplos com tópicos personalizados para que o Memory Bank possa aprender o comportamento pretendido. Os poucos exemplos são opcionais ao usar tópicos gerenciados, já que o Memory Bank define exemplos para cada tópico. Demonstre conversas que não devem resultar em memórias fornecendo uma lista generated_memories vazia.

Por exemplo, você pode fornecer exemplos few-shot que demonstram como extrair feedback sobre sua empresa das mensagens dos clientes:

Dicionário

example = {
    "conversationSource": {
      "events": [
        {
          "content": {
            "role": "model",
            "parts": [{ "text": "Welcome back to The Daily Grind! We'd love to hear your feedback on your visit." }] }
        },
        {
          "content": {
            "role": "user",
            "parts": [{ "text": "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend." }] }
        }
      ]
    },
    "generatedMemories": [
      {
        "fact": "The user reported that the drip coffee was lukewarm."
      },
      {
        "fact": "The user felt the music in the shop was too loud."
      }
    ]
}

Com base em classes

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory as ExampleGeneratedMemory

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend.")]
                )
            )
        ]
    ),
    generated_memories=[
        ExampleGeneratedMemory(
            fact="The user reported that the drip coffee was lukewarm."
        ),
        ExampleGeneratedMemory(
            fact="The user felt the music in the shop was too loud."
        )
    ]
)

Você também pode fornecer exemplos de conversas que não devem resultar em memórias geradas, fornecendo uma lista vazia para a saída esperada (generated_memories):

Dicionário

example = {
    "conversationSource": {
        "events": [
          {
              "content": {
                  "role": "model",
                  "parts": [{ "text": "Good morning! What can I get for you at The Daily Grind?" }] }
          },
          {
              "content": {
                  "role": "user",
                  "parts": [{ "text": "Thanks for the coffee." }] }
          }
        ]
    },
    "generatedMemories": []
}

Com base em classes

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Thanks for the coffee!")]
                )
            )
        ]
    ),
    generated_memories=[]
)

Perspectiva de memória

Por padrão, as recordações são geradas na primeira pessoa (por exemplo, "Eu uso o Memory Bank para gerenciamento de memória"). É possível configurar o Memory Bank para gerar na terceira pessoa (por exemplo, "O usuário usa o Memory Bank para gerenciamento de memória") usando o parâmetro enable_third_person_memories.

Dicionário

customization_config = {
  "enable_third_person_memories": True
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Personalização da consolidação

Durante a consolidação, o Memory Bank determina como integrar as informações recém-adquiridas ao seu conjunto de memórias atual. O Memory Bank avalia se é necessário ADICIONAR novas recordações, ATUALIZAR as recordações atuais com mais contexto ou EXCLUIR as recordações obsoletas.

Para garantir recordações corroboradas e de alta qualidade, o Memory Bank pode analisar o histórico de uma recordação para distinguir tendências de longo prazo de outliers únicos.

Por padrão, o Memory Bank só compara novas informações com o snapshot mais recente de uma memória candidata (uma revisão de memória). Para aumentar a profundidade dessa análise, configure o parâmetro revisions_per_candidate_count. Ele define quantas revisões anteriores de cada "memória candidata" (o registro específico que está sendo avaliado para uma atualização) o Memory Bank considera durante a consolidação.

Dicionário

customization_config = {
  "consolidation_customization": {
    "revisions_per_candidate_count": 10
  }
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig

customization_config = CustomizationConfig(
    consolidation_customization=ConsolidationConfig(
      revisions_per_candidate_count=10
    )
)

Aumentar revisions_per_candidate_count resulta em memórias mais consistentes e corroboradas, considerando a repetição das informações ingeridas. No entanto, uma contagem maior aumenta o consumo de tokens durante o processo de consolidação.

Configuração da pesquisa por similaridade

A configuração de pesquisa por similaridade controla qual modelo de embedding é usado pela sua instância para essa pesquisa, que é usada para identificar quais memórias devem ser candidatas à consolidação e à recuperação de memória baseada em pesquisa por similaridade. Se essa configuração não for fornecida, o Memory Bank usará text-embedding-005 como modelo padrão.

Se você espera que as conversas dos usuários sejam em idiomas diferentes do inglês, use um modelo que ofereça suporte a vários idiomas, como gemini-embedding-001 ou text-multilingual-embedding-002, para melhorar a qualidade da recuperação.

Dicionário

memory_bank_config = {
    "similarity_search_config": {
        "embedding_model": "EMBEDDING_MODEL",
    }
}

Com base em classes 

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig

memory_bank_config = MemoryBankConfig(
    similarity_search_config=SimilaritySearchConfig(
        embedding_model="EMBEDDING_MODEL"
    )
)

Substitua:

  • EMBEDDING_MODEL: o modelo de embedding de texto do Google a ser usado para pesquisa de similaridade, no formato projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuração de geração

A configuração de geração controla qual LLM é usado para gerar memórias, incluindo extrair e consolidar memórias novas com as atuais.

O Memory Bank usa o gemini-2.5-flash como modelo padrão. Para regiões que não têm disponibilidade regional do Gemini, o endpoint global é usado.

Dicionário

memory_bank_config = {
  "generation_config": {
    "model": "LLM_MODEL",
  }
}

Com base em classes 

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    model="LLM_MODEL"
  )
)

Substitua:

  • LLM_MODEL: o modelo de LLM do Google a ser usado para extrair e consolidar memórias, no formato projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuração de time to live (TTL)

A configuração de TTL controla como o Memory Bank define dinamicamente o tempo de expiração das memórias. Depois que o tempo de expiração expirar, as recordações não estarão mais disponíveis para recuperação e serão excluídas.

Se a configuração não for fornecida, o prazo de validade não será definido dinamicamente para as recordações criadas ou atualizadas. Portanto, elas não vão expirar, a menos que o prazo de validade seja definido manualmente.

Há duas opções para a configuração de TTL:

  • TTL padrão: o TTL será aplicado a todas as operações que criam ou atualizam uma memória, incluindo UpdateMemory, CreateMemory e GenerateMemories.

    Dicionário

    memory_bank_config = {
  "ttl_config": {
      "default_ttl": f"TTLs"
  }
}

    Com base em classes 

    from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      default_ttl=f"TTLs"
  )
)

    Substitua:

    • TTL: a duração em segundos do TTL. Para memórias atualizadas, o prazo de validade recém-calculado (agora + TTL) vai substituir o prazo anterior.

  • TTL granular (por operação): o TTL é calculado com base na operação que criou ou atualizou a memória. Se não for definido para uma determinada operação, a operação não vai atualizar o prazo de validade da memória.

    Dicionário

    memory_bank_config = {
  "ttl_config": {
      "granular_ttl": {
          "create_ttl": f"CREATE_TTLs",
          "generate_created_ttl": f"GENERATE_CREATED_TTLs",
          "generate_updated_ttl": f"GENERATE_UPDATED_TTLs"
      }
  }
}

    Com base em classes 

    from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfigGranularTtlConfig as GranularTtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      granular_ttl_config=GranularTtlConfig(
          create_ttl=f"CREATE_TTLs",
          generate_created_ttl=f"GENERATE_CREATED_TTLs",
          generate_updated_ttl=f"GENERATE_UPDATED_TTLs",
      )
  )
)

    Substitua:

    • CREATE_TTL: a duração em segundos do TTL para memórias criadas usando CreateMemory.
    • GENERATE_CREATED_TTL: a duração em segundos do TTL para memórias criadas usando GenerateMemories.
    • GENERATE_UPDATED_TTL: a duração em segundos do TTL para memórias atualizadas usando GenerateMemories. O prazo de validade recém-calculado (agora + TTL) vai substituir o prazo de validade anterior da memória.

A seguir

Guia de início rápido

Comece a usar a API Memory Bank para gerenciar memórias de longo prazo.

Guia de início rápido

Comece a usar o Kit de Desenvolvimento de Agente (ADK).