Skip to content

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

@enesdemirag

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
    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