Perfiles de memoria

Puedes usar Memory Bank para generar perfiles estructurados, que son estructuras de datos con esquemas estáticos que se completan y actualizan con LLM. Cuando defines un esquema fijo, garantizas que tus agentes tengan acceso inmediato y de baja latencia a la información en evolución sin necesidad de realizar operaciones de búsqueda costosas durante una sesión.

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

Descripción general

El uso de perfiles estructurados con tu agente garantiza que la información extraída, como las pilas técnicas o las preferencias de un usuario, esté disponible de forma rápida, concisa y con un formato coherente. Por ejemplo, puedes recuperar perfiles que incluyan contenido como el siguiente:

MemoryProfile(
    profile={
        "technical_stacks": "ADK, Python",
        "preferred_language": "Python",
        "tone_preference": "Succinct"
    },
    schema_id="user-profile"
)

Los perfiles estructurados están optimizados para la recuperación de baja latencia, ya que el trabajo duro de seleccionar la información se realiza en el momento de la generación. Son excelentes para inicializar una interacción entre un agente y un usuario.

Información sobre los perfiles de memoria estructurados

Los perfiles estructurados se generan con los mismos métodos (GenerateMemories y IngestEvents) que usas para los recuerdos en lenguaje natural. Una vez que definas un esquema, Memory Bank intentará generar automáticamente perfiles que se alineen con tu esquema usando las fuentes de datos proporcionadas.

Cuando se usan perfiles estructurados, Memory Bank realiza las siguientes operaciones durante la generación de memorias:

  • Extracción: Extrae información y contexto que se ajustan al esquema de la fuente de datos. Solo se extraerá la información que se alinee con el esquema. Puedes inspeccionar qué información y contexto se extrajeron con las revisiones de la memoria.
  • Consolidación: Actualiza (si es necesario) los campos existentes en el perfil. Un LLM evaluará cómo actualizar el contenido existente en función de la información y el contexto extraídos recientemente. Si el campo aún no existe en el perfil, se omitirá la consolidación y el campo se actualizará directamente con la información extraída.

Los perfiles se aíslan según el scope (como {"user_id": "123"}) que proporcionaste cuando transferiste datos a Memory Bank. Para cada esquema y alcance, el banco de memoria mantiene un solo perfil como fuente de información. Un perfil generado se compone de una o más instancias de Memory. Cada instancia de Memory representa un solo campo dentro del perfil que puedes usar para inspeccionar los metadatos y el historial de revisiones del campo, como los siguientes:

Memory(
     create_time=datetime.datetime(...),
     memory_type=<MemoryType.STRUCTURED_PROFILE: 'STRUCTURED_PROFILE'>,
     name='projects/.../locations/.../reasoningEngines/.../memories/...',
     scope={
       'user_id': '123'
     },
     structured_content=MemoryStructuredContent(
       data={
         'language_preference': 'Java'
       },
       schema_id='user-profile'
     ),
     update_time=datetime.datetime(...),
     expire_time=datetime.datetime(...),
     metadata={...}
)

Definición de esquema

Los perfiles que genera Memory Bank se alinean con los esquemas definidos en tu instancia de Memory Bank. Puedes definir varios esquemas de perfil independientes; cada esquema debe tener un ID único. Ten en cuenta que agregar o actualizar un esquema no reabastece los perfiles de memorias anteriores.

Console

Para agregar o editar esquemas de perfil en una instancia independiente de Memory Bank en la consola de Google Cloud (se requiere aiplatform.reasoningEngines.update para guardar los cambios), haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Memory Bank de Agent Platform y haz clic en tu instancia de Memory Bank.

    Ir a Memory Bank

  2. Haz clic en Schemas en la barra de acciones (o en la sección Generation de la pestaña Configuration).

  3. Haz clic en Agregar esquema para crear un esquema con un ID único o haz clic en el encabezado de una tarjeta de esquema existente para expandirla.

  4. Define o edita los campos del esquema con la vista Simple o JSON y, luego, haz clic en Guardar.

SDK de Agent Platform

Puedes usar un modelo de pydantic para definir los campos que quieres que Memory Bank extraiga y mantenga. Por ejemplo:

from pydantic import BaseModel, Field
from typing import Literal

class UserProfile(BaseModel):
    name: str = Field(
      description="Name of the user.")
    technical_stack: str = Field(
      description="Comma-separated list tools or languages used by the user.")
    primary_goal: str = Field(
      description="The main objective the user is pursuing.")
    expertise_level: str = Field(
      description="Current skill level (e.g., Junior, Senior).")
    job_status: Literal['unemployed', 'part_time', 'full_time', 'student'] = Field(
      description="The job status of the individual")

Sube el esquema a Memory Bank cuando crees o actualices tu instancia de Memory Bank:

schema_config = {
  "id": "user-profile",
  "memory_schema": UserProfile.model_json_schema()
}

memory_bank = client.memory_banks.create(
    managed_semantic_memory_config={
        "structured_memory_configs": [
            {
                "schema_configs": [schema_config]
            }
        ]
    }
)

De forma predeterminada, Memory Bank extrae recuerdos en lenguaje natural. Puedes desactivar la generación de memoria en lenguaje natural si solo quieres que Memory Bank genere perfiles:

memory_bank = client.memory_banks.create(
    managed_semantic_memory_config={
        "structured_memory_configs": [
            {
                "schema_configs": [schema_config]
            }
        ],
        # Optional: Turn off natural language memories.
        "unstructured_memory_configs": [
            {"disable_natural_language_memories": True}
        ]
    }
)

Generación de perfiles

Activas la generación de memorias estructuradas proporcionando un historial de conversaciones (eventos) a los métodos GenerateMemories o IngestEvents. Al igual que con las memorias de lenguaje natural, Memory Bank usa LLM para extraer información significativa de las fuentes de datos y consolidarla con las memorias existentes.

Ejemplo

En el siguiente ejemplo, se explica cómo generar un perfil de memoria con el esquema definido anteriormente.

En el primer conjunto de eventos enviados a Memory Bank para el permiso {"user_id": "123"}, el usuario indica que trabaja con agentes de ADK:

client.memory_banks.memories.generate(
  name=memory_bank.name,
  scope={"user_id": "123"},
  direct_contents_source={
    "events": [
      {"content": {
        "parts": [{
          "text": "Can you help me build an ADK agent that organizes my daily tasks?"}]}}]
  }
)

Memory Bank extrae "ADK" para el campo technical_stack en el esquema. No se completan otros campos porque el evento transferido no contiene información relevante para el resto del esquema. Como esta es la primera interacción para este alcance, se omite la consolidación y el perfil se inicializa con este valor inicial.

result = client.memory_banks.memories.retrieve_profiles(
    name=memory_bank.name,
    scope={"user_id": "123"},
)

"""
Returns:

RetrieveProfilesResponse(
  profiles={
    'user-profile': MemoryProfile(
      profile={
        'technical_stack': 'ADK'
      },
      schema_id='user-profile'
    )
  }
)
"""

En el siguiente conjunto de eventos enviados a Memory Bank, el usuario indica que es estudiante y que programa principalmente en Python:

client.memory_banks.memories.generate(
  name=memory_bank.name,
  scope={"user_id": "123"},
  direct_contents_source={
    "events": [
      {"content": {
        "parts": [
          {"text": "Do you have any career recommendations for students that specialize in Python?"}]}}]
  }
)

Memory Bank extrae tanto "Python" como el estado de "estudiante" de la interacción. Se consolida el fragmento technical_stack, que agrega "Python" a la entrada "ADK" existente. El sistema completa el campo job_status, que antes estaba vacío, con la enumeración "student" y omite el paso de consolidación.

result = client.memory_banks.memories.retrieve_profiles(
    name=memory_bank.name,
    scope=scope
)

"""
Returns:

RetrieveProfilesResponse(
  profiles={
    'user-profile': MemoryProfile(
      profile={
        'technical_stack': 'ADK, Python',
        'job_status': 'student'
      },
      schema_id='user-profile'
    )
  }
)
"""

Recuperación de perfiles

Una vez generado, puedes recuperar el perfil consolidado para un permiso específico con el método RetrieveProfiles. Esto devuelve los datos más actualizados asignados a tu esquema.

result = client.memory_banks.memories.retrieve_profiles(
  name=memory_bank.name,
  scope={"user_id": "123"},
)

# Accessing the data
for profile in result.profiles.values():
  print(profile)
  # Output: {'technical_stack': 'ADK, Python', 'job_status': 'student', ...}

Inspección de perfiles

De forma interna, un perfil se compone de recuerdos individuales de tipo STRUCTURED_PROFILE. Cada campo de tu esquema se asigna a una sola memoria por alcance, lo que proporciona una observabilidad detallada.

Si bien RetrieveProfiles es el método principal para recuperar perfiles en producción, puedes inspeccionar recuerdos individuales en la consola deGoogle Cloud o con el SDK de Agent Platform para auditar la evolución del perfil:

  • Metadatos a nivel de campo: Consulta y actualiza el tiempo de actividad (TTL) específico y Memory.metadata para campos individuales en el perfil.
  • Historial de revisiones: Realiza un seguimiento del linaje de un campo para ver los valores históricos y el contexto de conversación específico que activó cada cambio.

Console

  1. En la consola de Google Cloud , abre tu instancia independiente en la página Banco de memoria o tu agente implementado en la página Implementaciones y, luego, selecciona la pestaña Memorias.

    Ir a Memory Bank

  2. Selecciona Estructurado y, luego, elige valores para todas las claves en el alcance de destino (o aplica un filtro de alcance en No estructurado y haz clic en Buscar memorias estructuradas). Las filas de perfiles coincidentes muestran Esquema, Tipo, Contenido, Creado y Actualizado.

  3. Haz clic en Ver en una fila de perfil para abrir el panel Detalles de la memoria, que muestra el chip de alcance, un vínculo al esquema, los datos de la memoria individuales (con Ver revisiones para cada dato) y el JSON del perfil consolidado.

SDK de Agent Platform

Usa RetrieveMemories para recuperar recuerdos que contengan fragmentos del perfil de un usuario. De forma predeterminada, RetrieveMemories solo recupera recuerdos en lenguaje natural, por lo que debes solicitar de forma explícita recuerdos de STRUCTURED_PROFILE:

client.memory_banks.memories.retrieve(
  name="...",
  scope={"user_id": "123"},
  config={
    "memory_types": ["STRUCTURED_PROFILE"]
  }
)

"""
Returns:

[RetrieveMemoriesResponseRetrievedMemory(
   memory=Memory(
     create_time=datetime.datetime(...),
     memory_type=<MemoryType.STRUCTURED_PROFILE: 'STRUCTURED_PROFILE'>,
     name='projects/.../locations/.../reasoningEngines/.../memories/...',
     scope={
       'user_id': '123'
     },
     structured_content=MemoryStructuredContent(
       data={
         'technical_stack': 'ADK, Python'
       },
       schema_id='user'
     ),
     update_time=datetime.datetime(...)
   )
 )]
"""

Luego, recupera el historial de revisiones de un fragmento de perfil estructurado para inspeccionar cómo cambió el campo del perfil con el tiempo y el contexto de cada cambio:

for retrieved_memory in list(results):
    list(client.memory_banks.memories.revisions.list(
        name=retrieved_memory.memory.name
    ))

"""
Returns:

[MemoryRevision(
   create_time=datetime.datetime(...),
   expire_time=datetime.datetime(...),
   extracted_memories=[
     IntermediateExtractedMemory(
       context='The user indicated that they have expertise in Python when asking about career options.',
       structured_data={
         'technical_stack': 'Python'
       }
     ),
   ],
   name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...',
   structured_data={
     'technical_stack': 'ADK, Python'
   }
 ),
 MemoryRevision(
   create_time=datetime.datetime(...),
   expire_time=datetime.datetime(...),
   extracted_memories=[
     IntermediateExtractedMemory(
       context='The user indicated that they need help building an ADK agent',
       structured_data={
         'technical_stack': 'ADK'
       }
     ),
   ],
   name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...',
   structured_data={
     'technical_stack': 'ADK'
   }
 )]
"""