Skip to content

feat: Add BufferedFirestoreSessionService (batched, buffered Firestore session backend) #159

Description

@enesdemirag

What this is

ADK already ships a Firestore session service (google.adk.integrations.firestore.FirestoreSessionService). It works well, but it does one Firestore transaction per event — so if 10 messages fire 10 events, that's 10 separate writes, each touching the session document to bump its revision.

This adds a BufferedFirestoreSessionService to the community package that holds events in memory and flushes them all in a single transaction when the buffer fills up (or on a timer, or on shutdown). The session document gets updated once instead of 10 times, and the state docs get merged once.

When to use it

You want this if:

  • You're on a budget and Firestore costs matter (fewer writes = lower bill)
  • Your service runs stably and you can afford to lose the last few seconds of events if it crashes

You want the builtin instead if:

  • You need every event durable the moment it happens
  • You're running in an environment where the process can be killed without warning

Both services use the same Firestore layout, so they're compatible with each other's data.

What's in the PR

  • BufferedFirestoreSessionService in google.adk_community.sessions
  • Configurable buffer size, flush interval, retry behaviour
  • durable_mode=True flag to fall back to per-event writes (same as builtin)
  • flat_layout=True option for a flat root_collection/{session_id} layout instead of the default ADK nested path
  • All collection names configurable if your Firestore uses a custom structure
  • 20 unit tests, no external dependencies
  • New [firestore] optional extra (google-cloud-firestore>=2.11,<3, matching ADK's own constraint)

PR: #160

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