google-adk-persql 0.1.0

Google ADK session service backed by PerSQL — durable sessions, events, and state in an isolated SQLite database per agent.

google-adk-persql

Google ADK session service backed by PerSQL — durable sessions, events, and state in an isolated SQLite database per agent, provisioned instantly.

pip install google-adk-persql

Usage

import os
from google.adk.runners import Runner
from persql import PerSQL
from google_adk_persql import PerSQLSessionService

client = PerSQL(token=os.environ["PERSQL_TOKEN"])
service = PerSQLSessionService(client.database("acme/agent-state"))

runner = Runner(agent=agent, app_name="my-app", session_service=service)

Or let the service own the client:

with PerSQLSessionService.from_token(os.environ["PERSQL_TOKEN"], "acme/agent-state") as service:
    ...

AsyncPerSQL databases are awaited natively; sync databases run via asyncio.to_thread.

What it stores

The same four-table layout and state-scope semantics as ADK's built-in SqliteSessionService:

• adk_sessions — one row per session, with session-scoped state.
• adk_events — one row per event, stored as opaque JSON so ADK event fields can evolve without schema migrations.
• adk_app_states / adk_user_states — app: and user: prefixed state keys, shared across sessions and merged into session.state on read. temp: keys are never persisted.

Pass table_prefix= to change the adk_ prefix.

Limits

• The stale-session check in append_event is read-then-write over HTTP, not a single database transaction — two writers racing the same session can both pass it. Keep one writer per session.
• Event payloads are JSON; binary artifacts should go through ADK's artifact service, not session state.
• Requires google-adk >= 2.2, < 3 — the package subclasses BaseSessionService, so an ADK major version can change the contract.

Local mode for tests

from persql import PerSQL
service = PerSQLSessionService(PerSQL(local=":memory:").database("test/db"))

Runs against in-process SQLite — no network, no token.