Memory Bank da Agent Platform

O Memory Bank da Agent Platform permite gerar dinamicamente memórias de longo prazo com base em conversas entre o usuário e o agente. Essas memórias são informações personalizadas que persistem em várias sessões, permitindo que o agente adapte e personalize as respostas para contexto e continuidade.

Recursos

O Memory Bank ajuda a gerenciar memórias para que você possa personalizar a forma como o agente interage com os usuários e gerenciar a janela de contexto. Para cada escopo, o Memory Bank mantém uma coleção isolada de memórias. Cada memória é uma informação independente e independente que pode ser usada para expandir o contexto disponível para o agente. Exemplo:

{
  "name": "projects/.../locations/.../reasoningEngines/.../memories/...",
  "scope": {
    "agent_name": "My agent",
    "user": "my user ID"
  },
  "fact": "I use Memory Bank to manage my memories."
}

O Memory Bank inclui os seguintes recursos:

  • Geração de dados de memória: Crie, refine e gerencie dados de memória usando um modelo de linguagem grande (LLM).

    • Extração de memória: extraia apenas as informações mais significativas dos dados de origem para persistir como memórias.

    • Consolidação de memória: consolide as informações recém-extraídas com as memórias atuais, permitindo que as memórias evoluam à medida que novas informações são ingeridas. Também é possível consolidar memórias pré-extraídas (como informações que o agente ou um humano no loop considera significativas) com as memórias atuais.

    • Geração assíncrona: gere dados de memória em segundo plano para que o agente não precise esperar a conclusão da geração de dados de memória.

    • Ingestão contínua de eventos: transmita e gerencie eventos de conversa com a ingestão de eventos, que aciona automaticamente a geração de dados de memória com base nas regras de lote que você configura.

    • Extração personalizável: Configure quais informações o Memory Bank considera significativas fornecendo tópicos específicos e exemplos com poucos exemplos (few-shot).

    • Compreensão multimodal: processe informações multimodais para gerar e persistir insights textuais.

  • Armazenamento e recuperação gerenciados: aproveite um armazenamento de memória totalmente gerenciado, persistente, e acessível.

    • Isolamento de dados em identidades: a consolidação e a recuperação de memória são isoladas para uma identidade específica.

    • Armazenamento persistente e acessível: armazene memórias que podem ser acessadas em vários ambientes, incluindo o ambiente de execução do agente, o ambiente local ou outras opções de implantação.

    • Pesquisa de similaridade: recupere memórias usando a pesquisa de similaridade com escopo para uma identidade específica.

    • Expiração automática: defina um time to live (TTL) nas memórias para garantir que as informações desatualizadas sejam excluídas automaticamente. Configure a instância do Memory Bank para que um TTL seja aplicado automaticamente às memórias inseridas ou geradas.

    • Revisões de memória: crie e mantenha automaticamente revisões de memória que permitem inspecionar como as memórias são transformadas à medida que novas informações são ingeridas.

    • Permissões restritivas: use as condições do IAM para restringir quais principais podem ler ou gravar memórias de escopos específicos.

  • Integração do agente: conecte o Memory Bank ao agente para que ele possa orquestrar chamadas para gerar e recuperar memórias.

    • Integração do Kit de Desenvolvimento de Agente (ADK): orquestre chamadas do agente baseado no ADK usando ferramentas integradas do ADK e o VertexAiMemoryBankService para ler e gravar no Memory Bank.

    • Outros frameworks: encapsule o código do Memory Bank em ferramentas e callbacks para orquestrar a geração e a recuperação de memória.

Casos de uso

É possível usar o Memory Bank para transformar interações de agentes sem estado em experiências contextuais com estado em que o agente se lembra, aprende e se adapta ao longo do tempo. O Memory Bank é ideal para aplicativos que exigem:

  • Personalização de longo prazo: crie experiências personalizadas para usuários individuais. O Memory Bank escopa memórias para uma identidade específica, permitindo que um agente se lembre das preferências, do histórico e dos detalhes principais de um usuário em várias sessões.

    • Exemplo: um agente de serviço ao cliente que se lembra das principais informações dos tíquetes de suporte e das preferências de produtos anteriores de um usuário sem precisar perguntar novamente.

  • Extração de conhecimento orientada por LLM: use quando precisar identificar e persistir automaticamente as informações mais importantes de conversas ou conteúdo multimodal sem intervenção manual.

    • Exemplo: um agente de pesquisa que lê uma série de artigos técnicos e cria uma memória consolidada de principais descobertas, metodologias e conclusões.

  • Contexto dinâmico e em evolução: use o Memory Bank quando precisar de uma fonte de conhecimento que não seja estática. O Memory Bank foi projetado para integrar continuamente novas informações do agente, refinando e atualizando as memórias armazenadas à medida que novos dados ficam disponíveis. Isso garante que o contexto em que o agente confia esteja sempre atualizado e preciso. Enquanto a RAG tem uma base de conhecimento estática e externa, o Memory Bank pode evoluir com base no contexto fornecido pelo agente.

Exemplo de uso

Visão geral conceitual do Memory Bank da Agent Platform

É possível usar o Memory Bank com as sessões da Agent Platform para gerar memórias de sessões armazenadas usando o processo a seguir:

  1. (Sessões) CreateSession: no início de cada conversa, crie uma nova sessão. O histórico de conversas usado pelo agente tem escopo para essa sessão. Uma sessão contém a sequência cronológica de mensagens e ações (SessionEvents) para uma interação entre um usuário e o agente. Todas as sessões precisam ter um ID de usuário. As memórias extraídas (consulte GenerateMemories) para essa sessão são mapeadas para esse usuário.

  2. (Sessões) AppendEvent: à medida que o usuário interage com o agente, os eventos (como mensagens do usuário, respostas do agente, ações de ferramentas) são enviados para as sessões. Os eventos persistem no histórico de conversas e criam um registro da conversa que pode ser usado para gerar memórias.

  3. (Sessões) ListEvents: à medida que o usuário interage com o agente, o agente recupera o histórico de conversas.

  4. (Memory Bank) Gere ou crie memórias:

    • GenerateMemories: em um intervalo especificado (como o final de cada sessão ou o final de cada turno), o agente pode acionar a geração de memórias usando o histórico de conversas. Os fatos sobre o usuário são extraídos automaticamente do histórico de conversas para que fiquem disponíveis para sessões atuais ou futuras.

    • CreateMemory: o agente pode gravar memórias diretamente no Memory Bank. Por exemplo, o agente pode decidir quando uma memória deve ser gravada e quais informações precisam ser salvas (memória como ferramenta). Use CreateMemory quando quiser que o agente tenha mais controle sobre quais fatos são extraídos.

  5. (Memory Bank) RetrieveMemories: à medida que o usuário interage com o agente, o agente pode recuperar as memórias salvas sobre esse usuário. É possível recuperar todas as memórias (recuperação simples) ou apenas as mais relevantes para a conversa atual (recuperação de pesquisa de similaridade). Em seguida, insira as memórias recuperadas no comando.

Guias de início rápido

Comece a usar o Memory Bank com os seguintes guias de início rápido:

Governança do Memory Bank

Esta seção descreve as considerações sobre governança de dados ao usar o Memory Bank, como responsabilidades de segurança e residência de dados.

Riscos de segurança da injeção de comando

Além das responsabilidades de segurança descritas na Agent Platform responsabilidade compartilhada, considere o risco de injeção de comando e envenenamento de memória que podem afetar o agente ao usar memórias de longo prazo. O envenenamento de memória ocorre quando informações falsas são armazenadas no Memory Bank. O agente pode operar com essas informações falsas ou maliciosas em sessões futuras.

Para reduzir o risco de envenenamento de memória, faça o seguinte:

  • Model Armor: use o Model Armor para inspecionar os comandos enviados ao Memory Bank ou do agente.

  • Testes adversários: teste proativamente o aplicativo LLM para vulnerabilidades de injeção de comando simulando ataques. Isso é conhecido como "red teaming".

  • Execução em sandbox: se o agente tiver a capacidade de executar ou interagir com sistemas externos ou críticos, essas ações precisam ser realizadas em um ambiente de sandbox com controle de acesso rigoroso e revisão humana.

Para mais informações, consulte a abordagem do Google para agentes de IA seguros.

Residência de dados

Para obedecer a frameworks regulatórios, como o Regulamento Geral de Proteção de Dados (GDPR) e os requisitos regionais de soberania de dados, é necessário garantir que as memórias geradas e armazenadas no Memory Bank sigam limites rigorosos de residência de dados e segregação.

Embora o Memory Bank forneça isolamento de dados baseado em escopo em identidades em uma instância, é necessário aplicar o controle de acesso baseado em papéis (RBAC) e as políticas do Identity and Access Management para aplicar limites regionais e evitar a contaminação de memória transfronteiriça entre instâncias regionais distintas.

Implantação de instâncias regionais e residência de dados

Ao criar uma instância do Memory Bank, escolha um local regional ou multirregional (como eu para a União Europeia ou us para os Estados Unidos) para garantir que os dados em repouso permaneçam dentro desse limite geográfico específico.

O local de processamento de machine learning (ML) depende da disponibilidade regional do modelo subjacente. Se um endpoint regional não estiver disponível para o modelo ou local selecionado (por exemplo, modelos do Gemini 3 ou regiões únicas da Ásia), os endpoints globais do Gemini serão usados para o processamento de ML. Para mais informações, consulte Residência de dados e endpoints multirregionais e globais.

Como evitar a contaminação de memória transfronteiriça

A contaminação transfronteiriça ocorre quando um ambiente de execução do agente, uma identidade do agente, uma conta de serviço ou um aplicativo que opera em uma jurisdição (por exemplo, os EUA) grava ou recupera memórias de uma instância do Memory Bank localizada em outra jurisdição (por exemplo, a UE).

Para evitar a contaminação transfronteiriça e manter a conformidade regulatória, é possível configurar os seguintes controles do IAM:

  • Identidades de agentes regionais dedicadas ou contas de serviço: crie identidades de agentes ou contas de serviço separadas e específicas da região para cada jurisdição (como agent-us@PROJECT_ID.iam.gserviceaccount.com para cargas de trabalho dos EUA e agent-eu@PROJECT_ID.iam.gserviceaccount.com para cargas de trabalho da UE). Garanta que as identidades de agentes regionais e as contas de serviço só recebam papéis do IAM nas instâncias do Memory Bank que residem na mesma jurisdição geográfica, impedindo que os ambientes de execução regionais acessem instâncias transfronteiriças.

    • Papéis especializados de menor privilégio: conceda aos principais apenas os papéis específicos do Memory Bank necessários para a carga de trabalho (como roles/aiplatform.memoryViewer para recuperação somente leitura ou roles/aiplatform.memoryEditor para acesso de gravação e geração) vinculados ao recurso regional apropriado. Para detalhes sobre os papéis disponíveis, consulte Papéis especializados do IAM do Memory Bank.

  • Políticas da organização: aplique restrições de local no nível da organização, pasta ou projeto usando a gcp.resourceLocations restrição de política da organização. Isso restringe a criação e o uso de recursos do Memory Bank a regiões compatíveis aprovadas e impede o uso não autorizado de endpoints globais.

Para mais informações sobre como implementar políticas de acesso condicional, consulte Controlar o acesso ao Memory Bank da Agent Platform com as condições do IAM.

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).

Guia

Saiba como configurar o Memory Bank.