The Agent Development Kit (ADK) connects agents to Agent Platform Memory Bank through
VertexAiMemoryBankService,
an implementation of the ADK
BaseMemoryService
interface. This document explains how to choose a memory callback and retrieval
tool, and how to connect the memory service in each ADK runtime.
To run a complete example first, see the Memory Bank quickstart with ADK.
Before you begin
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
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.
- Install ADK and the Agent Platform SDK:
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
- Create a Memory Bank instance in the Google Cloud console or with the Agent Platform SDK. On the Memory Bank page, click Link to an agent > Use with ADK for prefilled setup code. Skip this step if Agent Runtime creates the instance for you.
Required roles
To get the permissions that you need to create a Memory Bank instance and generate and retrieve memories, ask your administrator to grant you the following IAM roles on your project:
- Create or update a Memory Bank instance: Agent Platform User (`roles/aiplatform.user`)
- Read, write, or generate memories: Memory Bank User (`roles/aiplatform.memoryUser`)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
How ADK components work with Memory Bank
An ADK agent uses the following components to read and write memories:
| Component | Role | Required |
|---|---|---|
| Memory Bank instance | Stores and consolidates memories. | Yes |
VertexAiMemoryBankService |
Connects your agent to Memory Bank as the ADK memory service. | Yes |
| Session service | Stores conversation history. You can use any ADK session service. | Yes |
| Memory retrieval tool | Retrieves memories for the agent. See Retrieve memories with a tool. | To read memories |
| Memory generation callback | Sends conversation events to Memory Bank after the agent responds. See Generate memories with a callback. | To write memories |
ADK Runner or AdkApp |
Orchestrates the agent, services, tools, and callbacks. | Yes |
The following diagram shows how these components interact on each turn when an
agent uses PreloadMemoryTool and a memory callback:
Memory Bank scopes each memory to the user ID and app name that
run your agent, as {"user_id": USER_ID, "app_name": APP_NAME}. Only requests
with the same user ID and app name retrieve those memories.
Generate memories with a callback
A memory generation callback sends conversation events to Memory Bank. Memory Bank extracts memories from those events and consolidates them with existing memories. Choose a method based on how often you process events:
| Method | Events sent | When to use |
|---|---|---|
callback_context.add_events_to_memory |
A subset of events that you select | Recommended. Process events incrementally, for example after each turn. |
callback_context.add_session_to_memory |
All events in the session | Call once at the end of a session, so that the same events aren't processed more than once. |
The following example sends recent events after each agent response:
from google.adk.agents.callback_context import CallbackContext
async def generate_memories_callback(
callback_context: CallbackContext,
) -> None:
await callback_context.add_events_to_memory(
events=callback_context.session.events[-5:]
)
return None
To send the full session instead, call
await callback_context.add_session_to_memory() in a callback at the end of
the session.
By default, VertexAiMemoryBankService sends events by using event
ingestion. To wait until memory
generation finishes in tests or demos, pass
custom_metadata={"wait_for_completion": True} to add_events_to_memory.
Retrieve memories with a tool
A memory retrieval tool controls when the agent retrieves memories and how the memories enter the prompt. Choose one of the following tools:
| Tool | When memories are retrieved | When to use |
|---|---|---|
PreloadMemoryTool |
At the start of every turn. Memories are injected into the model request context before the current user turn. | Establish baseline context about the user on every turn. |
LoadMemoryTool |
When the model decides that memories are necessary to answer the query. | Let the model decide when memories are relevant. |
Custom FunctionTool |
When the model calls your tool, guided by the tool's description. | Give the agent instructions about when to retrieve memories. |
The following example creates an agent that uses PreloadMemoryTool and the
callback from the preceding section:
from google import adk
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
agent = adk.Agent(
model="gemini-3.5-flash",
name="stateful_agent",
instruction="You are a vehicle voice agent. Limit responses to 30 words.",
tools=[PreloadMemoryTool()],
after_agent_callback=generate_memories_callback,
)
To let the model decide when to retrieve memories, import LoadMemoryTool from
google.adk.tools.load_memory_tool and pass LoadMemoryTool() in tools.
To write a custom retrieval tool, call tool_context.search_memory from a
function tool:
from typing import Any
from google import adk
from google.adk.tools import FunctionTool, ToolContext
async def search_memories(query: str, tool_context: ToolContext) -> Any:
"""Query this tool when you need information about user preferences."""
return await tool_context.search_memory(query)
agent = adk.Agent(
model="gemini-3.5-flash",
name="stateful_agent",
instruction=(
"You are a vehicle voice agent. Before you change a setting, call "
"search_memories to look up the user's preferences. Limit responses "
"to 30 words."
),
tools=[FunctionTool(func=search_memories)],
after_agent_callback=generate_memories_callback,
)
Connect the memory service to your runtime
How you connect VertexAiMemoryBankService depends on where your agent
runs. Select your runtime:
Local runner
When you run your agent with adk.Runner, create the memory service and
pass it to the runner:
import asyncio
import os
from google import adk
from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import InMemorySessionService
from google.genai import types
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"
memory_service = VertexAiMemoryBankService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="MEMORY_BANK_ID",
)
# You can use any ADK session service. This example keeps sessions in memory.
# To persist conversation history, use VertexAiSessionService with a
# Sessions instance instead.
session_service = InMemorySessionService()
runner = adk.Runner(
agent=agent,
app_name="APP_NAME",
session_service=session_service,
memory_service=memory_service,
)
async def main() -> None:
session = await session_service.create_session(
app_name="APP_NAME",
user_id="USER_ID",
)
message = types.Content(
role="user", parts=[types.Part(text="Can you fix the temperature?")]
)
async for event in runner.run_async(
user_id="USER_ID",
session_id=session.id,
new_message=message,
):
if event.is_final_response() and event.content:
print(event.content.parts[0].text)
asyncio.run(main())
Replace the following:
- PROJECT_ID: Your Google Cloud project ID, for example
my-project. - LOCATION: Your location, for example
global. See the supported locations and global and multi-regional endpoints for Memory Bank. - MEMORY_BANK_ID: The Memory Bank instance ID,
for example
456inprojects/my-project/locations/us-central1/reasoningEngines/456. - APP_NAME: The ADK app name, for example
my_agent. Memory Bank includes the app name in the memory scope, so memories are isolated across apps. - USER_ID: An identifier for your user, for example
user-123. Memories generated from this session are scoped to this identifier.
Agent Runtime on Gemini Enterprise Agent Platform
When you deploy an ADK agent to Agent Runtime with the
ADK template
(AdkApp), the template uses VertexAiMemoryBankService by default. You can
create the Memory Bank instance and deploy the agent in one
step:
import asyncio
import agentplatform
from agentplatform.frameworks import AdkApp
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION",
)
adk_app = AdkApp(agent=agent)
# Create a resource with your agent deployed to Agent Runtime. The
# resource also includes an empty Memory Bank instance.
runtime_instance = client.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
async def main() -> None:
session = await runtime_instance.async_create_session(
user_id="USER_ID"
)
async for event in runtime_instance.async_stream_query(
user_id="USER_ID",
session_id=session.get("id"),
message="Can you fix the temperature?",
):
print(event)
asyncio.run(main())
To deploy the agent to an existing resource and keep the resource's
existing memories, call client.runtimes.update instead:
runtime_instance = client.runtimes.update(
name="RUNTIME_NAME",
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
When you run AdkApp locally, it uses InMemoryMemoryService by default.
To use Memory Bank locally, override the memory service:
from google.adk.memory import VertexAiMemoryBankService
def memory_bank_service_builder() -> VertexAiMemoryBankService:
return VertexAiMemoryBankService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="MEMORY_BANK_ID",
)
adk_app = AdkApp(
agent=agent,
memory_service_builder=memory_bank_service_builder,
)
Replace the following:
- PROJECT_ID: Your Google Cloud project ID, for example
my-project. - LOCATION: Your Agent Runtime region or multi-region, for
example
us-central1. Only standaloneVertexAiMemoryBankServiceinstances supportglobal, notclient.runtimes.create. See supported locations. - STAGING_BUCKET: The Cloud Storage bucket URI for staging
your Agent Runtime, for example
gs://my-staging-bucket. - USER_ID: An identifier for your user, for example
user-123. - RUNTIME_NAME: The resource name of the existing
Agent Runtime, in the format
projects/.../locations/.../reasoningEngines/.... - MEMORY_BANK_ID: The Memory Bank instance ID,
for example
456inprojects/my-project/locations/us-central1/reasoningEngines/456.
Cloud Run
To deploy your agent to Cloud Run, follow the ADK documentation and pass your Memory Bank instance as the memory service:
adk deploy cloud_run \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Replace MEMORY_BANK_ID with your Memory Bank
instance ID, for example 456. To test the deployed agent, see the
ADK Cloud Run deployment
documentation.
Google Kubernetes Engine (GKE)
To deploy your agent to GKE, follow the ADK documentation and pass your Memory Bank instance as the memory service:
adk deploy gke \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Replace MEMORY_BANK_ID with your Memory Bank
instance ID, for example 456. To test the deployed agent, see the Testing
your agent
section of the ADK GKE deployment
documentation.
ADK Web
ADK Web is a local browser interface for testing and inspecting your agent during development.
ADK Web reads your project and location from environment variables. Run the following commands in your terminal, from the directory that contains your agent folder:
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
adk web --memory_service_uri=agentengine://MEMORY_BANK_IDReplace the following:
- PROJECT_ID: Your Google Cloud project ID, for example
my-project. - LOCATION: Your location, for example
global. See the supported locations and global and multi-regional endpoints for Memory Bank. - MEMORY_BANK_ID: The Memory Bank instance ID,
for example
456.
Then open http://localhost:8000 in your browser. By default, ADK Web sets
the user ID to user. To use a different user ID, add the userId query
parameter, for example http://localhost:8000?userId=USER_ID.
Use a multi-regional Memory Bank with a regional runtime
By default, when you use Runtime with built-in
Memory Bank, your agent and Memory Bank are
deployed in the same region. To maintain one central Memory Bank
across regional deployments, you can pair a multi-regional
Memory Bank (such as us) with a regional runtime (such as
us-central1).
To use a multi-regional Memory Bank, override the default ADK memory service builder so that it points to the multi-region location and instance ID:
import agentplatform
from agentplatform.frameworks import AdkApp
from google.adk.memory import VertexAiMemoryBankService
# Create the Memory Bank instance in a multi-region location.
client_mb = agentplatform.Client(
project="PROJECT_ID",
location="us",
)
memory_bank = client_mb.memory_banks.create()
memory_bank_id = memory_bank.name.split("/")[-1]
# Point the memory service to the multi-regional instance.
def memory_bank_service_builder() -> VertexAiMemoryBankService:
return VertexAiMemoryBankService(
project="PROJECT_ID",
location="us",
agent_engine_id=memory_bank_id,
)
adk_app = AdkApp(
agent=agent,
memory_service_builder=memory_bank_service_builder,
)
# Deploy the runtime to a specific region.
client_runtime = agentplatform.Client(
project="PROJECT_ID",
location="us-central1",
)
runtime_instance = client_runtime.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
Replace the following:
- PROJECT_ID: Your Google Cloud project ID, for example
my-project. - STAGING_BUCKET: The Cloud Storage bucket URI for staging
your Agent Runtime, for example
gs://my-staging-bucket.
To delete these resources, delete the runtime and the multi-regional instance.
If you delete an instance right after a conversation, the request can fail with
a FAILED_PRECONDITION error while memory generation finishes. If that
happens, wait a minute and run the deletion again.
client_runtime.runtimes.delete(
name=runtime_instance.api_resource.name,
force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)