Quickstart with Vertex AI Agent Engine SDK

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This tutorial demonstrates how to make API calls directly to Vertex AI Agent Engine Sessions and Memory Bank using the Vertex AI Agent Engine SDK. Use the Vertex AI Agent Engine SDK if you don't want an agent framework to orchestrate calls for you, or you want to integrate Sessions and Memory Bank with agent frameworks other than Agent Development Kit (ADK).

For the quickstart using ADK, see Quickstart with Agent Development Kit.

This tutorial uses the following steps:

1. Create memories using the following options:
   • Generate memories using Vertex AI Agent Engine Memory Bank: Write sessions and events to Vertex AI Agent Engine Sessions as sources for Vertex AI Agent Engine Memory Bank to generate memories.
   • Upload memories directly: Write your own memories or have your agent build memories if you want full control over what information is persisted.
2. Retrieve memories.
3. Clean up.

Before you begin

To complete the steps demonstrated in this tutorial, you must first follow the steps in Set up for Memory Bank.

Generate memories with Vertex AI Agent Engine Sessions

After setting up Vertex AI Agent Engine Sessions and Memory Bank, you can create sessions and append events to them. Memories are generated as facts from the user's conversation with the agent so that they're available for future user interactions. For more information, see Generate memories and Fetch memories.

Note: You can also provide the conversation history directly in the GenerateMemories payload using direct contents source.

1. Create a session with an opaque user ID. Any memories generated from this session are automatically keyed by the scope {"user_id": "USER_ID"} unless you explicitly provide a scope when generating memories.

   import vertexai
   
   client = vertexai.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   
   session = client.agent_engines.create_session(
     name=AGENT_ENGINE_NAME,
     user_id="USER_ID"
   )
   

   Replace the following:

   • PROJECT_ID: Your project ID.

   • LOCATION: Your region. See the supported regions for Memory Bank.

   • AGENT_ENGINE_NAME: The name of the Vertex AI Agent Engine instance that you created or an existing Vertex AI Agent Engine instance. The name should be in the following format: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

   • USER_ID: An identifier for your user. Any memories generated from this session are automatically keyed by the scope {"user_id": "USER_ID"} unless you explicitly provide a scope when generating memories.

2. Iteratively upload events to your session. Events can include any interactions between your user, agent, and tools. The ordered list of events represents your session's conversation history. This conversation history is used as the source material for generating memories for that particular user.

   import datetime
   
   client.agent_engines.append_session_event(
     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"}]
       }
     }
   )
   

3. To generate memories from your conversation history, trigger a memory generation request for the session:

   client.agent_engines.generate_memories(
     name=agent_engine.api_resource.name,
     vertex_session_source={
       # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
       "session": session.response.name
     },
     # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
     scope=SCOPE
   )
   

Replace the following:

• (Optional) SCOPE: A dictionary representing the scope of the generated memories, with a maximum of 5 key value pairs and no * characters. For example, {"session_id": "MY_SESSION"}. Only memories with the same scope are considered for consolidation. If not provided, {"user_id": session.user_id} is used.

Upload memories

As an alternative to generating memories using raw dialogue, you can upload memories or have your agents add them directly using GenerateMemories with pre-extracted facts. Rather than Memory Bank extracting information from your content, you provide the facts that should be stored about your user directly. We recommended that you write facts about users in first person (for example, I am a software engineer).

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

Replace the following:

• FACT: The pre-extracted fact that should be consolidated with existing memories. You can provide up to 5 pre-extracted facts in a list like the following:

  {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
  

• SCOPE: A dictionary, representing the scope of the generated memories. For example, {"session_id": "MY_SESSION"}. Only memories with the same scope are considered for consolidation.

Alternatively, you can use CreateMemory to upload memories without using Memory Bank for either memory extraction or consolidation.

Caution: Memories uploaded using CreateMemory won't be consolidated with existing memories, so you can end up with duplicated memories for the same scope. Created memories are available for similarity search and can be consolidated for future requests when generating memories.

memory = client.agent_engines.create_memory(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

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

Retrieve and use memories

You can retrieve memories for your user and include them in your system instructions to give the LLM access to your personalized context.

For more information about retrieving memories using a scope-based method, see Fetch memories.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.retrieve_memories(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

You can use jinja to convert your structured memories into a prompt:

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

Delete memories

You can delete a specific memory using its resource name:

client.agent_engines.delete_memory(name=MEMORY_NAME)

Replace the following:

• MEMORY_NAME: The name of the Memory to delete. The name should be in the following format: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. You can find the Memory name by fetching memories.

Clean up

To clean up all resources used in this project, you can delete the Google Cloud project you used for the quickstart.

Otherwise, you can delete the individual resources you created in this tutorial, as follows:

1. Use the following code sample to delete the Vertex AI Agent Engine instance, which also deletes any sessions or memories associated with the Vertex AI Agent Engine instance.

   agent_engine.delete(force=True)
   

2. Delete any locally created files.

What's next

• Quickstart with Agent Development Kit.