API Reference¶

This page documents the complete API for the SQLSpec ADK extension.

Session Service¶

SQLSpecSessionService¶

class sqlspec.extensions.adk.SQLSpecSessionService[source]¶

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:: store¶ (BaseAsyncADKStore) – Database store implementation (e.g., AsyncpgADKStore).

Example

from sqlspec.adapters.asyncpg import AsyncpgConfig from sqlspec.adapters.asyncpg.adk.store import AsyncpgADKStore from sqlspec.extensions.adk.service import SQLSpecSessionService

config = AsyncpgConfig(pool_config={“dsn”: “postgresql://…”}) store = AsyncpgADKStore(config) await store.create_tables()

service = SQLSpecSessionService(store) session = await service.create_session(

app_name=”my_app”, user_id=”user123”, state={“key”: “value”}

)

SQLSpec-backed implementation of Google ADK’s BaseSessionService.

This service provides session and event storage using SQLSpec database adapters, delegating all database operations to a store implementation.

Attributes:

store: The database store implementation (e.g., AsyncpgADKStore).

Example:

from sqlspec.adapters.asyncpg import AsyncpgConfig
from sqlspec.adapters.asyncpg.adk import AsyncpgADKStore
from sqlspec.extensions.adk import SQLSpecSessionService

config = AsyncpgConfig(pool_config={"dsn": "postgresql://..."})
store = AsyncpgADKStore(config)
await store.create_tables()

service = SQLSpecSessionService(store)

# Create a session
session = await service.create_session(
    app_name="my_app",
    user_id="user123",
    state={"key": "value"}
)

Base Store Classes¶

BaseAsyncADKStore¶

class sqlspec.extensions.adk.BaseAsyncADKStore[source]¶

Bases: ABC, Generic[ConfigT]

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:: config¶ (TypeVar(ConfigT)) – SQLSpec database configuration with extension_config[“adk”] settings.

Notes

Configuration is read from config.extension_config[“adk”]: - session_table: Sessions table name (default: “adk_sessions”) - events_table: Events table name (default: “adk_events”) - owner_id_column: Optional owner FK column DDL (default: None)

Abstract base class for async SQLSpec-backed ADK session stores.

This class defines the interface that all database-specific async store implementations must follow. Each database adapter (asyncpg, psycopg, asyncmy, etc.) provides a concrete implementation in its adk/ subdirectory.

Type Parameters:

ConfigT: The SQLSpec configuration type (e.g., AsyncpgConfig)

Abstract Methods:

Subclasses must implement:

create_session()
get_session()
update_session_state()
list_sessions()
delete_session()
append_event()
get_events()
create_tables()
_get_create_sessions_table_sql()
_get_create_events_table_sql()
_get_drop_tables_sql()

Properties:

config: The SQLSpec database configuration.

session_table: Name of the sessions table (default: adk_sessions).

events_table: Name of the events table (default: adk_events).

Example:

from sqlspec.adapters.asyncpg import AsyncpgConfig
from sqlspec.adapters.asyncpg.adk import AsyncpgADKStore

config = AsyncpgConfig(pool_config={"dsn": "postgresql://..."})
store = AsyncpgADKStore(
    config,
    session_table="custom_sessions",
    events_table="custom_events"
)
await store.create_tables()

BaseSyncADKStore¶

class sqlspec.extensions.adk.BaseSyncADKStore[source]¶

Bases: ABC, Generic[ConfigT]

Base class for sync SQLSpec-backed ADK session stores.

Implements storage operations for Google ADK sessions and events using SQLSpec database adapters with synchronous execution.

This abstract base class provides common functionality for sync 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/sqlite/adk/store.py).

Parameters:: config¶ (TypeVar(ConfigT)) – SQLSpec database configuration with extension_config[“adk”] settings.

Notes

Abstract base class for synchronous SQLSpec-backed ADK session stores.

Similar to BaseAsyncADKStore but for synchronous database drivers. Currently used by the SQLite adapter which wraps sync operations with async compatibility.

Type Parameters:

ConfigT: The SQLSpec configuration type (e.g., SqliteConfig)

Abstract Methods:

Subclasses must implement:

create_session()
get_session()
update_session_state()
list_sessions()
delete_session()
create_event()
list_events()
create_tables()
_get_create_sessions_table_sql()
_get_create_events_table_sql()
_get_drop_tables_sql()

Example:

from sqlspec.adapters.sqlite import SqliteConfig
from sqlspec.adapters.sqlite.adk import SqliteADKStore

config = SqliteConfig(pool_config={"database": "agent.db"})
store = SqliteADKStore(config)
store.create_tables()

__init__(config)[source]¶

Initialize the sync ADK store.

Parameters:: config¶ (TypeVar(ConfigT)) – SQLSpec database configuration.

Notes

property config: ConfigT¶: Return the database configuration.

property session_table: str¶: Return the sessions table name.

property events_table: str¶: Return the events table name.

property owner_id_column_ddl: str | None¶: Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None¶: Return the owner ID column name only (or None if not configured).

abstractmethod create_session(session_id, app_name, user_id, state, owner_id=None)[source]¶

Create a new session.

Parameters:

session_id¶ (str) – Unique identifier for the session.
app_name¶ (str) – Name of the application.
user_id¶ (str) – ID of the user.
state¶ (dict[str, typing.Any]) – Session state dictionary.
owner_id¶ (Optional[typing.Any]) – Optional owner ID value for owner_id_column (if configured).

Return type:

SessionRecord

Returns:

The created session record.

abstractmethod get_session(session_id)[source]¶

Get a session by ID.

Parameters:: session_id¶ (str) – Session identifier.
Return type:: SessionRecord | None
Returns:: Session record if found, None otherwise.

abstractmethod update_session_state(session_id, state)[source]¶

Update session state.

Parameters:

session_id¶ (str) – Session identifier.
state¶ (dict[str, typing.Any]) – New state dictionary.

Return type:

None

abstractmethod list_sessions(app_name, user_id=None)[source]¶

List all sessions for an app, optionally filtered by user.

Parameters:

app_name¶ (str) – Name of the application.
user_id¶ (str | None) – ID of the user. If None, returns all sessions for the app.

Return type:

list[SessionRecord]

Returns:

List of session records.

abstractmethod delete_session(session_id)[source]¶

Delete a session and its events.

Parameters:: session_id¶ (str) – Session identifier.
Return type:: None

abstractmethod create_event(event_id, session_id, app_name, user_id, author=None, actions=None, content=None, **kwargs)[source]¶

Create a new event.

Parameters:

event_id¶ (str) – Unique event identifier.
session_id¶ (str) – Session identifier.
app_name¶ (str) – Application name.
user_id¶ (str) – User identifier.
author¶ (str | None) – Event author (user/assistant/system).
actions¶ (bytes | None) – Pickled actions object.
content¶ (dict[str, typing.Any] | None) – Event content (JSONB/JSON).
**kwargs¶ (Any) – Additional optional fields.

Return type:

EventRecord

Returns:

Created event record.

abstractmethod list_events(session_id)[source]¶

List events for a session ordered by timestamp.

Parameters:: session_id¶ (str) – Session identifier.
Return type:: list[EventRecord]
Returns:: List of event records ordered by timestamp ASC.

abstractmethod create_tables()[source]¶

Create both sessions and events tables if they don’t exist.

Return type:: None

Type Definitions¶

SessionRecord¶

class sqlspec.extensions.adk._types.SessionRecord[source]¶

Bases: TypedDict

Database record for a session.

Represents the schema for sessions stored in the database.

TypedDict representing a session database record.

Fields:

id: str¶: Unique session identifier (typically a UUID).

app_name: str¶: Name of the application.

user_id: str¶: User identifier.

state: dict[str, Any]¶: Session state dictionary (stored as JSON/JSONB).

create_time: datetime¶: Timestamp when session was created (timezone-aware).

update_time: datetime¶: Timestamp when session was last updated (timezone-aware).

Example:

Python 3.9+

from datetime import datetime, timezone

record: SessionRecord = {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "app_name": "weather_agent",
    "user_id": "user123",
    "state": {"location": "SF", "units": "metric"},
    "create_time": datetime.now(timezone.utc),
    "update_time": datetime.now(timezone.utc)
}

Python 3.11+

from datetime import datetime, UTC

record: SessionRecord = {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "app_name": "weather_agent",
    "user_id": "user123",
    "state": {"location": "SF", "units": "metric"},
    "create_time": datetime.now(UTC),
    "update_time": datetime.now(UTC)
}

EventRecord¶

class sqlspec.extensions.adk._types.EventRecord[source]¶

Bases: TypedDict

Database record for an event.

Represents the schema for events stored in the database. Follows the ADK Event model plus session metadata.

TypedDict representing an event database record.

Fields:

id: str¶: Unique event identifier.

app_name: str¶: Application name (denormalized from session).

user_id: str¶: User identifier (denormalized from session).

session_id: str¶: Parent session identifier (foreign key).

invocation_id: str¶: ADK invocation identifier.

author: str¶: Event author (user, assistant, system).

branch: str | None¶: Conversation branch identifier.

actions: bytes¶: Pickled actions object.

long_running_tool_ids_json: str | None¶: JSON-encoded list of long-running tool IDs.

timestamp: datetime¶: Event timestamp (timezone-aware).

content: dict[str, Any] | None¶: Event content (stored as JSON/JSONB).

grounding_metadata: dict[str, Any] | None¶: Grounding metadata (stored as JSON/JSONB).

custom_metadata: dict[str, Any] | None¶: Custom metadata (stored as JSON/JSONB).

partial: bool | None¶: Whether this is a partial event.

turn_complete: bool | None¶: Whether the turn is complete.

interrupted: bool | None¶: Whether the event was interrupted.

error_code: str | None¶: Error code if event failed.

error_message: str | None¶: Error message if event failed.

Converter Functions¶

The converter module provides functions to translate between ADK models and database records.

session_to_record¶

sqlspec.extensions.adk.converters.session_to_record(session)[source]¶

Convert ADK Session to database record.

Parameters:: session¶ (Session) – ADK Session object.
Return type:: SessionRecord
Returns:: SessionRecord for database storage.

Convert an ADK Session object to a SessionRecord for database storage.

Args:

session: ADK Session object

Returns:

SessionRecord: Database record ready for insertion

Example:

from google.adk.sessions import Session
from sqlspec.extensions.adk.converters import session_to_record

session = Session(
    id="sess_123",
    app_name="my_agent",
    user_id="user456",
    state={"count": 1},
    events=[]
)

record = session_to_record(session)
# record is a SessionRecord TypedDict

record_to_session¶

sqlspec.extensions.adk.converters.record_to_session(record, events)[source]¶

Convert database record to ADK Session.

Parameters:

record¶ (SessionRecord) – Session database record.
events¶ (list[EventRecord]) – List of event records for this session.

Return type:

Session

Returns:

ADK Session object.

Convert a SessionRecord and list of EventRecords to an ADK Session object.

Args:

record: Session database record
events: List of event records for this session

Returns:

Session: ADK Session object

Example:

from sqlspec.extensions.adk.converters import record_to_session

session = record_to_session(session_record, event_records)
# session is a google.adk.sessions.Session

event_to_record¶

sqlspec.extensions.adk.converters.event_to_record(event, session_id, app_name, user_id)[source]¶

Convert ADK Event to database record.

Parameters:

event¶ (Event) – ADK Event object.
session_id¶ (str) – ID of the parent session.
app_name¶ (str) – Name of the application.
user_id¶ (str) – ID of the user.

Return type:

EventRecord

Returns:

EventRecord for database storage.

Convert an ADK Event object to an EventRecord for database storage.

Args:

event: ADK Event object
session_id: ID of the parent session
app_name: Application name
user_id: User identifier

Returns:

EventRecord: Database record ready for insertion

Example:

from google.adk.events.event import Event
from google.genai.types import Content, Part
from sqlspec.extensions.adk.converters import event_to_record

event = Event(
    id="evt_1",
    invocation_id="inv_1",
    author="user",
    content=Content(parts=[Part(text="Hello")]),
    actions=[]
)

record = event_to_record(
    event=event,
    session_id="sess_123",
    app_name="my_agent",
    user_id="user456"
)

record_to_event¶

sqlspec.extensions.adk.converters.record_to_event(record)[source]¶

Convert database record to ADK Event.

Parameters:: record¶ (EventRecord) – Event database record.
Return type:: Event
Returns:: ADK Event object.

Convert an EventRecord database record to an ADK Event object.

Args:

record: Event database record

Returns:

Event: ADK Event object

Example:

from sqlspec.extensions.adk.converters import record_to_event

event = record_to_event(event_record)
# event is a google.adk.events.event.Event

Database Adapter Stores¶

Each database adapter provides its own store implementation. See Database Adapters for details.

Available Stores¶

PostgreSQL:

sqlspec.adapters.asyncpg.adk.AsyncpgADKStore
sqlspec.adapters.psycopg.adk.PsycopgADKStore
sqlspec.adapters.psqlpy.adk.PsqlpyADKStore

MySQL:

sqlspec.adapters.asyncmy.adk.AsyncmyADKStore

SQLite:

sqlspec.adapters.sqlite.adk.SqliteADKStore
sqlspec.adapters.aiosqlite.adk.AiosqliteADKStore

Oracle:

sqlspec.adapters.oracledb.adk.OracleADKStore

DuckDB (dev/test only):

sqlspec.adapters.duckdb.adk.DuckDBADKStore

API Reference¶

Session Service¶

SQLSpecSessionService¶

Base Store Classes¶

BaseAsyncADKStore¶

BaseSyncADKStore¶

Type Definitions¶

SessionRecord¶

EventRecord¶

Converter Functions¶

session_to_record¶

record_to_session¶

event_to_record¶

record_to_event¶

Database Adapter Stores¶

Available Stores¶

See Also¶