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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions