Quickstart with Agent Development Kit

After you configure your Agent Development Kit (ADK) agent to use Memory Bank, your agent orchestrates calls to Memory Bank to manage long-term memories for you.

This tutorial demonstrates how you can use Memory Bank with the ADK to manage long-term memories:

1. Create your local ADK agent and runner.

2. Interact with your agent to dynamically generate long-term memories that are accessible across sessions.

3. Clean up.

To make calls directly to Memory Bank without ADK orchestration, see Quickstart with Agent Engine SDK. Using the Agent Engine SDK is helpful for understanding how Memory Bank generates memories or for inspecting the contents of Memory Bank.

Before you begin

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

Set environment variables

To use the ADK, set your environment variables:

import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

Replace the following:

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

Create your ADK agent

1. When developing your ADK agent, include a Memory tool that controls when the agent retrieves memories and how memories are included in the prompt. The example agent uses the PreloadMemoryTool, which always retrieves memories at the start of each turn and includes the memories in the system instruction:

   from google import adk
   
   agent = adk.Agent(
       model="gemini-2.0-flash",
       name='stateful_agent',
       instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.
   
   1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
   2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
   3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
   4.  **Brevity:** Limit responses to under 30 words.
   """,
       tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
   )
   

2. Create a VertexAiMemoryBankService memory service, which the ADK runner uses for retrieving memories. This is optional if you're using the Agent Engine ADK template instead of defining your own ADK runtime.

   from google.adk.memory import VertexAiMemoryBankService
   
   agent_engine_id = agent_engine.api_resource.name.split("/")[-1]
   
   memory_service = VertexAiMemoryBankService(
       project="PROJECT_ID",
       location="LOCATION",
       agent_engine_id=agent_engine_id
   )
   

   VertexAiMemoryBankService is an ADK wrapper around Memory Bank that is defined by ADK's BaseMemoryServiceand uses a different interface than the Agent Engine SDK. You can use the Agent Engine SDK to make direct API calls to Memory Bank. The VertexAiMemoryBankService interface includes:

   • memory_service.add_session_to_memory which triggers a GenerateMemories request to Memory Bank using the provided adk.Session as the source content. Calls to this method are not orchestrated by the ADK runner. If you want to automate memory generation with ADK, you need to define your own callback functions.

   • memory_service.search_memory which triggers a RetrieveMemories request to Memory Bank to fetch relevant memories for the current user_id and app_name. Calls to this method are orchestrated by the ADK runner when you provide a Memory tool to your agent.

3. Create an ADK Runtime, which orchestrates the execution of your agents, tools, and callbacks. The ADK Runner setup depends on which deployment environment you're using:

from google.adk.sessions import VertexAiSessionService
from google.genai import types

# You can use any ADK session service.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

app_name="APP_NAME"

runner = adk.Runner(
    agent=agent,
    app_name=app_name,
    session_service=session_service,
    memory_service=memory_service
)

def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run(user_id=user_id, session_id=session, new_message=content)

  for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

import vertexai
from vertexai.preview.reasoning_engines import AdkApp

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

adk_app = AdkApp(agent=agent)

# Create a new Agent Engine with your agent deployed to Agent Engine Runtime.
# The Agent Engine instance will also include an empty Memory Bank.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

# Alternatively, update an existing Agent Engine to deploy your agent to Agent Engine Runtime.
# Your agent will have access to the Agent Engine instance's existing memories.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

async def call_agent(query, session_id, user_id):
    async for event in agent_engine.async_stream_query(
        user_id=user_id,
        session_id=session_id,
        message=query,
    ):
        print(event)

def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )

adk_app = AdkApp(
      agent=adk_agent,
      # Override the default memory service.
      memory_service_builder=memory_bank_service_builder
)

async def call_agent(query, session_id, user_id):
  # adk_app is a local agent. If you want to deploy it to Agent Engine Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Engine instance instead.
  async for event in adk_app.async_stream_query(
      user_id=user_id,
      session_id=session_id,
      message=query,
  ):
      print(event)

Interact with your agent

After defining your agent and setting up Memory Bank, you can interact with your agent.

1. Create your first session. Since there are no available memories during the first session with a user, the agent doesn't know any user preferences, such as their preferred temperature:

   adk.Runner

   When using adk.Runner, you can call your ADK memory and session services directly.

   session = await session_service.create_session(
       app_name="APP_NAME",
       user_id="USER_ID"
   )
   
   call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.id,
       "USER_ID"
   )
   
   # Agent response: "What is your preferred temperature?"
   call_agent("I like it at 71 degrees", session.id, "USER_ID")
   # Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
   # Temperature successfully changed.
   

   Replace the following:

   • APP_NAME: App name for your runner.
   • USER_ID: An identifier for your user. Memories generated from this session are keyed by this opaque identifier. The generated memories' scope is stored as {"user_id": "USER_ID"}.

   Agent Engine ADK template

   When using the Agent Engine ADK template, you can call your Agent Engine Runtime to interact with memory and sessions.

   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   await call_agent(
       "Can you update the temperature to my preferred temperature?",
       session.get("id"),
       "USER_ID"
   )
   
   # Agent response: "What is your preferred temperature?"
   await call_agent("I like it at 71 degrees", session.get("id"), "USER_ID")
   # Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
   # Temperature successfully changed.
   

   Replace the following:

   • USER_ID: An identifier for your user. Memories generated from this session are keyed by this opaque identifier. The generated memories' scope is stored as {"user_id": "USER_ID"}.

2. Generate memories for your current session. If Memory Bank extracts memories from the conversation, they are stored under the scope {"user_id": USER_ID, "app_name": APP_NAME}.

   adk.Runner

   session = await session_service.get_session(
       app_name=app_name,
       user_id="USER_ID",
       session_id=session.id
   )
   memory_service.add_session_to_memory(session)
   

   Agent Engine ADK template

   await agent_engine.async_add_session_to_memory(session=session)
   

3. Create your second session. If you used the PreloadMemoryTool, the agent retrieves memories at the beginning of each turn to access preferences the user previously communicated to the agent.

   adk.Runner

   session = await session_service.create_session(
       app_name=app_name,
       user_id="USER_ID"
   )
   
   call_agent("Fix the temperature!", session.id, "USER_ID")
   # Agent Response:  Setting temperature to 71 degrees.  Is that correct?
   

   You can also use memory_service.search_memory to retrieve memories directly:

   await memory_service.search_memory(
       app_name="APP_NAME",
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

   Agent Engine ADK template

   session = await agent_engine.async_create_session(user_id="USER_ID")
   
   await call_agent("Fix the temperature!", session.get("id"), "USER_ID")
   # Agent Response:  Setting temperature to 71 degrees.  Is that correct?
   

   You can also use agent_engine.async_search_memory to retrieve memories directly: Note: To use async_search_memory, your AdkApp must have been created with google-cloud-aiplatform version 1.110.0 or newer. Otherwise, you can retrieve memories by making direct calls to Memory Bank.

   await agent_engine.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   

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 belonging to that Vertex AI Agent Engine.

   agent_engine.delete(force=True)
   

2. Delete any locally created files.

What's next

• Quickstart with Agent Engine SDK.