Generar recuerdos

Memory Bank te permite construir recuerdos a largo plazo a partir de conversaciones entre el usuario y tu agente. En esta página, se describe cómo funciona la generación de recuerdos, cómo puedes personalizar la forma en que se extraen los recuerdos y cómo activar la generación de recuerdos.

Información sobre la generación de memoria

Memory Bank extrae recuerdos de los datos fuente y los organiza automáticamente para una colección específica de recuerdos (definida por un scope) agregando, actualizando y quitando recuerdos con el tiempo.

Cuando activas la generación de recuerdos, el Banco de recuerdos realiza las siguientes operaciones:

  • Extracción: Extrae información sobre el usuario de sus conversaciones con el agente. Solo se conservará la información que coincida con al menos uno de los temas de memoria de tu instancia.

  • Consolidación: Identifica si se deben borrar o actualizar los recuerdos existentes con el mismo alcance en función de la información extraída. Memory Bank verifica que los recuerdos nuevos no sean duplicados ni contradictorios antes de combinarlos con los recuerdos existentes. Si los recuerdos existentes no se superponen con la información nueva, se creará un recuerdo nuevo.

Los recuerdos solo se pueden extraer del texto, los archivos intercalados y los datos de archivos del contenido fuente. Todo el resto del contenido, incluidas las llamadas y respuestas de funciones, se ignora cuando se generan recuerdos.

Los recuerdos se pueden extraer de imágenes, videos y audios proporcionados por el usuario. Si Memory Bank considera que el contexto proporcionado por la entrada multimodal es significativo para las interacciones futuras, se puede crear una memoria textual que incluya la información extraída de la entrada. Por ejemplo, si el usuario proporciona una imagen de un golden retriever con el texto "Este es mi perro", Memory Bank genera un recuerdo como "Mi perro es un golden retriever".

Temas de recuerdos

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
        )
    )
    
  • 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 para demostrar cómo se deben extraer los recuerdos de tu conversación.

De forma predeterminada, Memory Bank conserva todos los siguientes temas administrados:

  • Información personal (USER_PERSONAL_INFO): Es la información personal importante sobre el usuario, como nombres, relaciones, pasatiempos y fechas importantes. Por ejemplo, "Trabajo en Google" o "Mi aniversario de boda es el 31 de diciembre".
  • Preferencias del usuario (USER_PREFERENCES): Me gusta, No me gusta, estilos preferidos o patrones declarados 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".

Esto equivale a usar el siguiente conjunto de temas de memoria administrada:

Diccionario

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

Basado en clases

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

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

Si quieres personalizar los temas que conserva Memory Bank, establece los temas de la memoria en tu configuración de personalización cuando configures Memory Bank.

Generación de recuerdos

Para completar los pasos que se muestran en esta guía, primero debes seguir los pasos que se indican en Configura Memory Bank.

Puedes activar la generación de recuerdos con GenerateMemories al final de una sesión o en intervalos regulares dentro de una sesión. La generación de memoria extrae el contexto clave de las conversaciones fuente y lo combina con las memorias existentes para el mismo alcance. Por ejemplo, puedes crear recuerdos a nivel de la sesión con un alcance como {"user_id": "123", "session_id": "456"}. Los recuerdos con el mismo alcance se pueden consolidar y recuperar juntos.

Cuando llames a GenerateMemories, debes proporcionar la conversación de origen a través de sesiones de Agent Engine o directamente en formato JSON:

Formato JSON

Si usas un almacenamiento de sesión diferente de las sesiones de Agent Engine, proporciona la conversación fuente directamente en formato JSON:

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Reemplaza lo siguiente:

  • EVENTS: Es una lista de diccionarios de contenido. Por ejemplo:
[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]
  • SCOPE: Es un diccionario que representa el alcance de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"} Solo se consideran para la consolidación los recuerdos con el mismo alcance.

Sesiones de Agent Engine

Con las sesiones de Agent Engine, Memory Bank usa los eventos de la sesión como la conversación fuente para la generación de memoria.

Para definir el alcance de los recuerdos generados, el Banco de recuerdos extrae y usa el ID del usuario de la sesión de forma predeterminada. Por ejemplo, el alcance de los recuerdos se almacena como {"user_id": "123"} si el user_id de la sesión es "123". También puedes proporcionar un scope directamente, lo que anula el uso del user_id de la sesión como alcance.

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    "session": "SESSION_NAME"
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Reemplaza lo siguiente:

  • SESSION_NAME: Es el nombre de la sesión.

  • SCOPE: Es un diccionario que representa el alcance de los recuerdos generados (opcional). Por ejemplo, {"session_id": "MY_SESSION"} Solo se consideran para la consolidación los recuerdos con el mismo alcance. Si no se proporciona, se usa {"user_id": session.user_id}.

GenerateMemories es una operación de larga duración. Una vez que se complete la operación, el objeto AgentEngineGenerateMemoriesOperation contendrá una lista de los recuerdos generados, si se generó alguno:

AgentEngineGenerateMemoriesOperation(
  name="projects/.../locations/.../reasoningEngines/.../operations/...",
  done=True,
  response=GenerateMemoriesResponse(
    generatedMemories=[
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="CREATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="UPDATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="DELETED",
      ),
    ]
  )
)

Cada memoria generada incluye la action que se realizó en esa memoria:

  • CREATED: Indica que se agregó un recuerdo nuevo, lo que representa un concepto novedoso que no se capturó en los recuerdos existentes.
  • UPDATED: Indica que se actualizó un recuerdo existente, lo que sucede si el recuerdo abarcaba conceptos similares a la información recién extraída. El hecho de la memoria se puede actualizar con información nueva o permanecer igual.
  • DELETED: Indica que se borró la memoria existente porque su información era contradictoria con la información nueva extraída de la conversación.

En el caso de los recuerdos de CREATED o UPDATED, puedes usar GetMemories para recuperar el contenido completo del recuerdo. Cuando se recuperan recuerdos de DELETED, se produce un error 404.

Generando recuerdos en segundo plano

GenerateMemories es una operación de larga duración. De forma predeterminada, client.agent_engines.generate_memories es una función de bloqueo y seguirá sondeo la operación hasta que finalice. Ejecutar la generación de recuerdos como una operación de bloqueo es útil cuando deseas inspeccionar manualmente los recuerdos generados o cuando deseas notificar a los usuarios finales qué recuerdos se generaron.

Sin embargo, para los agentes de producción, generalmente querrás ejecutar la generación de memoria en segundo plano como un proceso asíncrono. En la mayoría de los casos, el cliente no necesita usar el resultado de la ejecución actual, por lo que no es necesario incurrir en latencia adicional esperando una respuesta. Si deseas que la generación de memoria se ejecute en segundo plano, establece wait_for_completion en False:

client.agent_engines.memories.generate(
    ...,
    config={
        "wait_for_completion": False
    }
)

Consolidación de recuerdos extraídos previamente

Como alternativa al proceso de extracción automática de Memory Bank, puedes proporcionar directamente recuerdos preextraídos. Los recuerdos de fuente directa se consolidarán con los recuerdos existentes para el mismo alcance. Esto puede ser útil cuando quieres que tu agente o un humano en el circuito se encarguen de extraer recuerdos, pero aún quieres aprovechar la consolidación de Memory Bank para asegurarte de que no haya recuerdos duplicados o contradictorios.

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Reemplaza lo siguiente:

  • FACT: Es el hecho extraído previamente que se debe consolidar con los recuerdos existentes. Puedes proporcionar hasta 5 hechos preextraídos en una lista como la siguiente:

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
    
  • SCOPE: Es un diccionario que representa el alcance de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"} Solo se consideran para la consolidación los recuerdos con el mismo alcance.

¿Qué sigue?