Skip to content

feat: add FirestoreSessionService for serverless session persistence #103

@anmolg1997

Description

@anmolg1997

Summary

Add a FirestoreSessionService — a BaseSessionService implementation backed by Google Cloud Firestore, providing persistent, serverless session storage with zero database management.

This was originally submitted as google/adk-python#4439, where maintainer @rohityan directed it to this community repo.

Motivation

The ADK currently has:

  • InMemorySessionService — dev-only, no persistence
  • DatabaseSessionService — requires SQL infrastructure (PostgreSQL, MySQL, SQLite)
  • VertexAiSessionService — requires a Reasoning Engine
  • RedisSessionService (community) — requires a Redis instance

For GCP-native deployments (Cloud Run, Cloud Functions), Firestore offers a fully managed, serverless alternative with no infrastructure to provision.

Design

  • Events stored in Firestore subcollections (avoids 1MB document size limit)
  • Three-tier state management (app/user/session) matching ADK conventions
  • Atomic state updates via Firestore transactions (addresses race conditions)
  • Batch writes for bulk event deletion
  • Server-side query limits for num_recent_events
  • google-cloud-firestore as an optional dependency
  • Async context manager support for clean client lifecycle

Implementation Plan

  1. src/google/adk_community/sessions/firestore_session_service.py
  2. tests/unittests/sessions/test_firestore_session_service.py
  3. Update __init__.py exports and pyproject.toml optional dependencies

Ref: google/adk-python#3776

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions