Google ADK Extension¶

from sqlspec.extensions.adk import (
    ADKConfig,
    BaseAsyncADKArtifactStore,
    BaseAsyncADKMemoryStore,
    BaseAsyncADKStore,
    BaseSyncADKArtifactStore,
    BaseSyncADKMemoryStore,
    BaseSyncADKStore,
    PruneReport,
    SessionOrderBy,
    SQLSpecArtifactService,
    SQLSpecMemoryService,
    SQLSpecSessionService,
    SQLSpecSyncMemoryService,
    StoredArtifact,
    StoredEvent,
    StoredMemory,
    StoredSession,
    prune_artifacts,
    prune_events,
    prune_memory,
    prune_sessions,
    prune_user_state,
)

Session, event, long-term memory, and artifact metadata services and base stores for the Google Agent Development Kit (ADK). Adapter-specific ADK store subclasses are documented on each Database Adapter page. See the Google ADK Integration Guide for setup examples.

ADK Services¶

SQLSpecSessionService ¶

Bases: BaseSessionService

SQLSpec-backed implementation of BaseSessionService.

Provides session and event storage using SQLSpec database adapters. Delegates all database operations to a store implementation.

Parameters:

Name	Type	Description	Default
`store`	`ADKStore`	Database store implementation.	required

create_session ¶

create_session(*, app_name, user_id, state=None, session_id=None)

Create a new session.

Parameters:

Name	Type	Description	Default
`app_name`	`str`	Name of the application.	required
`user_id`	`str`	ID of the user.	required
`state`	`dict[str, Any] \| None`	Initial state of the session.	`None`
`session_id`	`str \| None`	Client-provided session ID. If None or whitespace-only, generates a UUID.	`None`

Returns:

Type	Description
`Session`	The newly created session.

Raises:

Type	Description
`AlreadyExistsError`	If a caller-supplied `session_id` already exists.

get_session ¶

get_session(*, app_name, user_id, session_id, config=None)

Get a session by ID.

Parameters:

Name	Type	Description	Default
`app_name`	`str`	Name of the application.	required
`user_id`	`str`	ID of the user.	required
`session_id`	`str`	Session identifier.	required
`config`	`GetSessionConfig \| None`	Configuration for retrieving events.	`None`

Returns:

Type	Description
`Session \| None`	Session object if found, None otherwise.

append_event ¶

append_event(session, event)

Append an event to a session.

Persists the event record and the post-append durable state atomically via store.append_event_and_update_state(), then updates the in-memory session only after persistence succeeds.

Implements stale-session detection: if the session has been modified in storage since it was last loaded, a StaleSessionError is raised instead of silently overwriting.

temp: keys are stripped from the persisted state snapshot so they never survive a reload.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Session to append to.	required
`event`	`Event`	Event to append.	required

Returns:

Type	Description
`Event`	The appended event.

Raises:

Type	Description
`SessionNotFoundError`	If the session does not exist in storage.
`StaleSessionError`	If the session has been modified in storage since it was loaded (stale session).

SQLSpecMemoryService ¶

Bases: BaseMemoryService

SQLSpec-backed implementation of BaseMemoryService.

Provides memory entry storage using SQLSpec database adapters. Delegates all database operations to a store implementation.

ADK BaseMemoryService defines two core methods

add_session_to_memory(session) - Ingests session into memory (returns void)
search_memory(app_name, user_id, query) - Searches stored memories

Parameters:

Name	Type	Description	Default
`store`	`BaseAsyncADKMemoryStore \| BaseSyncADKMemoryStore`	Database store implementation.	required

SQLSpecSyncMemoryService ¶

Synchronous SQLSpec-backed memory service.

Provides memory entry storage using SQLSpec sync database adapters. This is a sync-compatible version for use with sync drivers like SQLite.

Note: This does NOT inherit from BaseMemoryService since ADK's base class requires async methods. Use this for sync-only deployments.

Parameters:

Name	Type	Description	Default
`store`	`BaseSyncADKMemoryStore`	Sync database store implementation.	required

SQLSpecArtifactService ¶

Bases: BaseArtifactService

SQLSpec-backed implementation of BaseArtifactService.

Composes SQL metadata storage with sqlspec/storage/ content backends to provide versioned artifact management for Google ADK.

Metadata (version number, filename, MIME type, custom metadata, canonical URI) is stored in a SQL table managed by the artifact store. Content bytes are stored in object storage (S3, GCS, Azure, local filesystem) via the storage registry.

Parameters:

Name	Type	Description	Default
`store`	`BaseAsyncADKArtifactStore \| BaseSyncADKArtifactStore`	Artifact metadata store implementation (async or sync).	required
`artifact_storage_uri`	`str`	Base URI for content storage. Can also be a registered alias in the storage registry.	required
`registry`	`StorageRegistry \| None`	Storage registry to use. Defaults to the global singleton.	`None`

Base ADK Stores¶

BaseAsyncADKStore ¶

Bases: _ADKStoreCommon[ConfigT], ABC

Base class for async SQLSpec-backed ADK session stores.

Implements storage operations for Google ADK sessions and events using SQLSpec database adapters with async/await.

This abstract base class provides common functionality for all database-specific store implementations including: - Connection management via SQLSpec configs - Table name validation - Session and event CRUD operations

Subclasses must implement dialect-specific SQL queries and will be created in each adapter directory (e.g., sqlspec/adapters/asyncpg/adk/store.py).

Parameters:

Name	Type	Description	Default
`config`	`ConfigT`	SQLSpec database configuration with extension_config["adk"] settings.	required

Notes

Configuration is read from config.extension_config["adk"]: - session_table: Sessions table name (default: "adk_session") - events_table: Events table name (default: "adk_event") - app_state_table: App-scoped state table name (default: "adk_app_state") - user_state_table: User-scoped state table name (default: "adk_user_state") - metadata_table: Internal metadata table name (default: "adk_internal_metadata") - owner_id_column: Optional owner FK column DDL (default: None)

BaseSyncADKStore ¶

Bases: _ADKStoreCommon[ConfigT], ABC

Base class for sync SQLSpec-backed ADK session stores.

Sync-backed adapters expose a real synchronous API for direct use in synchronous applications. Async bridging belongs in SQLSpecSessionService when Google ADK calls into a sync store from its async service surface.

Parameters:

Name	Type	Description	Default
`config`	`ConfigT`	SQLSpec database configuration with extension_config["adk"] settings.	required

BaseAsyncADKMemoryStore ¶

Bases: _ADKMemoryStoreCommon[ConfigT], ABC

Base class for async SQLSpec-backed ADK memory stores.

Implements storage operations for Google ADK memory entries using SQLSpec database adapters with async/await.

BaseSyncADKMemoryStore ¶

Bases: _ADKMemoryStoreCommon[ConfigT], ABC

Base class for sync SQLSpec-backed ADK memory stores.

BaseAsyncADKArtifactStore ¶

Bases: _ADKArtifactStoreCommon[ConfigT], ABC

Base class for async SQLSpec-backed ADK artifact metadata stores.

Manages artifact version metadata in a SQL table. Content bytes are stored externally via sqlspec/storage/ backends and referenced by canonical URI in each metadata row.

Subclasses must implement dialect-specific SQL queries.

Parameters:

Name	Type	Description	Default
`config`	`ConfigT`	SQLSpec database configuration with extension_config["adk"] settings.	required

BaseSyncADKArtifactStore ¶

Bases: _ADKArtifactStoreCommon[ConfigT], ABC

Base class for sync SQLSpec-backed ADK artifact metadata stores.

Synchronous counterpart of :class:BaseAsyncADKArtifactStore.

Parameters:

Name	Type	Description	Default
`config`	`ConfigT`	SQLSpec database configuration with extension_config["adk"] settings.	required

Configuration & Record Schemas¶

`ADKConfig` ¶

Bases: TypedDict

Configuration options for ADK session and memory store extension.

All fields are optional with sensible defaults. Use in extension_config["adk"]:

Configuration supports three deployment scenarios

SQLSpec manages everything (runtime + migrations)
SQLSpec runtime only (external migration tools like Alembic/Flyway)
Selective features (sessions OR memory, not both)

Attributes:

Name	Type	Description
`migrations_path`	`NotRequired[str \| Path]`	Directory containing this extension's migrations, or a `'<dotted.module>:<subdir>'` specification.
`manage_schema`	`NotRequired[bool]`	Apply additive target-schema reconciliation. Default: True.
`create_schema`	`NotRequired[bool]`	Create missing ADK tables during managed reconciliation. Default: True.
`enable_sessions`	`NotRequired[bool]`	Enable the session store at runtime and in packaged migrations. Default: True.
`enable_memory`	`NotRequired[bool]`	Enable the memory store at runtime and in packaged migrations. Default: True.
`session_table`	`NotRequired[str]`	Name of the sessions table. Default: 'adk_session'
`events_table`	`NotRequired[str]`	Name of the events table. Default: 'adk_event'
`app_state_table`	`NotRequired[str]`	Name of the app-scoped state table. Default: 'adk_app_state'
`user_state_table`	`NotRequired[str]`	Name of the user-scoped state table. Default: 'adk_user_state'
`metadata_table`	`NotRequired[str]`	Name of the internal metadata table. Default: 'adk_internal_metadata'
`memory_table`	`NotRequired[str]`	Name of the memory entries table. Default: 'adk_memory'
`artifact_table`	`NotRequired[str]`	Name of the artifact metadata table. Default: 'adk_artifact'
`artifact_storage_uri`	`NotRequired[str]`	Base URI for artifact content storage.
`memory_use_fts`	`NotRequired[bool]`	Enable full-text search when supported. Default: False.
`memory_max_results`	`NotRequired[int]`	Maximum number of results for memory search queries. Default: 20.
`owner_id_column`	`NotRequired[str]`	Optional owner ID column definition to link sessions/memories to a user, tenant, team, or other entity.

StoredSession ¶

Bases: TypedDict

Database record for a session.

Represents the schema for sessions stored in the database.

Attributes:

Name	Type	Description
`id`	`str`	Unique Google ADK session identifier.
`app_name`	`str`	Application namespace owning the session.
`user_id`	`str`	End-user identifier associated with the session.
`state`	`dict[str, Any]`	Serialized session-scoped state dictionary.
`create_time`	`datetime`	UTC timestamp when the session record was created.
`update_time`	`datetime`	UTC timestamp of the most recent session state or event update.

StoredEvent ¶

Bases: TypedDict

Database record for an event.

Stores the full ADK Event as a single JSON blob (event_data) alongside indexed scalar columns used for scoped query filtering.

This design eliminates column drift with upstream ADK: new Event fields are automatically captured in event_data without schema changes.

Attributes:

Name	Type	Description
`id`	`str`	Unique ADK event identifier.
`app_name`	`str`	Application namespace owning the parent session.
`user_id`	`str`	End-user identifier owning the parent session.
`session_id`	`str`	Parent ADK session identifier.
`invocation_id`	`str`	Agent turn or invocation identifier grouping related events.
`timestamp`	`datetime`	UTC timestamp when the event was emitted.
`event_data`	`dict[str, Any]`	Complete serialized Google ADK `Event` payload.

StoredMemory ¶

Bases: TypedDict

Database record for a memory entry.

Represents the schema for memory entries stored in the database. Contains extracted content from ADK events for searchable long-term memory.

Attributes:

Name	Type	Description
`id`	`str`	Unique memory entry identifier.
`session_id`	`str`	Source ADK session identifier from which the memory was extracted.
`app_name`	`str`	Application namespace owning the memory entry.
`user_id`	`str`	End-user identifier owning the memory entry.
`scope`	`str`	Visibility scope for retrieval (such as `user` or `app`).
`event_id`	`str`	Originating ADK event identifier.
`author`	`str \| None`	Agent or participant role that authored the source event.
`timestamp`	`datetime`	UTC timestamp of the originating conversation event.
`content_json`	`dict[str, Any]`	Structured ADK `Content` payload stored as JSON.
`content_text`	`str`	Flattened plain-text projection indexed for full-text and keyword search.
`metadata_json`	`dict[str, Any] \| None`	Optional structured metadata dictionary attached to the memory entry.
`inserted_at`	`datetime`	UTC timestamp when the memory row was persisted.
`embedding`	`Sequence[float] \| None`	Optional dense float vector used for semantic similarity search.

StoredArtifact ¶

Bases: TypedDict

Database record for an artifact version.

Represents the schema for artifact metadata stored in the database. Content is stored separately in object storage; this record tracks versioning, ownership, and the canonical URI pointing to the content.

The composite key is (app_name, user_id, session_id, filename, version), where session_id may be NULL for user-scoped artifacts.

Attributes:

Name	Type	Description
`app_name`	`str`	Application namespace owning the artifact.
`user_id`	`str`	End-user identifier owning the artifact.
`session_id`	`str \| None`	Session identifier for session-scoped artifacts, or `None` for user-scoped artifacts.
`filename`	`str`	Logical artifact filename within the user or session scope.
`version`	`int`	Zero-based or monotonic integer revision number for the artifact.
`mime_type`	`str \| None`	IANA media type of the stored artifact payload, if known.
`canonical_uri`	`str`	Object-storage URI referencing the persisted binary content.
`custom_metadata`	`dict[str, Any] \| None`	Optional caller-supplied metadata dictionary stored alongside the revision.
`created_at`	`datetime`	UTC timestamp when this artifact version was recorded.

Maintenance & Pruning Helpers¶

PruneReport ¶

Bases: TypedDict

Performance telemetry for a pruning operation.

Attributes:

Name	Type	Description
`deleted_count`	`int`	Total number of expired or idle rows deleted during the sweep.
`elapsed_ms`	`float`	Wall-clock duration of the pruning operation in milliseconds.
`table`	`str`	Target ADK persistence table name that was pruned.

prune_sessions ¶

prune_sessions(target, *, idle_days=30, app_name=None)

Prune sessions that have been idle longer than specified days.

Parameters:

Name	Type	Description	Default
`target`	`Any`	ADKStore instance, DatabaseConfig, or DriverAdapter.	required
`idle_days`	`int`	Number of days of inactivity before a session is pruned.	`30`
`app_name`	`str \| None`	Optional application name to limit pruning.	`None`

Returns:

Type	Description
`PruneReport`	PruneReport containing deleted row count and timing.

Raises:

Type	Description
`ValueError`	If `idle_days` is not a positive integer.

Google ADK Extension¶

ADK Services¶

SQLSpecSessionService ¶

create_session ¶

get_session ¶

append_event ¶

SQLSpecMemoryService ¶

SQLSpecSyncMemoryService ¶

SQLSpecArtifactService ¶

Base ADK Stores¶

BaseAsyncADKStore ¶

BaseSyncADKStore ¶

BaseAsyncADKMemoryStore ¶

BaseSyncADKMemoryStore ¶

BaseAsyncADKArtifactStore ¶

BaseSyncADKArtifactStore ¶

Configuration & Record Schemas¶

ADKConfig ¶

StoredSession ¶

StoredEvent ¶

StoredMemory ¶

StoredArtifact ¶

Maintenance & Pruning Helpers¶

PruneReport ¶

prune_sessions ¶

`ADKConfig` ¶