Runner, App, and Sessions
Runner / InMemoryRunner, the App container, session services, RunConfig, and state scopes.
Verified against google-adk 2.13.0 (google/adk/runners.py, google/adk/apps/app.py, google/adk/sessions/), checked 2026-11-19. The examples were run against a stub model that stands in for Gemini. MongoDbSessionService was exercised for create, append and get against a Mongo mock, not a live MongoDB.
The Runner glues an agent/workflow to the three per-session services (session, memory, artifact) plus a credential service and plugin manager. App is the container that bundles the root agent with app-wide settings.
Minimal example (in-memory)
Section titled “Minimal example (in-memory)”import asynciofrom google.adk.agents import LlmAgentfrom google.adk.runners import InMemoryRunnerfrom google.genai import types
agent = LlmAgent(name="chat", model="gemini-3.8-flash", instruction="Be concise.")
async def main(): runner = InMemoryRunner(agent=agent, app_name="demo") session = await runner.session_service.create_session( app_name="demo", user_id="u1", session_id="s1" ) async for event in runner.run_async( user_id="u1", session_id=session.id, new_message=types.Content(role="user", parts=[types.Part(text="Hi")]), ): if event.content: for part in event.content.parts: if part.text: print(event.author, "→", part.text) await runner.close()
asyncio.run(main())InMemoryRunner subclasses Runner and wires in InMemorySessionService + InMemoryMemoryService + InMemoryArtifactService (runners.py).
The App container
Section titled “The App container”from google.adk.apps import App, ResumabilityConfigfrom google.adk.apps.app import EventsCompactionConfig # not re-exported from google.adk.appsfrom google.adk.plugins import LoggingPluginfrom google.adk.agents.context_cache_config import ContextCacheConfig
app = App( name="demo", root_agent=agent, # an LlmAgent or a Workflow plugins=[LoggingPlugin()], resumability_config=ResumabilityConfig(is_resumable=True), events_compaction_config=EventsCompactionConfig( compaction_interval=10, overlap_size=2, token_threshold=50_000, event_retention_size=50, ), context_cache_config=ContextCacheConfig(cache_intervals=10), # optional, for explicit Gemini cache)| Field | Default | Purpose |
|---|---|---|
name | required | Must match ^[a-zA-Z][a-zA-Z0-9_-]*$ (a letter first; letters, digits, _, -); "user" is reserved. Violations raise ValueError |
root_agent | required | BaseAgent or BaseNode (e.g. a Workflow) |
plugins | [] | App-wide plugins (ordered) |
events_compaction_config | None | Sliding-window event compaction |
context_cache_config | None | Gemini context cache config, applied to every LLM call |
resumability_config | None | Enables pause/resume around long-running tools |
Put plugins on the App: Runner(plugins=...) still works but emits a DeprecationWarning. Likewise LlmAgent.global_instruction is deprecated in favour of App(plugins=[GlobalInstructionPlugin(...)]).
Runner constructor
Section titled “Runner constructor”from google.adk.runners import Runnerfrom google.adk.sessions import DatabaseSessionService
runner = Runner( app=app, # preferred session_service=DatabaseSessionService(db_url="sqlite+aiosqlite:///./adk.db"), memory_service=memory_service, # optional artifact_service=artifact_service, # optional credential_service=credential_service, # optional auto_create_session=False, plugin_close_timeout=5.0,)Exactly one of app=, agent=, or node= is required (runners.py). plugins= on the runner is deprecated — pass them through App(plugins=[...]) instead. auto_create_session=True is a convenience flag — when the session service returns None, the runner creates one on the fly; otherwise it raises SessionNotFoundError with an app-name alignment hint.
Key methods
Section titled “Key methods”| Method | Purpose |
|---|---|
async run_async(*, user_id, session_id, new_message=None, invocation_id=None, run_config=None, state_delta=None, yield_user_message=False, abort_signal=None) | Primary entry point. Yields Events. abort_signal (an asyncio.Event, 2.11.0) stops the run when set |
run(...) | Sync wrapper — starts a background thread. For local testing only. |
async run_live(*, live_request_queue, user_id=None, session_id=None, run_config=None, session=None) | Bidi streaming (audio/video). Experimental. |
async run_debug(user_messages, *, user_id="debug_user_id", session_id="debug_session_id", run_config=None, quiet=False, verbose=False) | Quick REPL-style helper. Returns a list of events. |
async rewind_async(*, user_id, session_id, rewind_before_invocation_id, run_config=None) | Rewinds the session state and artifacts to before the given invocation. |
async close() | Closes toolsets and plugins. Call it on shutdown (or use async with runner:). |
All run_* methods work with asyncio. Wire async with Runner(...) as runner: for auto-cleanup.
RunConfig
Section titled “RunConfig”Passed to each run_async/run_live call (agents/run_config.py). Notable fields:
| Field | Default | Notes |
|---|---|---|
streaming_mode | StreamingMode.NONE | SSE for HTTP streaming, BIDI for live API |
max_llm_calls | 500 | Hard cap per run (env: ADK_MAX_LLM_CALLS). <=0 disables |
service_tier | None | ServiceTier.FLEX, STANDARD, PRIORITY or DEFERRED; only reaches Gemini models on the Interactions API. DEFERRED is incompatible with StreamingMode.SSE |
labels | None | dict[str, str] forwarded to Gemini billing/attribution (e.g. {"team": "growth"}) |
http_options | None | types.HttpOptions — per-invocation timeout/header overrides (ms units for timeout) |
custom_metadata | None | Merged into every emitted event; useful for APM trace correlation |
telemetry | None | TelemetryConfig — overrides process-global OTel env vars for this invocation |
model_input_context | None | list[types.Content] injected into LLM input for this invocation; not saved to session history |
include_thoughts_from_other_agents | False | When True, sub-agent <thinking> blocks are passed to the coordinator’s context |
response_modalities | None | e.g. ["TEXT"] or ["AUDIO"] for live |
speech_config / avatar_config | None | Live mode TTS / avatar |
output_audio_transcription / input_audio_transcription | AudioTranscriptionConfig() | Live transcription |
context_window_compression | None | Live-mode server-side context compression |
get_session_config | None | Passes num_recent_events / after_timestamp through to the session service on load |
support_cfc | False | Experimental compositional function calling over the Live API. Only gemini-2* model names are accepted; any other model raises ValueError, so it is of little use for new projects |
tool_thread_pool_config | None | Runs tools in a thread pool during live mode |
save_live_blob | False | Persist audio/video frames to artifact service |
save_input_blobs_as_artifacts | False | Deprecated → SaveFilesAsArtifactsPlugin |
save_live_audio | False | Deprecated → save_live_blob |
from google.adk.agents.run_config import RunConfig, StreamingModefrom google.adk.sessions.base_session_service import GetSessionConfig
cfg = RunConfig( streaming_mode=StreamingMode.SSE, max_llm_calls=50, get_session_config=GetSessionConfig(num_recent_events=20),)ServiceTier.DEFERRED — off-peak execution (2.10.0+)
Section titled “ServiceTier.DEFERRED — off-peak execution (2.10.0+)”ServiceTier.DEFERRED queues each model call to run on off-peak capacity instead of returning results immediately. ADK waits for the queued result before yielding, so each tool-calling agent that calls the LLM multiple times queues once per LLM call rather than once per full run.
Key constraints (source-verified in run_config.py):
- Cannot be combined with
StreamingMode.SSE— a deferred request returns an interaction ID, not a result, so there is nothing to stream. ADK raisesValueErroratRunConfigconstruction time. ManagedAgentignoresservice_tier— it callsinteractions.createfrom its own execution loop and never reads this field.- Only honoured by
Geminimodels that use the Interactions API (Gemini(model=..., use_interactions_api=True)). Models on thegenerate_contentpath, which is the default, and non-Gemini models such asLiteLlmignoreservice_tiersilently.
from google.adk.agents.run_config import RunConfig, StreamingModefrom google.adk.models import ServiceTier
# Off-peak — useful for batch jobs and background processing# ADK blocks on the queue result; total latency is queue time + compute time.deferred_cfg = RunConfig( service_tier=ServiceTier.DEFERRED, max_llm_calls=200, labels={"job": "nightly-batch", "cost_center": "analytics"},)
# Combining with SSE raises ValueError at construction:# RunConfig(service_tier=ServiceTier.DEFERRED, streaming_mode=StreamingMode.SSE)# → ValueError: "service_tier='deferred' cannot be used with StreamingMode.SSE"
# Correct approach: use deferred without streamingasync def run_batch_job(runner, user_id: str, session_id: str, messages: list): from google.genai import types results = [] for text in messages: msg = types.Content(role="user", parts=[types.Part(text=text)]) events = [] async for event in runner.run_async( user_id=user_id, session_id=session_id, new_message=msg, run_config=deferred_cfg, ): if event.is_final_response() and event.content: events.append(event) results.append(events) return resultsmodel_input_context — transient per-invocation context
Section titled “model_input_context — transient per-invocation context”Inject additional context into every LLM call within a Runner invocation without persisting it to session history. Because RunConfig is read on each round, a tool-calling run with multiple model calls receives this context on every round, not just the first. Useful for passing dynamic reference data (retrieved chunks, user profile) that should influence the response but not pollute the conversation history.
from google.adk.agents.run_config import RunConfigfrom google.genai import types
# Simulate per-turn RAG: inject retrieved documents as contextretrieved_docs = [ types.Content( role="user", parts=[types.Part(text="Reference: Q3 revenue was $4.2M, up 18% YoY.")], )]
cfg = RunConfig( model_input_context=retrieved_docs, # not saved to session; only for this call max_llm_calls=10,)
# The agent sees the retrieved docs but they do not appear in future turnsasync for event in runner.run_async( user_id="u1", session_id="s1", new_message=types.Content( role="user", parts=[types.Part(text="Summarise our Q3 performance.")] ), run_config=cfg,): if event.is_final_response() and event.content: print(event.content.parts[0].text)SSE streaming — event filtering
Section titled “SSE streaming — event filtering”StreamingMode.SSE yields both partial (streaming chunks) and final events. Without care you display the text twice. Three strategies from run_config.py:
from google.adk.agents.run_config import RunConfig, StreamingMode
cfg = RunConfig(streaming_mode=StreamingMode.SSE)
# ── Strategy 1: typewriter effect (show partials, skip final text) ──────────async for event in runner.run_async(..., run_config=cfg): if event.partial and event.content: parts = event.content.parts or [] has_text = any(p.text for p in parts) has_fc = any(p.function_call for p in parts) if has_text and not has_fc: print("".join(p.text or "" for p in parts), end="", flush=True) elif not event.partial and event.get_function_calls(): for fc in event.get_function_calls(): print(f"\n[tool] {fc.name}({fc.args})")
# ── Strategy 2: final-only (no streaming effect) ────────────────────────────async for event in runner.run_async(..., run_config=cfg): if not event.partial and event.is_final_response() and event.content: print("".join(p.text or "" for p in event.content.parts or []))
# ── Strategy 3: track what was already streamed ─────────────────────────────streamed = ""async for event in runner.run_async(..., run_config=cfg): if event.partial and event.content: chunk = "".join(p.text or "" for p in event.content.parts or []) print(chunk, end="", flush=True) streamed += chunk elif not event.partial and event.content: final = "".join(p.text or "" for p in event.content.parts or []) if final != streamed: print(final) # only if the final has content we didn't stream yetToolThreadPoolConfig — live mode concurrency
Section titled “ToolThreadPoolConfig — live mode concurrency”In live mode (run_live) tools run in the event loop by default. Set tool_thread_pool_config to run them in a thread pool, keeping the loop responsive to audio/video interrupts:
from google.adk.agents.run_config import RunConfig, ToolThreadPoolConfig
cfg = RunConfig( tool_thread_pool_config=ToolThreadPoolConfig(max_workers=8), save_live_blob=True, # persist audio/video frames to artifact service)# Note: thread pool helps with blocking I/O (network, DB, file); it does NOT# provide parallelism for pure-Python CPU work (GIL still applies).The full RunConfig — every field in one runnable example
Section titled “The full RunConfig — every field in one runnable example”Source-verified against google.adk.agents.run_config (first verified in 2.7.1; re-checked against 2.13.0). Every field is optional; the example below sets each one at least once so you can see the exact call site and type. Copy-paste-delete to build your own.
from google.genai import typesfrom google.adk.agents.run_config import ( RunConfig, StreamingMode, ToolThreadPoolConfig,)from google.adk.sessions.base_session_service import GetSessionConfigfrom google.adk.telemetry.context import TelemetryConfig
cfg = RunConfig( # ── Streaming ──────────────────────────────────────────────────────────── streaming_mode=StreamingMode.SSE, # NONE | SSE | BIDI max_llm_calls=200, # hard cap; <=0 disables
# ── Attribution & tracing ──────────────────────────────────────────────── labels={"team": "growth", "cost_center": "b2b"}, # forwarded to Gemini billing custom_metadata={"trace_id": "abc-123"}, # merged into every Event http_options=types.HttpOptions(timeout=30_000), # 30 s per LLM call (ms!) telemetry=TelemetryConfig(), # OpenTelemetry span/attribute config
# ── Live-mode audio / video ────────────────────────────────────────────── # NOTE: Gemini's live API accepts one modality per session. Pick AUDIO # OR TEXT (not both) — combining them causes the connection to be rejected. response_modalities=[types.Modality.AUDIO], speech_config=types.SpeechConfig( voice_config=types.VoiceConfig( prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Puck") ), ), output_audio_transcription=types.AudioTranscriptionConfig(), input_audio_transcription=types.AudioTranscriptionConfig(), realtime_input_config=types.RealtimeInputConfig(), # When True the CLIENT must send activity_start / activity_end (types.ActivityStart / # types.ActivityEnd) to demarcate each user turn — the model will NOT auto-detect # turn-end. Leave False (or unset) unless your live client explicitly emits VAD signals. explicit_vad_signal=False, save_live_blob=True, # persist audio/video to artifact_service save_live_audio=True, # keep raw audio bytes (in addition to blobs) save_input_blobs_as_artifacts=True, # persist user-uploaded blobs alongside events avatar_config=types.AvatarConfig(), # live-mode virtual avatar rendering translation_config=types.TranslationConfig(), # live-mode translation of user/agent audio enable_affective_dialog=True, # emotion-aware responses proactivity=types.ProactivityConfig(), # allow model-initiated turns
# ── Session handling ───────────────────────────────────────────────────── session_resumption=types.SessionResumptionConfig(), # transparent resumption history_config=types.HistoryConfig(), # what history flows to model context_window_compression=types.ContextWindowCompressionConfig(), get_session_config=GetSessionConfig(num_recent_events=50),
# ── Tool concurrency (live mode only) ──────────────────────────────────── tool_thread_pool_config=ToolThreadPoolConfig(max_workers=4),
# ── Advanced Gemini features ───────────────────────────────────────────── support_cfc=False, # experimental compositional function calling include_thoughts_from_other_agents=False, # share <thinking> across sub-agents model_input_context=None, # pre-seed model input with types.Content list)custom_metadata is a first-class tracing hook. Verified in runners.py: every emitted Event gets event.custom_metadata = self.custom_metadata merged in before yielding. Use it to correlate agent turns with your APM span IDs without wrapping the runner:
import uuid
trace_id = str(uuid.uuid4())cfg = RunConfig(custom_metadata={"trace_id": trace_id, "surface": "web"})
async for event in runner.run_async(user_id="u1", session_id="s1", new_message=msg, run_config=cfg): # event.custom_metadata → {"trace_id": "…", "surface": "web"} logger.info("agent_event", extra=event.custom_metadata)get_session_config — control what history the session service loads. By default the session service returns every event ever recorded. On a long-lived chat that’s expensive both in DB round-trips and in prompt tokens. GetSessionConfig(num_recent_events=N) tells the service to fetch only the last N; after_timestamp (float, unix seconds) is an alternative window.
Session services
Section titled “Session services”All subclass BaseSessionService and expose create_session, get_session, list_sessions, delete_session, append_event.
| Service | Import | Storage | Notes |
|---|---|---|---|
InMemorySessionService | google.adk.sessions | Python dict | Dev/testing |
DatabaseSessionService(db_url) | google.adk.sessions (lazy) | SQLAlchemy URL with an async driver | pip install "google-adk[db]" plus the driver: aiosqlite (bundled), asyncpg, aiomysql, asyncmy |
SqliteSessionService | google.adk.sessions.sqlite_session_service | SQLite file (async) | Zero-dep alternative to DatabaseSessionService for SQLite only |
MongoDbSessionService(*, database_name, connection_string=None, mongo_client=None, ...) | google.adk.integrations.mongodb | MongoDB collections for sessions, events, app state and user state (experimental, added in 2.13.0) | pip install "google-adk[mongodb]"; replicas of one runner can share sessions. Add timeoutMS=<ms> to the connection string to bound each operation; collection names and ensure_indexes are keyword options |
VertexAiSessionService(project, location, agent_engine_id, *, express_mode_api_key=None) | google.adk.sessions | Vertex AI Agent Engine | Production-ready, scales with Agent Engine |
from google.adk.sessions import DatabaseSessionService, VertexAiSessionService
# Postgressvc = DatabaseSessionService(db_url="postgresql+asyncpg://user:pass@host/db")
# Vertex AIsvc = VertexAiSessionService( project="my-gcp-project", location="us-central1", agent_engine_id="1234567890",)VertexAiSessionService validates session IDs against ^[A-Za-z0-9_-]+$ and raises ValueError otherwise (this blocks path injection into the resource URL); it also accepts a full projects/.../reasoningEngines/{id}/sessions/{sid} resource name as session_id and checks that the engine ID matches. express_mode_api_key is only for Vertex AI Express Mode.
DatabaseSessionService.create_session/get_session run the underlying SQL inside an async session factory; Postgres and MySQL use row-level locking for concurrent append_event (database_session_service.py).
DatabaseSessionService
Section titled “DatabaseSessionService”DatabaseSessionService(db_url, **kwargs) is the recommended persistent session backend for self-hosted deployments. It uses SQLAlchemy 2.x async with a per-session asyncio lock to serialise concurrent append_event calls within the same process.
Supported backends and URL format
Section titled “Supported backends and URL format”from google.adk.sessions import DatabaseSessionService
# ── SQLite (local dev, single-process) ────────────────────────────────────────# aiosqlite is bundled with google-adk; no extra driver install neededsvc = DatabaseSessionService(db_url="sqlite+aiosqlite:///./sessions.db")
# In-memory SQLite for tests (data lost on close)svc_mem = DatabaseSessionService(db_url="sqlite+aiosqlite:///:memory:")
# ── PostgreSQL ────────────────────────────────────────────────────────────────# pip install asyncpgsvc = DatabaseSessionService(db_url="postgresql+asyncpg://user:pass@localhost:5432/adk")
# With connection pool tuningsvc = DatabaseSessionService( db_url="postgresql+asyncpg://user:pass@pg-host/adk", pool_size=10, # max persistent connections max_overflow=5, # additional connections when pool is full pool_recycle=3600, # close connections older than 1 h echo=False, # set True to log every SQL statement)
# ── MySQL / MariaDB ───────────────────────────────────────────────────────────# pip install aiomysqlsvc = DatabaseSessionService(db_url="mysql+aiomysql://user:pass@localhost:3306/adk")Cloud Spanner does not work here in 2.13.0: the sqlalchemy-spanner dialect that the db extra installs is synchronous, and a spanner+spanner:///projects/... URL fails with the synchronous-driver ValueError. For managed storage on Google Cloud, use Cloud SQL (PostgreSQL or MySQL) or VertexAiSessionService.
**kwargs are forwarded directly to create_async_engine — use them for pool parameters, SSL settings, etc. The URL must name an async driver: a plain sqlite:///... or postgresql://... URL raises ValueError: ... resolves to a synchronous driver. (The adk CLI’s --session_service_uri is different: there sqlite:///path.db selects SqliteSessionService.)
Schema and tables
Section titled “Schema and tables”ADK creates its tables on first use (or when you call await svc.prepare_tables(), which is worth doing at start-up). There are two schema versions; new databases get V1, recorded in an adk_internal_metadata table alongside these four:
| Table | Purpose |
|---|---|
sessions | One row per session — app_name, user_id, id, update_time, update_storage_marker, plus serialised state (session-scoped only) |
app_states | One row per (app_name) — serialised app_state dict |
user_states | One row per (app_name, user_id) — serialised user_state dict |
events | One row per event — foreign-keyed to sessions, stores event_data JSON, invocation_id, timestamp, branch, etc. |
State scopes are split across tables to enable efficient app- and user-level updates without touching every session row.
CRUD examples
Section titled “CRUD examples”import asynciofrom google.adk.sessions import DatabaseSessionServicefrom google.adk.sessions.base_session_service import GetSessionConfigfrom google.genai import types
svc = DatabaseSessionService(db_url="sqlite+aiosqlite:///./demo.db")
async def main(): # ── create_session ──────────────────────────────────────────────────────── session = await svc.create_session( app_name="myapp", user_id="u1", state={ "last_city": "London", # no prefix: session-scoped "user:lang": "en", # user-scoped (persists across sessions) "app:feature_x": True, # app-scoped (all users see this) }, session_id="s1", # omit for auto-generated UUID ) print(session.id, session.state)
# ── get_session ────────────────────────────────────────────────────────── loaded = await svc.get_session( app_name="myapp", user_id="u1", session_id="s1", config=GetSessionConfig( num_recent_events=10, # load only the last 10 events # after_timestamp=1_747_000_000.0, # or events after a timestamp ), )
# ── list_sessions ───────────────────────────────────────────────────────── response = await svc.list_sessions(app_name="myapp", user_id="u1") for s in response.sessions: print(s.id, s.last_update_time)
# ── delete_session ──────────────────────────────────────────────────────── await svc.delete_session(app_name="myapp", user_id="u1", session_id="s1")
asyncio.run(main())Concurrent writes and per-session locking
Section titled “Concurrent writes and per-session locking”append_event serialises concurrent writes within the same process using a per-session asyncio.Lock. Each unique (app_name, user_id, session_id) tuple gets its own lock that is reference-counted and removed when no longer needed.
import asynciofrom google.adk.sessions import DatabaseSessionServicefrom google.adk.events.event import Eventfrom google.genai import types
svc = DatabaseSessionService(db_url="postgresql+asyncpg://user:pass@host/adk")
async def concurrent_append_demo(): session = await svc.create_session(app_name="myapp", user_id="u1")
# Concurrent appends are safe within the same process. # Different processes (or containers) are serialised by the DB # — Postgres/MySQL use FOR UPDATE row-level locking. event = Event( invocation_id="inv-001", author="user", content=types.Content(role="user", parts=[types.Part(text="Hello")]), ) appended = await svc.append_event(session=session, event=event) print(appended.id, appended.timestamp)Multi-process note: For multi-process or multi-container deployments, use PostgreSQL or MySQL — these dialects use
SELECT ... FOR UPDATErow-level locking on the session row when detected via_supports_row_level_locking(). SQLite is single-writer by design; run only one process against the same SQLite file.
Stale-session detection
Section titled “Stale-session detection”append_event compares the in-memory session.update_storage_marker against the value persisted in the DB. If another process has modified the session since it was loaded, a ValueError is raised:
ValueError: The session has been modified in storage since it was loaded.Please reload the session before appending more events.Handle this by reloading the session and replaying:
from google.adk.sessions import DatabaseSessionServicefrom google.adk.events.event import Event
async def safe_append(svc: DatabaseSessionService, session, event: Event): """Append an event, reloading the session once if stale.""" try: return await svc.append_event(session=session, event=event) except ValueError as exc: if "modified in storage" in str(exc): fresh = await svc.get_session( app_name=session.app_name, user_id=session.user_id, session_id=session.id, ) return await svc.append_event(session=fresh, event=event) raiseSchema migration (V0 → V1)
Section titled “Schema migration (V0 → V1)”ADK detects the schema version from the existing tables. A database created by an older release (V0 schema, one column per event field) is not migrated automatically: ADK keeps using the V0 tables and logs a warning that some event fields are not stored. Migrate it with the CLI, which copies into a new database:
adk migrate session \ --source_db_url "sqlite:///./sessions.db" \ --dest_db_url "sqlite:///./sessions_v1.db"Then point the service at the new database. Back up first; --allow_unsafe_unpickling is only for trusted legacy databases that stored pickled values.
Production setup with Runner
Section titled “Production setup with Runner”from google.adk.apps import Appfrom google.adk.runners import Runnerfrom google.adk.sessions import DatabaseSessionServicefrom google.adk.artifacts import GcsArtifactServicefrom google.adk.memory import VertexAiMemoryBankService
app = App(name="prod_app", root_agent=agent)
runner = Runner( app=app, session_service=DatabaseSessionService( db_url="postgresql+asyncpg://adk_user:${PG_PASSWORD}@pg-host:5432/adk", pool_size=10, max_overflow=5, ), artifact_service=GcsArtifactService(bucket_name="my-adk-artifacts"), memory_service=VertexAiMemoryBankService( project="my-gcp-project", location="us-central1", agent_engine_id="1234567890", ),)
# Always clean up — closes the connection poolasync with runner: ...SqliteSessionService
Section titled “SqliteSessionService”SqliteSessionService(db_path) is a lighter-weight alternative to DatabaseSessionService for pure SQLite use. It uses aiosqlite directly (bundled with google-adk) instead of SQLAlchemy, making it a zero-extra-dependency choice.
Constructor
Section titled “Constructor”from google.adk.sessions.sqlite_session_service import SqliteSessionService
# ── File path (absolute or relative) ─────────────────────────────────────────svc = SqliteSessionService("sessions.db")svc = SqliteSessionService("/var/data/adk/sessions.db")
# ── SQLAlchemy-style URL (also accepted) ──────────────────────────────────────svc = SqliteSessionService("sqlite:///sessions.db") # relativesvc = SqliteSessionService("sqlite:////abs/path/sessions.db") # absolute
# ── In-memory SQLite for tests ────────────────────────────────────────────────svc = SqliteSessionService(":memory:")Path parsing logic (verified sqlite_session_service.py:_parse_db_path):
- URLs starting with
sqlite:///→ strips the prefix, uses the trailing path. - Bare paths (
/pathor./path) → used directly. :memory:→ in-memory SQLite (no file created).
Schema
Section titled “Schema”SqliteSessionService creates four tables on first use:
-- App-wide shared stateCREATE TABLE app_states ( app_name TEXT, state TEXT, -- JSON update_time REAL, PRIMARY KEY (app_name));
-- User-wide state (spans all sessions for a user)CREATE TABLE user_states ( app_name TEXT, user_id TEXT, state TEXT, -- JSON update_time REAL, PRIMARY KEY (app_name, user_id));
-- Session metadata + session-scoped stateCREATE TABLE sessions ( app_name TEXT, user_id TEXT, id TEXT, state TEXT, -- JSON (session-scoped only) create_time REAL, update_time REAL, PRIMARY KEY (app_name, user_id, id));
-- Events (FK to sessions)CREATE TABLE events ( id TEXT, app_name TEXT, user_id TEXT, session_id TEXT, invocation_id TEXT, timestamp REAL, event_data TEXT, -- JSON serialised Event FOREIGN KEY (app_name, user_id, session_id) REFERENCES sessions(app_name, user_id, id));State is merged using SQLite’s native json_patch() function for atomic partial updates.
Full usage example
Section titled “Full usage example”import asynciofrom google.adk.agents import LlmAgentfrom google.adk.apps import Appfrom google.adk.runners import Runnerfrom google.adk.sessions.sqlite_session_service import SqliteSessionServicefrom google.adk.sessions.base_session_service import GetSessionConfigfrom google.genai import types
agent = LlmAgent(name="chat", model="gemini-3.8-flash", instruction="Be helpful.")app = App(name="chatbot", root_agent=agent)
async def main(): svc = SqliteSessionService("conversations.db") runner = Runner(app=app, session_service=svc)
# Create a session with mixed-scope state session = await svc.create_session( app_name="chatbot", user_id="alice", state={ "user:preferred_language": "en", # user-scoped → survives session deletion "greeting_shown": False, # session-scoped }, )
# Run a turn async for event in runner.run_async( user_id="alice", session_id=session.id, new_message=types.Content(role="user", parts=[types.Part(text="Hello!")]), ): if event.is_final_response() and event.content: print("Agent:", "".join(p.text or "" for p in event.content.parts))
# Load session with only the 5 most-recent events recent = await svc.get_session( app_name="chatbot", user_id="alice", session_id=session.id, config=GetSessionConfig(num_recent_events=5), ) print(f"Events loaded: {len(recent.events)}")
# Inspect state scopes print("Session state:", recent.state.get("greeting_shown")) print("User lang:", recent.state.get("user:preferred_language"))
# Delete the session (user-scoped state persists) await svc.delete_session( app_name="chatbot", user_id="alice", session_id=session.id )
# Create a new session — user:preferred_language is still there new_session = await svc.create_session( app_name="chatbot", user_id="alice" ) print("Lang still set:", new_session.state.get("user:preferred_language")) # "en"
await runner.close()
asyncio.run(main())State scopes — what survives deletion
Section titled “State scopes — what survives deletion”| State key prefix | Survives delete_session? | Scope |
|---|---|---|
| (none) | No — lost when session is deleted | This session only |
user: | Yes — stored in user_states table | All sessions of this user in this app |
app: | Yes — stored in app_states table | All sessions, all users in this app |
temp: | No — never persisted at all | Current invocation only |
Migration detection
Section titled “Migration detection”SqliteSessionService raises a RuntimeError at construction if the file was written by DatabaseSessionService’s SQLAlchemy schema. The message gives the conversion command:
python -m google.adk.sessions.migration.migrate_from_sqlalchemy_sqlite \ --source_db_path sessions.db --dest_db_path sessions.db.newThen back up the original and rename the new file into place.
Session state
Section titled “Session state”Access via ctx.state in callbacks and tools. State is a dict-like object with three reserved prefixes (sessions/state.py):
| Prefix | Lifetime | Example |
|---|---|---|
| (none) | Session | ctx.state["last_query"] = "..." |
app: | All sessions for the app | ctx.state["app:feature_flag"] = True |
user: | All sessions for that user | ctx.state["user:preferred_language"] = "en" |
temp: | Current invocation only (stripped before persist) | ctx.state["temp:scratch"] = [...] |
Declare a Pydantic schema on the Workflow (state_schema=) to validate mutations at runtime. Reserved prefixes bypass validation.
Context caching (ContextCacheConfig)
Section titled “Context caching (ContextCacheConfig)”ContextCacheConfig enables Gemini’s server-side context caching for all LlmAgents in an App. When active, ADK caches the system instruction + static tools prefix in Gemini’s cache after the first call and reuses it for up to cache_intervals subsequent invocations. Cached tokens are billed at a reduced rate.
from google.adk.apps import Appfrom google.adk.agents.context_cache_config import ContextCacheConfigfrom google.adk.runners import Runnerfrom google.adk.sessions import DatabaseSessionService
app = App( name="cached_app", root_agent=agent, context_cache_config=ContextCacheConfig( cache_intervals=20, # reuse the same cache for up to 20 invocations ttl_seconds=3600, # 1-hour TTL on the cache entry min_tokens=1000, # only cache requests with >= 1000 estimated tokens ),)
runner = Runner( app=app, session_service=DatabaseSessionService(db_url="sqlite+aiosqlite:///./adk.db"),)Fields (from agents/context_cache_config.py):
| Field | Default | Constraints | Purpose |
|---|---|---|---|
cache_intervals | 10 | 1–100 | Max invocations before the cache is refreshed |
ttl_seconds | 1800 (30 min) | > 0 | How long the cache entry lives in Gemini |
min_tokens | 0 | ≥ 0 | Minimum estimated request tokens to bother caching |
When to use:
- Long system instructions (> 1 k tokens) that rarely change
- Large tool schemas registered on the agent
- High-frequency, short user messages (chat, Q&A)
Stability:
ContextCacheConfigwas experimental up to 2.12.0 and is stable from 2.13.0, so it no longer logs a warning when used. It only works with Gemini models that support context caching; check the Gemini docs for supported model versions.
ContextCacheConfig — the create_http_options timeout knob
Section titled “ContextCacheConfig — the create_http_options timeout knob”Source-verified against google.adk.agents.context_cache_config (first verified in 2.7.1; re-checked against 2.13.0). create_http_options is often overlooked but essential in production: when Gemini’s CachedContent.create() call is slow (network hiccup, quota spike), your first request of a new session would otherwise stall waiting for the cache to be created. Setting a timeout tells ADK to give up on cache creation and just serve the request uncached rather than pinning the request.
from google.genai import typesfrom google.adk.agents.context_cache_config import ContextCacheConfig
cache_cfg = ContextCacheConfig( cache_intervals=25, # up to 25 invocations reuse the same cache ttl_seconds=3600, # 1-hour TTL — Gemini also enforces its own model max min_tokens=2048, # never bother caching prefixes under 2 k prior-request tokens create_http_options=types.HttpOptions( timeout=10_000, # 10 s cap on CachedContent.create() (milliseconds!) # headers={"x-tenant-id": "acme"}, # custom headers reach the cache-create RPC too ),)
# Cache TTL string helper — used internally by ADK when building CachedContent:print(cache_cfg.ttl_string) # → "3600s"Two hard rules from the source docstring you must not confuse:
- Second-turn earliest. No cache is created on the first request of a session — Gemini has no prior token count to gate on. Caching begins on turn 2 onwards.
- Model minimum floor.
min_tokensis a floor above Gemini’s own model-specific minimum. Verified in the source docstring: Gemini 2.5 requires 2048 tokens cacheable prefix; Gemini 3 requires 4096. Settingmin_tokens=0still respects those floors — it does not opt you into shorter caching.
The pydantic extra="forbid" config on the class means typos (ttl_secs=, cache_interval=) raise ValidationError immediately at construction time, which is what you want.
run_async return semantics
Section titled “run_async return semantics”run_async yields Event objects one at a time. Each event carries:
event.author— agent name or"user".event.content— the message content (types.Content).event.actions— state delta, artifact delta,escalate,transfer_to_agent,skip_summarization, etc.event.partial—Truefor streaming chunks; the final event is non-partial.event.usage_metadata— token counts, only on model events.event.get_function_calls()/get_function_responses()— helpers to peel function-call events.
Non-partial events are persisted via session_service.append_event before being yielded.
Event and EventActions
Section titled “Event and EventActions”Event (defined in events/event.py) extends LlmResponse and is the single unit of communication between agents, tools, and the runner.
Key fields
Section titled “Key fields”| Field | Type | Purpose |
|---|---|---|
id | str | Unique event ID (auto-generated UUID) |
invocation_id | str | Groups all events from one run_async call |
author | str | "user" or the agent name |
content | types.Content | None | The message content (parts with text, function calls, etc.) |
actions | EventActions | Side-effects — state delta, routing, auth requests, etc. |
partial | bool | True for SSE streaming chunks; False for the final aggregated event |
timestamp | float | Unix seconds when the event was created |
long_running_tool_ids | set[str] | None | IDs of long-running function calls (pauses the invocation) |
branch | str | None | Dot-separated agent hierarchy (e.g. "triage.billing") |
node_info | NodeInfo | Workflow node metadata (path, run_id, name) |
output | Any | None | Structured output from a workflow node |
usage_metadata | UsageMetadata | None | Token counts (prompt, candidates, total) |
Useful methods
Section titled “Useful methods”# Is this the agent's final reply for this turn?if event.is_final_response(): text = "".join(p.text or "" for p in (event.content.parts or [])) print(text)
# Extract tool callsfor fc in event.get_function_calls(): print(f"Tool: {fc.name}({fc.args})")
# Extract tool responsesfor fr in event.get_function_responses(): print(f"Result for {fr.name}: {fr.response}")
# Convenience alias: event.message ↔ event.contenttext_parts = [p.text for p in (event.message.parts or []) if p.text]is_final_response() checks, in order:
actions.skip_summarizationis set orlong_running_tool_idsis non-empty →True(even with function calls present, so a client can show progress for a long-running call).- The event has an
error_code, is not partial and has no function calls →True. Error events count as final, so don’t assume every final event is a successful text reply. - Otherwise
Trueonly when there are no function calls or responses, the event is not partial, and there’s no trailing code-execution result.
When several agents take part in one invocation, each can produce its own final event.
Event(...) accepts shorthand keywords that it routes to nested fields: message= → content (text or parts are converted), state= → actions.state_delta, route= → actions.route, node_path= → node_info.path. So Event(author="my_agent", message="Done.", state={"ready": True}) is a complete event.
EventActions fields
Section titled “EventActions fields”EventActions (events/event_actions.py) carries the side-effects of an event:
| Field | Type | Purpose |
|---|---|---|
state_delta | dict[str, Any] | State keys/values to merge into the session on commit |
artifact_delta | dict[str, int] | Filename → version; auto-populated by save_artifact |
transfer_to_agent | str | None | Route control to this agent name after this event |
escalate | bool | None | Exit a loop — used by LoopAgent / workflow loop nodes |
skip_summarization | bool | None | Suppress the LLM from paraphrasing the tool result |
requested_auth_configs | dict[str, AuthConfig] | Pending OAuth flows, keyed by function-call ID |
requested_tool_confirmations | dict[str, ToolConfirmation] | Pending HITL confirmations |
compaction | EventCompaction | None | Sliding-window compaction metadata |
end_of_agent | bool | None | Marks that the originating agent has finished its run |
route | str | bool | int | list | None | Workflow routing value |
render_ui_widgets | list[UiWidget] | None | Rich UI widgets for ADK Web UI hosts |
rewind_before_invocation_id | str | None | Rewind anchor (set by runner.rewind_async); the target invocation and everything after it are discarded |
transfer_reason | str | None | Why transfer_to_agent was set (shows in telemetry) |
agent_state | dict | None | Checkpoint state for resumable agents and workflow nodes |
set_model_response | Any | None | Overrides the structured output for the model response |
Tools set these through tool_context: tool_context.state[...] = ... becomes state_delta, and tool_context.actions.transfer_to_agent = "billing_agent" (with an optional transfer_reason) or tool_context.actions.escalate = True steer control. A compaction event’s actions.compaction is an EventCompaction(start_timestamp, end_timestamp, compacted_content) covering the summarised window.
Emitting custom events from tools
Section titled “Emitting custom events from tools”Tools change state and routing through tool_context (above). A @node in a Workflow can instead yield Event(state={"key": "val"}) or yield Event(route="billing"), or both at once:
from google.adk.events.event import Eventfrom google.adk.workflow import node
@nodeasync def classify_and_route(node_input: str, ctx): intent = "billing" if "invoice" in node_input.lower() else "support" # Emit a state update alongside the routing decision yield Event( state={"last_intent": intent}, route=intent, )NodeInfo — workflow event metadata
Section titled “NodeInfo — workflow event metadata”Events emitted inside a Workflow carry a node_info field:
for event in events: if event.node_info.path: print(f"Node: {event.node_info.name}, run_id: {event.node_info.run_id}")| Property | Purpose |
|---|---|
node_info.path | Full slash-separated path, e.g. "my_wf/classify@1/billing@1" |
node_info.name | Just the node name without @run_id, e.g. "billing" |
node_info.run_id | Execution ID of this run (useful when a node runs multiple times in a loop) |
Artifact service
Section titled “Artifact service”Runners accept an optional artifact_service=. When configured, tools can call tool_context.save_artifact("report.pdf", part) and load_artifact(...). Available services (artifacts/__init__.py):
| Service | Storage |
|---|---|
InMemoryArtifactService() | Dict in memory |
FileArtifactService(root_dir=...) | Local filesystem |
GcsArtifactService(bucket_name=...) | Google Cloud Storage |
See memory-and-artifacts for detailed semantics and versioning.
InvocationContext — invocation lifecycle
Section titled “InvocationContext — invocation lifecycle”Each call to runner.run_async creates one InvocationContext. Callbacks and plugins receive it via invocation_context kwargs. Key fields:
| Field | Type | Notes |
|---|---|---|
invocation_id | str | Unique per run_async call; prefix "e-" + UUID |
session | Session | The live session object |
user_content | types.Content | None | The original user message (readonly) |
run_config | RunConfig | None | Per-run config |
end_invocation | bool | Set to True to abort the current invocation early |
agent | BaseAgent | BaseNode | None | The currently-executing agent |
Early termination with end_invocation
Section titled “Early termination with end_invocation”Set invocation_context.end_invocation = True inside any callback to stop the invocation after the current step. Useful for hard budget/safety gates. Here a before_agent_callback ends the run and returns the reply the user sees:
from google.genai import typesfrom google.adk.agents import LlmAgentfrom google.adk.agents.callback_context import CallbackContext
def safety_gate(callback_context: CallbackContext) -> types.Content | None: ctx = callback_context._invocation_context user_text = " ".join(p.text or "" for p in (ctx.user_content.parts if ctx.user_content else [])) if "forbidden" in user_text.lower(): ctx.end_invocation = True # stop the whole invocation, not just this agent return types.Content(role="model", parts=[types.Part(text="I cannot help with that request.")]) return None
agent = LlmAgent(name="guarded", model="gemini-3.8-flash", instruction="Answer the user.", before_agent_callback=safety_gate)LlmCallsLimitExceededError
Section titled “LlmCallsLimitExceededError”When RunConfig.max_llm_calls is exceeded, the runner raises LlmCallsLimitExceededError. Catch it at the call site if you want graceful handling:
from google.adk.agents.invocation_context import LlmCallsLimitExceededError
try: async for event in runner.run_async(user_id=..., session_id=..., new_message=...): process(event)except LlmCallsLimitExceededError as exc: print(f"Budget exceeded: {exc}")Patterns
Section titled “Patterns”1 — Dev loop with run_debug
Section titled “1 — Dev loop with run_debug”runner = InMemoryRunner(agent=agent)events = await runner.run_debug(["Hi", "What's my name?"])Uses fixed user_id="debug_user_id", session_id="debug_session_id". Reuse the same session id across calls to continue the conversation.
2 — Production with Vertex Agent Engine
Section titled “2 — Production with Vertex Agent Engine”Runner(app=app, session_service=VertexAiSessionService(...), memory_service=VertexAiMemoryBankService(...), artifact_service=GcsArtifactService(bucket_name=...)), with traces exported to Cloud Trace (adk deploy ... --otel_to_cloud, or the telemetry setup in the production guide).
3 — Local SQLite persistence
Section titled “3 — Local SQLite persistence”DatabaseSessionService(db_url="sqlite+aiosqlite:///./adk.db") plus FileArtifactService(root_dir="./artifacts"). Works offline; easy to ship in a Docker image.
4 — Rewinding bad turns
Section titled “4 — Rewinding bad turns”If an invocation went off the rails, await runner.rewind_async(user_id=..., session_id=..., rewind_before_invocation_id=bad_id) inverts the state and artifact deltas of events from that invocation forward. The session is left in its pre-invocation state; the user can retry.
5 — Event compaction for long chats
Section titled “5 — Event compaction for long chats”Configure EventsCompactionConfig(compaction_interval=10, overlap_size=2, token_threshold=50_000, event_retention_size=50). The runner compacts old events into a summarised form after every 10 user invocations — combine with RunConfig.get_session_config=GetSessionConfig(num_recent_events=50) to limit fetch size.
Gotchas
Section titled “Gotchas”- Exactly one of
app=,agent=, ornode=on theRunnerconstructor. Supplying more raisesValueError. - When using
agent=,app_name=is required. Runner(plugins=...)is deprecated. Move plugins toApp(plugins=...).auto_create_session=False(the default) means missing sessions raiseSessionNotFoundError. Callers should create sessions explicitly during signup/handshake.DatabaseSessionServicerequiressqlalchemy>=2.0— it’s lazy-imported so the error only fires when you instantiate it.RunConfig.save_input_blobs_as_artifactsandsave_live_audioare deprecated. UseSaveFilesAsArtifactsPluginandsave_live_blob.- The sync
Runner.run()spawns a background thread — safe for notebooks, not recommended for servers. - App-name alignment: the runner warns if the agent’s module path suggests a different app name (
agents/my_app/agent.py→my_app). Setapp_nameto match or move your module.