Configura Memory Bank de Agent Platform

Para usar Agent Platform Memory Bank, primero debes crear y configurar una instancia de Gemini Enterprise Agent Platform. Esta instancia administra tus recuerdos y se puede integrar con tus agentes en varios tiempos de ejecución.

En este documento, se explica cómo configurar tu proyecto de Google Cloud , instalar las bibliotecas requeridas y crear o actualizar una instancia con configuraciones personalizadas, como temas y TTL.

Comenzar

Antes de trabajar con Memory Bank, debes configurar tu entorno.

Configura tu proyecto de Google Cloud

Cada proyecto se puede identificar de dos maneras: con el número o con el ID del proyecto. El PROJECT_NUMBER se crea automáticamente cuando creas el proyecto, mientras que el PROJECT_ID lo creas tú o la persona que haya creado el proyecto. Sigue estos pasos para configurar un proyecto:

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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

Nota: Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si no tienes este permiso, pídele a tu administrador que te otorgue el rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin).

Obtén los roles necesarios

Para obtener los permisos que necesitas para usar Memory Bank, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

• Todos: Usuario de Agent Platform (roles/aiplatform.user)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Si realizas solicitudes a Memory Bank desde un agente implementado en Google Kubernetes Engine o Cloud Run, asegúrate de que tu cuenta de servicio tenga los permisos necesarios. El agente de servicio de Reasoning Engine ya tiene los permisos necesarios para leer y escribir recuerdos, por lo que las solicitudes salientes de Agent Runtime ya deberían tener permiso para acceder a Memory Bank.

Instala bibliotecas

En esta sección, se supone que configuraste un entorno de desarrollo de Python o que usas un tiempo de ejecución con un entorno de desarrollo de Python (como Colab).

Instala el SDK de Agent Platform:

pip install google-cloud-aiplatform>=1.111.0

Autenticación

Sigue las instrucciones que se indican en Autentica en Vertex AI.

Configura un cliente del SDK de Agent Platform

Ejecuta el siguiente código para configurar un cliente del SDK de Agent Platform:

SDK de Agent Platform

import vertexai

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

donde

• PROJECT_ID es el Google Cloud ID del proyecto en el que desarrollas y despliegas agentes.
• LOCATION es una de las regiones admitidas para Memory Bank.

Crea o actualiza una instancia de Agent Platform

Para comenzar a usar Memory Bank, primero necesitas una instancia de Agent Platform. Si aún no tienes una instancia, puedes crearla con la configuración predeterminada:

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)

Si deseas personalizar la configuración del comportamiento de tu instancia de Memory Bank nueva o existente, consulta Configura tu instancia de Agent Platform para Memory Bank. Por ejemplo, puedes especificar qué información considera significativa la función Memory Bank para conservarla.

Tu instancia de Agent Platform admite Sessions y Memory Bank de forma predeterminada. No se implementa ningún agente cuando creas la instancia. Para usar Agent Runtime, debes proporcionar el agente que se debe implementar cuando crees o actualices tu instancia de Agent Platform.

Una vez que tengas una instancia de Agent Platform, puedes usar su nombre para leer o escribir recuerdos. Por ejemplo:

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

Uso con Agent Runtime

Si bien Memory Bank se puede usar en cualquier entorno de ejecución, también puedes usarlo con Agent Runtime para leer y escribir memorias desde tu agente implementado.

Para implementar un agente con Memory Bank en Agent Platform, primero configura tu entorno para Agent Runtime. Luego, prepara tu agente para implementarlo en Agent Runtime con integración de memoria. Tu agente implementado debe realizar llamadas para leer y escribir recuerdos según sea necesario.

AdkApp

Si usas la plantilla del Kit de desarrollo de agentes de Agent Platform, el agente usa VertexAiMemoryBankService de forma predeterminada cuando se implementa en Agent Platform. Esto significa que las herramientas de memoria del ADK leen memorias del 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
      }
)

Reemplaza lo siguiente:

• STAGING_BUCKET: Es tu bucket de Cloud Storage que se usará para la etapa intermedia de tu Agent Runtime.

Para obtener más información sobre el uso de Memory Bank con el ADK, consulta la Guía de inicio rápido del Kit de desarrollo de agentes.

Agente personalizado

Puedes usar Memory Bank con tu agente personalizado implementado en Agent Runtime. En este caso, tu agente debe coordinar las llamadas a Memory Bank para activar las llamadas de generación de memoria y recuperación de memoria.

Tu aplicación implementada en Agent Runtime puede leer las variables de entorno GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION y GOOGLE_CLOUD_AGENT_ENGINE_ID para inferir el nombre de Agent Runtime del entorno:

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}"

Si usas el agente de servicio predeterminado para tu agente en Agent Runtime, este ya tiene permiso para leer y escribir recuerdos. Si usas una cuenta de atención al cliente, debes otorgar permisos a tu cuenta de servicio para leer y escribir recuerdos. Los permisos requeridos dependen de las operaciones que tu agente debería poder realizar. Si solo quieres que tu agente recupere y genere recuerdos, aiplatform.memories.generate y aiplatform.memories.retrieve son suficientes.

Uso en todos los demás entornos de ejecución

Para ver un ejemplo del uso de Memory Bank con Cloud Run, ejecuta el notebook "Comienza a usar Sessions y Memory Bank para agentes de ADK en Cloud Run" en uno de los siguientes entornos:

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

Para ver un ejemplo del uso de Memory Bank con Google Kubernetes Engine, ejecuta el notebook "Comienza a usar Sessions y Memory Bank para agentes de ADK en Google Kubernetes Engine" en uno de los siguientes entornos:

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

Si deseas usar Memory Bank en un entorno diferente, como Cloud Run o Colab, crea un Agent Runtime sin proporcionar un agente. Si no proporcionas una configuración, Memory Bank se creará con la configuración predeterminada para administrar la generación y recuperación de memoria.

agent_engine = client.agent_engines.create()

Si ya usaste Agent Platform, crear una nueva instancia de Agent Platform sin un tiempo de ejecución debería llevar solo unos segundos. Si es la primera vez que usas Agent Platform, el proceso puede tardar más (entre 1 y 2 minutos).

Si quieres configurar el comportamiento, proporciona una configuración de Memory Bank:

Crear

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

Actualizar

Si deseas cambiar la configuración de Memory Bank, puedes actualizar tu instancia de 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": ...
    }
  }
)

Reemplaza lo siguiente:

• RUNTIME_NAME: Es el nombre del entorno de ejecución del agente. Debe tener el formato projects/.../locations/.../reasoningEngines/.... Consulta las regiones admitidas para Memory Bank.

Puedes usar Memory Bank en cualquier entorno que tenga permiso para leer y escribir recuerdos. Por ejemplo, para usar Memory Bank con Cloud Run, otorga permisos a la identidad del servicio de Cloud Run para leer y escribir recuerdos. Los permisos necesarios dependen de las operaciones que tu agente debería poder realizar. Si solo quieres que tu agente recupere y genere recuerdos, aiplatform.memories.generate y aiplatform.memories.retrieve son suficientes.

Configura tu instancia de Agent Platform para Memory Bank

Puedes configurar tu Memory Bank para personalizar la forma en que se generan y administran los recuerdos. Si no proporcionas la configuración, Memory Bank usará la configuración predeterminada para cada tipo de configuración.

Puedes configurar los siguientes parámetros de configuración de Memory Bank para tu instancia:

• Configuración de personalización: Configura cómo se extraen los recuerdos de los datos fuente y se consolidan con los recuerdos existentes.
• Configuración de la búsqueda por similitud: Especifica qué modelo de embedding usa Memory Bank para la búsqueda por similitud. La configuración predeterminada es text-embedding-005.
• Configuración de generación: Configura qué LLM usa Memory Bank para la generación de memoria. La configuración predeterminada es gemini-2.5-flash.
• Configuración de TTL: Configura cómo se establece automáticamente el TTL para las memorias creadas o actualizadas. El valor predeterminado es sin TTL.

En el siguiente ejemplo, se muestra el Banco de memoria predeterminado:

Diccionario

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
}

Basado en clases

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
)

Puedes ajustar la configuración de Memory Bank cuando crees o actualices tu instancia de Agent Platform. En el siguiente ejemplo, se muestra cómo crear o actualizar una instancia con una configuración específica de 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
          }
      }
)

Configuración de personalización de la memoria en lenguaje natural

Para personalizar la forma en que Memory Bank extrae recuerdos en lenguaje natural, configura el comportamiento de extracción cuando configures tu instancia. Usa las siguientes opciones para personalizar el comportamiento:

• Configura temas de la memoria: Define el tipo de información que Memory Bank debe considerar significativa para conservarla. Memory Bank solo conservará la información que se ajuste a uno de estos temas de memoria.
• Proporcionar ejemplos de pocas tomas: Demuestra el comportamiento esperado para la extracción de memoria en Memory Bank.
• Configura la perspectiva de los recuerdos: Configura si los recuerdos se deben generar en primera persona (opción predeterminada) o en tercera persona.
• Configuración de la consolidación: Configura cuántas revisiones de memoria considera Memory Bank cuando consolida cada candidato de memoria.

Puedes pensar en la personalización del comportamiento de extracción de tu Banco de memoria en dos pasos: Decir y Mostrar. Los temas de la memoria indican al Memory Bank qué información debe persistir. Los ejemplos de aprendizaje con pocos datos muestran a Memory Bank qué tipo de información debe generar una memoria específica, lo que le permite aprender los patrones, los matices y la redacción que esperas que comprenda.

De manera opcional, puedes configurar un comportamiento diferente para los distintos niveles de alcance. Por ejemplo, los temas que son significativos para los recuerdos a nivel de la sesión pueden no serlo para los recuerdos a nivel del usuario (en varias sesiones). Para configurar el comportamiento de un subconjunto determinado de recuerdos, establece las claves de alcance de la configuración de personalización. Solo las solicitudes de GenerateMemories que incluyan esas claves de alcance usarán esa configuración. También puedes configurar el comportamiento predeterminado (que se aplica a todos los conjuntos de claves de alcance) si omites el campo scope_key. Esta configuración se aplicará a todas las solicitudes que no tengan una configuración que coincida exactamente con las claves de alcance de otra configuración de personalización.

Por ejemplo, user_level_config solo se aplicaría a las solicitudes de GenerateMemories que usen exactamente la clave de permiso user_id (es decir, scope={"user_id": "123"} sin claves adicionales). default_config se aplicaría a otras solicitudes:

Diccionario

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
  ]
}

Basado en clases

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

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

Cómo configurar temas de memoria

Los "temas de la memoria" identifican qué información considera Memory Bank significativa y, por lo tanto, debe conservarse como recuerdos generados. Memory Bank admite dos tipos de temas de memoria:

• Temas administrados: La etiqueta y las instrucciones las define Memory Bank. Solo debes proporcionar el nombre del tema administrado. Por ejemplo:

  Diccionario

  memory_topic = {
    "managed_memory_topic": {
      "managed_topic_enum": "USER_PERSONAL_INFO"
    }
  }
  

  Basado en clases

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

  Memory Bank admite los siguientes temas administrados:

  • Información del usuario (USER_PERSONAL_INFO): Información importante sobre el usuario, como nombres, relaciones, pasatiempos y fechas importantes. Por ejemplo, "Trabajo en Google" o "Mi aniversario de bodas es el 31 de diciembre".
  • Preferencias del usuario (USER_PREFERENCES): Me gusta, No me gusta, estilos o patrones preferidos, ya sean explícitos o implícitos. Por ejemplo, "Prefiero el asiento del medio".
  • Eventos clave de la conversación y resultados de tareas (KEY_CONVERSATION_DETAILS): Son los hitos o las conclusiones importantes dentro del diálogo. Por ejemplo, "Reservé boletos de avión para un viaje de ida y vuelta entre JFK y SFO. Me voy el 1 de junio de 2025 y regreso el 7 de junio de 2025".
  • Instrucciones explícitas para recordar o olvidar (EXPLICIT_INSTRUCTIONS): Es la información que el usuario le pide explícitamente al agente que recuerde o olvide. Por ejemplo, si el usuario dice "Recuerda que uso Python principalmente", Memory Bank genera un recuerdo como "Uso Python principalmente".

• Temas personalizados: Tú defines la etiqueta y las instrucciones cuando configuras tu instancia de Memory Bank. Se usarán en la instrucción del paso de extracción de Memory Bank. Por ejemplo:

  Diccionario

  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."""
      }
  }
  

  Basado en clases

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

  Cuando uses temas personalizados, te recomendamos que también proporciones ejemplos de aprendizaje con pocos datos que demuestren cómo se deben extraer los recuerdos de tu conversación.

Con la personalización, puedes usar cualquier combinación de temas de la memoria. Por ejemplo, puedes usar un subconjunto de los temas de memoria administrada disponibles:

Diccionario

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

Basado en clases

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)
      ),
  ]
)

También puedes usar una combinación de temas administrados y personalizados (o solo temas personalizados):

Diccionario

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."""
        }
    }
  ]
}

Basado en clases

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

Varios ejemplos

Los ejemplos de pocas tomas te permiten demostrar el comportamiento esperado de extracción de memoria en Memory Bank. Por ejemplo, puedes proporcionar una conversación de entrada de muestra y los recuerdos que se espera que se extraigan de esa conversación.

Recomendamos usar siempre ejemplos con pocos disparos y temas personalizados para que Memory Bank pueda aprender el comportamiento previsto. Los ejemplos de pocos disparos son opcionales cuando se usan temas administrados, ya que Memory Bank define ejemplos para cada tema. Demuestra conversaciones que no se espera que generen recuerdos proporcionando una lista generated_memories vacía.

Por ejemplo, puedes proporcionar ejemplos con pocos ejemplos que demuestren cómo extraer comentarios sobre tu empresa a partir de los mensajes de los clientes:

Diccionario

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."
      }
    ]
}

Basado en clases

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

También puedes proporcionar ejemplos de conversaciones que no deberían generar recuerdos proporcionando una lista vacía para el resultado esperado (generated_memories):

Diccionario

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": []
}

Basado en clases

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 la memoria

De forma predeterminada, las memorias se generan en primera persona (p. ej., "Uso Memory Bank para la administración de la memoria"). Puedes configurar Memory Bank para que genere texto en tercera persona (p. ej., "El usuario usa Memory Bank para la administración de la memoria") con el parámetro enable_third_person_memories.

Diccionario

customization_config = {
  "enable_third_person_memories": True
}

Basado en clases

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Nota: Si proporcionas ejemplos de aprendizaje con pocos datos, asegúrate de que su perspectiva sea coherente con la perspectiva configurada de tu instancia.

Personalización de la consolidación

Durante la consolidación, Memory Bank determina cómo integrar la información recién adquirida en tu conjunto de memoria existente. Memory Bank evalúa si se deben AGREGAR recuerdos nuevos, ACTUALIZAR los recuerdos existentes con contexto adicional o BORRAR los recuerdos obsoletos.

Para garantizar recuerdos corroborados y de alta calidad, Memory Bank puede analizar de forma opcional el historial de un recuerdo para distinguir las tendencias a largo plazo de los valores atípicos únicos.

De forma predeterminada, Memory Bank solo compara la información nueva con la instantánea más reciente de una memoria candidata (una "revisión de memoria"). Para aumentar la profundidad de este análisis, configura el parámetro revisions_per_candidate_count. Este parámetro define cuántas revisiones anteriores de cada "memoria candidata" (el registro específico que se evalúa para una actualización) considera Memory Bank durante la consolidación.

Diccionario

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

Basado en clases

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 genera recuerdos más coherentes y corroborados, ya que tiene en cuenta la repetición de la información ingerida. Sin embargo, un recuento más alto aumenta el consumo de tokens durante el proceso de consolidación.

Configuración de la búsqueda de similitud

La configuración de la búsqueda de similitud controla qué modelo de embedding usa tu instancia para la búsqueda de similitud. La búsqueda por similitud se usa para identificar qué recuerdos deben ser candidatos para la consolidación y para la recuperación de recuerdos basada en la búsqueda por similitud. Si no se proporciona esta configuración, Memory Bank usa text-embedding-005 como modelo predeterminado.

Si esperas que las conversaciones de los usuarios sean en idiomas distintos del inglés, usa un modelo que admita varios idiomas, como gemini-embedding-001 o text-multilingual-embedding-002, para mejorar la calidad de la recuperación.

Diccionario

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

Basado en clases

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

Reemplaza lo siguiente:

• EMBEDDING_MODEL: Es el modelo de embedding de texto de Google que se usará para la búsqueda de similitud, en el formato projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuración de generación

La configuración de generación controla qué LLM se usa para generar recuerdos, lo que incluye extraer recuerdos y consolidar recuerdos nuevos con los existentes.

Memory Bank usa gemini-2.5-flash como modelo predeterminado. Para las regiones que no tienen disponibilidad regional de Gemini, se usa el extremo global.

Diccionario

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

Basado en clases

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

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

Reemplaza lo siguiente:

• LLM_MODEL: Es el modelo de LLM de Google que se usará para extraer y consolidar recuerdos, en el formato projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuración del tiempo de actividad (TTL)

La configuración del TTL controla cómo Memory Bank debe establecer de forma dinámica el tiempo de vencimiento de los recuerdos. Después de que transcurra el tiempo de vencimiento, no se podrán recuperar los recuerdos y se borrarán.

Si no se proporciona la configuración, no se establecerá de forma dinámica el tiempo de vencimiento para los recuerdos creados o actualizados, por lo que los recuerdos no vencerán a menos que se establezca manualmente su tiempo de vencimiento.

Existen dos opciones para la configuración del TTL:

• TTL predeterminado: El TTL se aplicará a todas las operaciones que creen o actualicen una memoria, incluidas UpdateMemory, CreateMemory y GenerateMemories.

  Diccionario

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

  Basado en clases

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

  Reemplaza lo siguiente:

  • TTL: Es la duración en segundos del TTL. En el caso de las memorias actualizadas, la fecha de vencimiento recién calculada (ahora + TTL) reemplazará la fecha de vencimiento anterior de la memoria.

• TTL detallado (por operación): El TTL se calcula en función de la operación que creó o actualizó la memoria. Si no se configura para una operación determinada, esta no actualizará la fecha de vencimiento de la memoria.

  Diccionario

  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"
        }
    }
  }
  

  Basado en clases

  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",
        )
    )
  )
  

  Reemplaza lo siguiente:

  • CREATE_TTL: Es la duración en segundos del TTL de los recuerdos creados con CreateMemory.
  • GENERATE_CREATED_TTL: Es la duración en segundos del TTL de los recuerdos creados con GenerateMemories.
  • GENERATE_UPDATED_TTL: Es la duración en segundos del TTL de los recuerdos actualizados con GenerateMemories. La fecha de vencimiento recién calculada (ahora + TTL) reemplazará la fecha de vencimiento anterior de la memoria.

¿Qué sigue?

Guía de inicio rápido

Guía de inicio rápido de la API de Memory Bank

Comienza a usar la API de Memory Bank para administrar recuerdos a largo plazo.

Guía de inicio rápido

Inicio rápido con el Kit de desarrollo de agentes

Comienza a usar el Kit de desarrollo de agentes (ADK).