Quickstart with Agent Development Kit

After you configure your Agent Development Kit (ADK) agent to use Vertex AI Agent Engine Sessions and Memory Bank, your agent automatically reads and writes memories and sessions for you.

For the quickstart using the REST API, see Quickstart with REST API.

This tutorial demonstrates how you can use Vertex AI Agent Engine Sessions and Memory Bank with the ADK to create and use sessions and long-term memories:

1. Create your Vertex AI Agent Engine instance to access Vertex AI Agent Engine Sessions and Memory Bank.

2. Create your local ADK agent and runner.

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

4. Clean up.

Before you begin

To complete the steps demonstrated in this tutorial, you must first set up your project and environment.

Set up your project

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Vertex AI API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Vertex AI API.

   Enable the API

8. If you selected a project, make sure you have the Vertex AI user (roles/aiplatform.user) IAM role on the project.

Authenticate to Vertex AI

To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

1. Install the Google Cloud CLI.

2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

Import libraries

Install the Agent Development Kit and Vertex AI SDK:

pip install google-adk>=1.5.0
pip install google-cloud-aiplatform>=1.100.0

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. Only us-central1 is supported for Vertex AI Agent Engine Memory Bank.

Create your Vertex AI Agent Engine instance

To access Vertex AI Agent Engine Sessions and Vertex AI Agent Engine Memory Bank, you first need to create a Vertex AI Agent Engine instance. You don't need to deploy any code to start using Sessions and Memory Bank. Without code deployment, creating an Vertex AI Agent Engine instance should take a few seconds.

import vertexai

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

agent_engine = client.agent_engines.create()

Create your ADK agent

1. When developing your ADK agent, include a Memory tool, which controls when the memory service is used 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.

   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
   )
   

3. Create an ADK runner, which orchestrates the execution of your agents, tools, and callbacks.

   from google.adk.sessions import VertexAiSessionService
   
   # You can use any ADK session service.
   session_service = VertexAiSessionService(
       project_id="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)
   

   Replace the following:

   • APP_NAME: The name of your ADK app.

Interact with your agent

After defining your agent and setting up Sessions and 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:

   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:

   • 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}.

   session = await session_service.get_session(
       app_name=app_name,
       user_id="USER_ID",
       session_id=session.id
   )
   await memory_service.add_session_to_memory(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.

   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?
   

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 REST API.