Puedes usar el SDK de Agent Platform para hacer llamadas a la API directamente a Memory Bank. Usa el SDK de Agent Platform si no quieres que un framework de agentes coordine las llamadas por ti o si quieres integrar Memory Bank con frameworks de agentes que no sean el Kit de desarrollo de agentes (ADK).
En este documento, se muestra cómo crear, subir, recuperar y quitar recuerdos con llamadas a la API.
Para la guía de inicio rápido con ADK, consulta Guía de inicio rápido de Memory Bank con ADK.
Antes de comenzar
Para completar los pasos que se muestran en este instructivo, primero debes seguir los pasos que se indican en Configuración de Memory Bank. Antes de comenzar esta guía de inicio rápido, asegúrate de haber creado una instancia de Memory Bank y una instancia de Sessions, como se muestra en el siguiente ejemplo:
import agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION"
)
memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()
Genera recuerdos con Agent Platform Sessions
Después de configurar Agent Platform Sessions, puedes crear sesiones y agregarles eventos. Luego, puedes usar Memory Bank para generar recuerdos a partir de la conversación del usuario con el agente, de modo que los recuerdos estén disponibles para futuras interacciones del usuario. Para obtener más información, consulta Genera recuerdos y Recupera recuerdos.
Crea una sesión con un ID de usuario opaco. Todos los recuerdos generados a partir de esta sesión se etiquetan automáticamente con el alcance
{"user_id": "USER_ID"}, a menos que proporciones un alcance de forma explícita cuando generes recuerdos.import agentplatform client = agentplatform.Client( project="PROJECT_ID", location="LOCATION" ) session = client.sessions.create( # The name can be fetched using `sessions.name`. name="SESSIONS_NAME", user_id="USER_ID" )Reemplaza lo siguiente:
PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones admitidas para la función Memory Bank.
SESSIONS_NAME: Es el nombre de la instancia de Sessions que creaste o una instancia de Sessions existente. El nombre debe tener el siguiente formato:
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.USER_ID: Es un identificador para tu usuario. Todos los recuerdos generados a partir de esta sesión se indexan automáticamente según el alcance
{"user_id": "USER_ID"}, a menos que proporciones un alcance de forma explícita cuando generes recuerdos.
Sube eventos de forma iterativa a tu sesión. Los eventos pueden incluir cualquier interacción entre el usuario, el agente y las herramientas. La lista ordenada de eventos representa el historial de conversaciones de tu sesión. Este historial de conversación se usa como material de referencia para generar recuerdos para ese usuario en particular.
import datetime client.sessions.events.append( name=session.response.name, author="user", # Required by Sessions. invocation_id="1", # Required by Sessions. timestamp=datetime.datetime.now(tz=datetime.timezone.utc), # Required by Sessions. config={ "content": { "role": "user", "parts": [{"text": "hello"}] } } )Para generar recuerdos a partir de tu historial de conversaciones, activa una solicitud de generación de recuerdos para la sesión:
client.memory_banks.memories.generate( name=memory_bank.name, vertex_session_source={ # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...". "session": session.response.name }, # Optional when using Sessions. Defaults to {"user_id": session.user_id}. scope=SCOPE )
Reemplaza lo siguiente:
- (Opcional) SCOPE: Es un diccionario que representa el alcance de los recuerdos generados, con un máximo de 5 pares clave-valor y sin caracteres
*. 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}.
Cómo subir recuerdos
Como alternativa a generar recuerdos a partir de diálogos sin procesar, puedes subir recuerdos o hacer que tus agentes los agreguen directamente con GenerateMemories con hechos preextraídos.
En lugar de que Memory Bank extraiga información de tu contenido, tú proporcionas directamente los datos que se deben almacenar sobre tu usuario.
Para garantizar la coherencia con los recuerdos generados, intenta escribir hechos preextraídos con la misma perspectiva que configuraste para el alcance determinado. De forma predeterminada, los recuerdos se generan en primera persona (por ejemplo, I
am a software engineer).
client.memory_banks.memories.generate(
name=memory_bank.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 extraídos previamente 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.
Como alternativa, puedes usar CreateMemory para subir recuerdos sin usar Memory Bank para la extracción o la consolidación de recuerdos.
memory = client.memory_banks.memories.create(
name=memory_bank.name,
fact="This is a fact.",
scope={"user_id": "123"}
)
"""
Returns a MemoryOperation containing the created Memory like:
MemoryOperation(
done=True,
metadata={
"@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
"genericMetadata": {
"createTime": '2025-06-26T01:15:29.027360Z',
"updateTime": '2025-06-26T01:15:29.027360Z'
}
},
name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
response=Memory(
create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
fact="This is a fact.",
name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
scope={
"user_id": "123"
},
update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
)
)
"""
Cómo recuperar y usar recuerdos
Puedes recuperar recuerdos de tu usuario y agregarlos a tus instrucciones del sistema para darle al LLM acceso a tu contexto personalizado.
Para obtener más información sobre cómo recuperar recuerdos con un método basado en el alcance, consulta Cómo recuperar recuerdos.
# Retrieve memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope={"user_id": "123"}
).page
Puedes usar jinja para convertir tus recuerdos estructurados en una instrucción:
from jinja2 import Template
template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")
prompt = template.render(data=retrieved_memories)
"""
Output:
<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""
Cómo quitar recuerdos
Existen varias formas de borrar recuerdos de tu instancia de Memory Bank, según cómo quieras seleccionar los recuerdos que se deben quitar.
Quitar por nombre de recurso
Si sabes exactamente qué recurso de memoria quieres quitar, puedes borrar una memoria específica con su nombre de recurso:
client.memory_banks.memories.delete(
name=MEMORY_NAME,
config={
# Set to false (default) if you want to delete the memory asynchronously.
"wait_for_completion": True
}
)
Reemplaza lo siguiente:
- MEMORY_NAME: Es el nombre de la memoria que se borrará. El nombre debe tener el siguiente formato:
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Puedes encontrar el nombre del recuerdo recuperando recuerdos.
Quitar por criterios
Puedes usar el borrado basado en criterios para quitar uno o más recuerdos. Solo se borrarán los recuerdos que coincidan con los filtros proporcionados. Debes especificar al menos uno de los atributos filter (aplicado a los campos del sistema) o filter_groups (aplicado a los campos de metadatos).
operation = client.memory_banks.memories.purge(
name=memory_bank.name,
# Specify at least one of `filter` or `filter_groups`.
filter="FILTER_STRING",
filter_groups=FILTER_GROUPS,
# Set to false (default) if you want to stage but not execute the purge operation.
force=True,
config={
# Set to false (default) if you want to purge memories asynchronously.
"wait_for_completion": True
}
)
Reemplaza lo siguiente:
- FILTER_STRING: Es una cadena que usa la sintaxis de EBNF para filtrar los campos del sistema. Los campos del sistema incluyen
create_time,update_time,factytopics. Para obtener más información sobre el filtrado en función de los campos del sistema, consulta la sección Filtrar por campos de metadatos en la página Recuperar recuerdos. - FILTER_GROUPS: Es una lista de diccionarios o de objetos para filtrar los metadatos de la memoria. Para obtener más información sobre el filtrado en función de los campos de metadatos, consulta la sección Filtra por campos del sistema en la página Recuperar recuerdos.
La operación devolverá un recuento de cuántos recuerdos se borraron (si es force=True) o se borrarían si se ejecutara la operación (si es force=False).
print(operation.response.purge_count)
Por ejemplo, puedes purgar todos los recuerdos que pertenecen a un alcance para user_id "123":
operation = client.memory_banks.memories.purge(
name=memory_bank.name,
filter="scope.user_id=\"123\"",
force=True
)
Quitar por significado semántico
Durante la generación de memoria, Memory Bank decidirá si crear, actualizar o borrar recuerdos según el contenido de la información recién extraída y los recuerdos existentes. Es posible que se borre un recuerdo si la información nueva lo contradice o si el contenido extraído le indica a Memory Bank que olvide un tema (en el caso del tema de recuerdo EXPLICIT_INSTRUCTIONS).
Por ejemplo, la siguiente solicitud borraría los recuerdos existentes que contienen información sobre preferencias dietéticas, si existen para el scope determinado:
from google import genai
client.memory_banks.memories.generate(
name=memory_bank.name,
direct_contents_source={
"events": [{
"content": genai.types.Content(
role="user",
parts=[
genai.types.Part.from_text(text="Forget my dietary preferences.")
]
)
}]
},
scope={...}
)
Realiza una limpieza
Para limpiar todos los recursos que se usaron en este proyecto, puedes borrar el Google Cloud proyecto que usaste para la guía de inicio rápido.
De lo contrario, puedes borrar los recursos individuales que creaste en este instructivo de la siguiente manera:
Usa la siguiente muestra de código para borrar Agent Platform Memory Bank y Agent Runtime en las instancias de Gemini Enterprise Agent Platform:
client.memory_banks.delete(name=memory_bank.name, force=True) client.runtimes.delete(name=sessions.name, force=True)Borra los archivos creados de forma local.
¿Qué sigue?
Inicio rápido con el Kit de desarrollo de agentes
Comienza a usar el Kit de desarrollo de agentes (ADK).