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 BaseMemoryService and 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 .