Configurar o Memory Bank da plataforma de agentes

Para usar o Memory Bank da plataforma de agentes, primeiro crie e configure uma instância da plataforma de agentes do Gemini Enterprise. 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:

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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Observação: para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você não tiver essa permissão, peça ao administrador para conceder a função de administrador do uso de serviços (roles/serviceusage.serviceUsageAdmin).

Ter os papéis necessários

Para receber as permissões necessárias a fim de usar o Memory Bank, peça que o administrador conceda a você os seguintes papéis do IAM no projeto:

• Todos: Usuário da plataforma de agentes (roles/aiplatform.user)

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 Plataforma de Agentes:

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 Plataforma de Agentes

Execute o código a seguir para configurar um cliente do SDK da plataforma de agente:

SDK da plataforma de agentes

import vertexai

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

em que

• PROJECT_ID é o ID do projeto do Google Cloud em que você desenvolve e implanta agentes.
• LOCATION é uma das regiões com suporte para o Memory Bank.

Criar ou atualizar uma instância da plataforma de agentes

Para começar a usar o Memory Bank, primeiro você precisa de uma instância da plataforma de agentes. 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 quiser personalizar a configuração do comportamento da sua instância do Memory Bank nova ou atual, consulte Configurar sua instância da plataforma de agente para o Memory Bank. Por exemplo, você pode 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 de imediato. 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 sua instância da plataforma de agente.

Depois de ter uma instância da plataforma de agente, 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 tempo de execução do agente 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 plataforma de agentes. 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 Agent Development Kit.

Agente personalizado

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

O aplicativo implantado no ambiente de execução do agente pode ler as variáveis de ambiente GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_AGENT_ENGINE_ID para inferir o nome do ambiente de execução do agente no 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 são suficientes.

Uso em todos os outros ambientes de execução

Para conferir um exemplo de como usar o Memory Bank com o Cloud Run, execute o bloco de notas "Começar a usar as sessões e o Memory Bank para agentes do ADK no Cloud Run" em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Agent Platform Workbench | Ver no GitHub

Para conferir um exemplo de uso do Memory Bank com o Google Kubernetes Engine, execute o notebook "Começar a usar sessões e o Memory Bank para agentes do ADK no Google Kubernetes Engine" em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Agent Platform Workbench | Ver no GitHub

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 a plataforma de agentes, criar uma nova instância sem um ambiente de execução leva apenas alguns segundos. Se esta for a primeira vez que você usa a plataforma de agentes, o processo pode levar mais tempo (1 a 2 minutos).

Se você quiser configurar o comportamento, forneça uma configuração de 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 Agent Runtime. Ele precisa estar no formato projects/.../locations/.../reasoningEngines/.... Consulte as regiões com suporte do 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 realizar. Se você quiser que o agente apenas recupere e gere memórias, aiplatform.memories.generate e aiplatform.memories.retrieve são suficientes.

Configurar sua instância da plataforma do agente para o Memory Bank

Você pode configurar o Memory Bank para personalizar como as recordações são geradas e gerenciadas. Se você não fornecer a configuração, o Memory Bank 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:

• Configuração de personalização: configura como as recordações são extraídas dos dados de origem e consolidadas com as recordações atuais.
• Configuração da pesquisa de similaridade: especifica qual modelo de embedding o Memory Bank usa para a pesquisa de similaridade. O padrão é text-embedding-005.
• Configuração de geração: configura qual Memory Bank de LLM usa para geração de dados de memória. O padrão é gemini-2.5-flash.
• Configuração de TTL: configura como o TTL é definido automaticamente para memórias criadas ou atualizadas. O padrão é nenhum TTL.

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 da plataforma do agente. 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 da 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:

• Configurar tópicos de memória: defina o tipo de informação que o Memory Bank deve considerar significativa para persistir. Somente as informações que se encaixam em um desses tópicos de memória serão mantidas pelo Memory Bank.
• Fornecer exemplos de poucos disparos: demonstre o comportamento esperado para a extração de memória do Memory Bank.
• Configurar a perspectiva de memória: configure se as memórias devem ser geradas em primeira pessoa (padrão) ou terceira pessoa.
• Configurar a consolidação: defina quantas revisões de memória o Memory Bank considera ao consolidar cada candidato a memória.

Você pode personalizar o comportamento de extração do seu Banco de Memórias em duas etapas: dizer e mostrar. Os tópicos da Memória informam ao Memory Bank quais informações precisam ser mantidas. Os 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 se aplicaria 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 recordação" identificam quais informações o Memory Bank 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. 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 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 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 recordações devem ser extraídas da conversa.

Com a personalização, você pode usar qualquer combinação de temas de memória. Por exemplo, é possível usar um subconjunto dos tópicos 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 exemplos de poucas imagens, você demonstra o comportamento esperado de extração de memória para o Memory Bank. Por exemplo, você pode fornecer uma conversa de entrada de amostra e as memórias que devem ser extraídas dela.

Recomendamos sempre usar poucos exemplos com temas 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 recordações 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
)

Observação: se você estiver fornecendo exemplos de poucos disparos, verifique se a perspectiva deles é consistente com a perspectiva configurada da sua instância.

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 Banco de memória 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. Esse parâmetro 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 de similaridade controla qual modelo de embedding é usado pela sua instância para essa pesquisa. A pesquisa de similaridade é usada para identificar quais memórias devem ser candidatas à consolidação e à recuperação de memória baseada em pesquisa de similaridade. Se essa configuração não for fornecida, o Memory Bank usará text-embedding-005 como o 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 memórias e consolidar novas memórias com as atuais.

O Memory Bank usa o gemini-2.5-flash como modelo padrão. Para regiões sem 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 memórias 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, ela 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

Início rápido da API Memory Bank

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

Guia de início rápido

Guia de início rápido do Kit de Desenvolvimento de Agente

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