Quickstart#
Wire SQLSpec stores into your ADK agent to persist sessions, events, and memory across restarts.
How It Works#
Create a SQLSpec database config with ADK extension settings.
Initialize the appropriate stores (session and memory).
Pass the service wrappers to your ADK agent.
Session Service#
The session service persists agent state and events between conversations. When a user returns, the agent can resume from where it left off.
from sqlspec.adapters.asyncpg import AsyncpgConfig
from sqlspec.adapters.asyncpg.adk import AsyncpgADKStore
from sqlspec.extensions.adk import SQLSpecSessionService
config = AsyncpgConfig(
connection_config={"dsn": "postgresql://localhost/mydb"},
extension_config={
"adk": {
"session_table": "adk_session",
"events_table": "adk_event",
}
},
)
store = AsyncpgADKStore(config)
await store.ensure_tables()
session_service = SQLSpecSessionService(store)
# Create a session with scoped state
session = await session_service.create_session(
app_name="my_agent",
user_id="user_123",
state={
"app:model": "gemini-2.0", # shared across all sessions
"user:name": "Alice", # shared across user's sessions
"conversation_turn": 0, # session-local
"temp:scratch": "...", # runtime-only, never persisted
},
)
Events are persisted automatically when you use the session service with an
ADK runner. Each call to append_event() atomically stores the event and
updates the session's durable state via append_event_and_update_state().
Scoped State#
State keys use prefixes to control their scope and persistence:
app:-- shared across all sessions for the same application.user:-- shared across all sessions for the same user.temp:-- runtime-only, stripped before every write to storage.(no prefix) -- private to the current session.
See Scoped State Semantics for full details.
Memory Service#
The memory service retains context that the agent can reference later. This enables long-term memory across sessions with full-text search.
from sqlspec.adapters.asyncpg.adk import AsyncpgADKMemoryStore
from sqlspec.extensions.adk import SQLSpecMemoryService
memory_store = AsyncpgADKMemoryStore(config)
await memory_store.ensure_tables()
memory_service = SQLSpecMemoryService(memory_store)
Enable full-text search by setting memory_use_fts: True in the ADK config.
This creates database-native FTS indexes (tsvector, FTS5, InnoDB FT) for
efficient memory retrieval.
Artifact Service#
The artifact service contracts live in sqlspec.extensions.adk.artifact and
separate SQL metadata from object-storage content. Use them when your
deployment provides a concrete artifact metadata store; adapter adk
packages currently export session/event and memory stores only.
Schema Setup#
You can programmatically create ADK tables ahead of first use with
ensure_tables():
await session_store.ensure_tables()
await memory_store.ensure_tables()
Alternatively, configure SQLSpec migrations for your database and run the migration CLI as part of deployment:
sqlspec upgrade