Generative AI Google Brain

agents-cloud-run-agents-with-memory-get-started-with-memory-for-adk-in-cloud-run

3 min read

Get started with Sessions and Memory Bank for ADK agents in Cloud Run

Source notebook

Repo path: agents/cloud_run/agents_with_memory/get_started_with_memory_for_adk_in_cloud_run.ipynb · Open on GitHub · intermediate

Builds an ADK weather agent with Vertex AI Sessions, Memory Bank, and Cloud Run deployment.

Summary

This notebook teaches how to give an ADK agent short-term session persistence and long-term memory using Vertex AI Agent Engine Sessions and Memory Bank. It registers an Agent Engine resource, wires VertexAiSessionService and VertexAiMemoryBankService into an ADK Runner, saves sessions to memory after each turn, and deploys the agent to Cloud Run with memory and session service URIs.

Key code patterns

Vertex AI ADK environment

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = PROJECT_ID
os.environ["GOOGLE_CLOUD_LOCATION"] = LOCATION
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

ADK is configured to use Vertex AI in the selected Google Cloud project and location.

Agent Engine memory services

agent_engine = client.agent_engines.create(config={"display_name": AGENT_NAME, "context_spec": {"memory_bank_config": {"generation_config": {"model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"}}}}})
agent_engine_id = agent_engine.api_resource.name.split("/")[-1]
session_service = VertexAiSessionService(project=PROJECT_ID, location=LOCATION, agent_engine_id=agent_engine_id)
memory_service = VertexAiMemoryBankService(project=PROJECT_ID, location=LOCATION, agent_engine_id=agent_engine_id)

The Agent Engine resource anchors managed session storage and Memory Bank for the agent.

Persist turns to Memory Bank

async def add_session_to_memory(callback_context):
    if hasattr(callback_context, "_invocation_context"):
        invocation_context = callback_context._invocation_context
        if invocation_context.memory_service:
            await invocation_context.memory_service.add_session_to_memory(invocation_context.session)

The after-agent callback sends completed session content to the long-term memory service.

Memory-aware ADK agent

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    tools=[get_weather, PreloadMemoryTool()],
    after_agent_callback=add_session_to_memory,
)

PreloadMemoryTool retrieves relevant memories automatically at the beginning of each turn.

Cloud Run deployment with memory

adk deploy cloud_run --project {PROJECT_ID} --region {LOCATION} \
  --session_service_uri=agentengine://{agent_engine_id} \
  --memory_service_uri=agentengine://{agent_engine_id} \
  --app_name {AGENT_NAME} --with_ui .

The deployment passes Agent Engine-backed session and memory services into the Cloud Run agent.

Models & APIs used

  • Models: gemini-2.5-flash
  • APIs / services: Vertex AI, Vertex AI Agent Engine Sessions, Vertex AI Agent Engine Memory Bank, Cloud Run, Artifact Registry, Cloud Build
  • SDKs / libraries: google-adk, google-cloud-aiplatform, vertexai, google-genai

When to use this

Use this pattern when an ADK agent deployed on Cloud Run needs persistent chat sessions and cross-session user memory.

Gotchas & caveats

  • PROJECT_ID must be set and Vertex AI, Cloud Run, Artifact Registry, and Cloud Build APIs must be enabled.
  • The notebook may require gcloud login and ADC setup before running cloud commands.
  • Default InMemorySessionService loses session state on runner shutdown and does not work reliably across multiple Cloud Run instances.
  • Memory Bank only stores extracted meaningful information, so not every conversation creates a memory.
  • The callback checks for the private _invocation_context attribute before saving memory.
  • The sample uses —allow-unauthenticated for easier testing, while the notebook recommends authenticated Cloud Run services for production.
  • Resources should be deleted after testing to avoid unexpected costs.

Best practices

  • Store production ADK session data outside the agent runtime.
  • Use VertexAISessionService for scalable managed session storage.
  • Provide a memory tool on the Agent and a memory_service on the Runner.
  • Use a session_service on the Runner when using managed sessions.
  • Create new sessions during testing to prove long-term memory carries across sessions.
  • Configure Cloud Run authentication for production instead of —allow-unauthenticated.
  • Clean up Agent Engine and Cloud Run resources when finished.

Graph View

Backlinks