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
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
BufferedFirestoreSessionServiceto 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 want the builtin instead if:
Both services use the same Firestore layout, so they're compatible with each other's data.
What's in the PR
BufferedFirestoreSessionServiceingoogle.adk_community.sessionsdurable_mode=Trueflag to fall back to per-event writes (same as builtin)flat_layout=Trueoption for a flatroot_collection/{session_id}layout instead of the default ADK nested path[firestore]optional extra (google-cloud-firestore>=2.11,<3, matching ADK's own constraint)PR: #160