Configurar o Memory Bank

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

Neste documento, explicamos como configurar o 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 Banco de Memórias, 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 é gerado automaticamente ao criar o projeto, enquanto o PROJECT_ID é gerado 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 Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

  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, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

Receber as permissões necessárias

Para receber as permissões necessárias para usar o Memory Bank, peça ao administrador para conceder 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 (GKE) ou no Cloud Run, verifique se a conta de serviço tem as permissões necessárias para ler, gravar ou gerar memórias. O agente de serviço do Reasoning Engine já tem as permissões necessárias para ler, gravar e gerar 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, pressupomos que você tenha configurado um ambiente de desenvolvimento em Python ou esteja usando um ambiente de execução com um ambiente de desenvolvimento em Python (como o Colaboratory).

Instale o SDK da Agent Platform:

pip install google-cloud-agentplatform>=2.0.1

Autenticação

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

Configurar um cliente do SDK da Agent Platform

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

SDK da plataforma de agentes 

import agentplatform

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

em que

Endpoints multirregionais e globais

O Memory Bank é compatível com endpoints multirregionais e globais:

  • Para instâncias globais, defina o local como global.
  • Para instâncias multirregionais, defina o local como us ou eu.

Criar ou atualizar uma instância do Memory Bank

Para começar a usar o banco de memória, primeiro você precisa de uma instância dele. Se você ainda não tiver uma instância, crie uma usando a configuração padrão e um nome de exibição de sua escolha.

# create the resource
memory_bank = client.memory_banks.create(
    config={
        "display_name": "My Memory Bank",
    }
)

# Optionally, print out the Memory Bank resource name. You will need the
# resource name to interact with your Memory Bank instance later on.
print(memory_bank.name)

Se quiser personalizar a configuração do comportamento da sua instância nova ou atual do Memory Bank, consulte Configurar sua instância do Memory Bank. Por exemplo, é possível especificar quais informações o Banco de Memória considera significativas para persistir.

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

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

Usar com o Agent Runtime

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

Para implantar um agente no Agent Runtime com o banco de memória integrado, primeiro configure seu ambiente para o Agent Runtime. Em seguida, prepare o 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 (ADK) da Agent Platform, o agente usará o VertexAiMemoryBankService por padrão quando implantado no Agent Runtime. Isso significa que as ferramentas de memória do ADK leem memórias do Memory Bank.

from google.adk.agents import Agent
from agentplatform.frameworks import AdkApp

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

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

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

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

Substitua:

  • STAGING_BUCKET: o bucket do Cloud Storage a ser usado para preparar o Agent Runtime.

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

Agente personalizado

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

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 Agent Runtime, ele já terá permissão para ler e gravar memórias. Se você estiver usando uma conta de atendimento ao cliente, conceda 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ê quiser que o agente apenas recupere e gere memórias, aiplatform.memories.generate e aiplatform.memories.retrieve são suficientes.

Uso em todos os outros ambientes de execução

Se você quiser usar o Memory Bank em um ambiente diferente, como o Cloud Run ou o Colab, crie um Memory Bank. 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.

memory_bank = client.memory_banks.create()

Se você já usou o Memory Bank, criar uma nova instância leva apenas alguns segundos. Se esta for sua primeira vez usando o Memory Bank, 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

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "generation_config": ...,
    "unstructured_memory_configs": [...],
    "structured_memory_configs": [...],
    "similarity_search_config": ...,
    "ttl_config": ...,
    "disable_memory_revisions": False,
  }
)

Atualizar

Se você quiser mudar a configuração do Memory Bank, atualize a instância dele.

memory_bank = client.runtimes.update(
  # You can access the name using `memory_bank.name` for a MemoryBank object.
  name="MEMORY_BANK_NAME",
  config={
    "context_spec": {
      "memory_bank_config": {
        "generation_config": ...,
        "customization_configs": [...],
        "structured_memory_configs": [...],
        "similarity_search_config": ...,
        "ttl_config": ...,
        "disable_memory_revisions": False,
      }
    }
  }
)

Substitua:

  • MEMORY_BANK_NAME: o nome do banco de memória. Ele precisa estar no formato projects/.../locations/.../reasoningEngines/.... Consulte as regiões compatíveis com o Memory Bank.

Você pode usar o Banco de Memória em qualquer ambiente que tenha permissão para ler e gravar memórias. 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 a instância do 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 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:

O exemplo a seguir mostra o banco de memória padrão:

Dicionário

managed_semantic_memory_config = {
  "generation_config": {
    # `gemini-3.5-flash` will be used to extract and consolidate memories.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-3.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"
  },
  "unstructured_memory_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "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"}}
      ],
      "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 agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig
from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  generation_config=GenerationConfig(
    # `gemini-3.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-3.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"
  ),
  unstructured_memory_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. O exemplo a seguir demonstra como criar uma instância com uma configuração específica de banco de memória.

memory_bank = client.memory_banks.create(
    managed_semantic_memory_config=managed_semantic_memory_config
)

Configuração de personalização da memória de 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 seguintes opções para personalizar o comportamento:

Você pode personalizar o comportamento de extração do Banco de Memórias em duas etapas: informar e mostrar. Os tópicos de 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.

Se quiser, você pode configurar comportamentos diferentes para cada nível de escopo. Por exemplo, os temas 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 vão usar 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 outras chaves). 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": [...]
}

managed_semantic_memory_config = {
  "unstructured_memory_configs": [
    user_level_config,
    default_config
  ]
}

Com base em classes 

from agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig

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

default_config = CustomizationConfig(
  memory_topics=[...],
  generate_memories_examples=[...]
)

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  unstructured_memory_configs=[
    user_level_config,
    default_config,
  ]
)

Configurar temas das memórias

Os "tópicos 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 tópicos 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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topic = MemoryTopic(
    managed_memory_topic=ManagedMemoryTopic(
        managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
    )
)

    O Memory Bank é compatível com os seguintes tópicos gerenciados:

    • Informações do usuário (USER_PERSONAL_INFO): informações importantes 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): preferências, 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 para lembrar / esquecer (EXPLICIT_INSTRUCTIONS): informações que o usuário pede explicitamente para o agente 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".

  • 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 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 agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.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 que demonstrem como as memórias 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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

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 poucos disparos (few-shot), 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 few-shots com tópicos personalizados para que o banco de memória possa aprender o comportamento pretendido. Os few-shots são opcionais ao usar tópicos gerenciados, já que o banco de memória 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 demonstrem 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 agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from agentplatform.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."
        )
    ]
)

Também é possível 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 agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.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 memórias são geradas na primeira pessoa (por exemplo, "Eu uso o Memory Bank para gerenciamento de memória"). É possível configurar o Banco de Memória para gerar na terceira pessoa (por exemplo, "O usuário usa o Banco de Memória 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 agentplatform.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 banco de memória 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 de alta qualidade e corroboradas, o Memory Bank pode analisar o histórico de uma recordação para distinguir tendências de longo prazo de outliers pontuais.

Por padrão, o Banco de Memória só compara as 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 banco de memória considera durante a consolidação.

Dicionário

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

Com base em classes

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

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

Aumentar o 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.

Como aplicar configurações de personalização

Para aplicar configurações de personalização à sua instância do Memory Bank, forneça-as na lista unstructured_memory_configs do seu managed_semantic_memory_config:

Dicionário

managed_semantic_memory_config = {
  "unstructured_memory_configs": [customization_config],
  # Include other configurations (similarity search, generation, TTL)...
}

Com base em classes

from agentplatform.types import ManagedSemanticMemoryConfig

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  unstructured_memory_configs=[customization_config],
  # Include other configurations (similarity search, generation, TTL)...
)

Configuração da pesquisa por similaridade

A configuração de pesquisa de similaridade controla qual modelo de embedding é usado pela instância para pesquisa de similaridade. 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 Banco de Memória vai 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-2, gemini-embedding-001 ou text-multilingual-embedding-002, para melhorar a qualidade da recuperação.

Dicionário

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

Com base em classes 

from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig

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 a extração de memórias e a consolidação de novas memórias com as atuais.

A partir de 29 de junho de 2026, o Banco de Memória vai usar gemini-3.5-flash como modelo padrão. As instâncias criadas antes dessa data usam gemini-2.5-flash.

Para novas instâncias do Memory Bank que usam o modelo padrão:

  • As instâncias do Memory Bank em multirregiões us ou em regiões únicas us-* (por exemplo, us-central1) usam o endpoint multirregional us do Gemini 3.5.
  • As instâncias do Memory Bank em multirregiões eu ou em regiões únicas eu-* (por exemplo, europe-west2) usam o endpoint multirregional eu do Gemini 3.5.
  • Todas as outras regiões do Memory Bank usam o endpoint global do Gemini 3.5.

Para instâncias do Memory Bank criadas antes de 29 de junho de 2026 usando o modelo padrão, o Memory Bank usa o endpoint global do Gemini em regiões que não têm um endpoint regional do Gemini 2.5 disponível.

Dicionário

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

Com base em classes 

from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig

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 deve definir dinamicamente o tempo de expiração das memórias. Depois que o prazo de validade 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 memórias 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

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

    Com base em classes 

    from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig

ttl_config = TtlConfig(
    default_ttl=f"TTLs"
)

    Substitua:

    • TTL: a duração em segundos do TTL. Para memórias atualizadas, o novo prazo de validade calculado (agora + TTL) vai substituir o 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

    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 agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfigGranularTtlConfig as GranularTtlConfig

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

Introdução ao Kit de Desenvolvimento de Agente (ADK).