Feat: Firestore support by ScottMansfield · Pull Request #5088 · google/adk-python

ScottMansfield · 2026-03-31T19:34:31Z

Adding support for Firestore for both session and memory storage.

This started by copying the Firestore support from the Java ADK into the Python ADK and also takes inspiration from @anmolg1997's PR google/adk-python-community#104. It does things differently from both.

Firestore contains a hierarchical set of data for sessions:

adk-session
  ↳ <user ID>
    ↳ sessions
      ↳ <session ID>
        ↳ events
          ↳ <event ID>
            ↳ Event document

The firestore memory service creates a top-level collection that hold indexed memories when sessions are added.

Link to Issue or Description of Change

This is from an existing customer request for firestore support.

Testing Plan

Unit Tests:

I have added or updated unit tests for my change.
All unit tests pass locally.

$ pytest tests/unittests/integrations/firestore
======================================== test session starts ========================================
platform darwin -- Python 3.11.14, pytest-9.0.2, pluggy-1.6.0
rootdir: /Users/scottmansfield/projects/adk-python
configfile: pyproject.toml
plugins: mock-3.15.1, xdist-3.8.0, langsmith-0.7.23, asyncio-1.3.0, anyio-4.13.0
asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=function, asyncio_default_test_loop_scope=function
collected 28 items                                                                                  

tests/unittests/integrations/firestore/test_firestore_memory_service.py ...........           [ 39%]
tests/unittests/integrations/firestore/test_firestore_session_service.py .................    [100%]

========================================= warnings summary ==========================================
src/google/adk/features/_feature_decorator.py:72
  /Users/scottmansfield/projects/adk-python/src/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
    check_feature_enabled()

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
=================================== 28 passed, 1 warning in 1.52s ===================================

Manual End-to-End (E2E) Tests:

I created a demo app locally to test the session and memory storage with a real firebase instance. It successfully records sessions and memories, verified by manually checking the cloud console.

Memory did require an index, which will be created by the user the first time the memory session is used. Firestore has a specific deep link that it will create to give the exact index needed. After that, memory worked fine.

Checklist

I have read the CONTRIBUTING.md document.
I have performed a self-review of my own code.
I have commented my code, particularly in hard-to-understand areas.
I have added tests that prove my fix is effective or that my feature works.
New and existing unit tests pass locally with my changes.
I have manually tested my changes end-to-end.
Any dependent changes have been merged and published in downstream modules.

adk-bot · 2026-03-31T19:35:35Z

Response from ADK Triaging Agent

Hello @ScottMansfield, thank you for creating this PR!

I see that this is a draft PR. When you are ready, please ensure you have read the contribution guide and filled out the PR template, including:

Link to an existing issue or a description of the change: This helps reviewers understand the context of your contribution.
Testing Plan: Please describe the tests you ran to verify your changes.

This information will help reviewers to review your PR more efficiently. Thanks!

ScottMansfield · 2026-04-01T14:58:39Z

Looks like we have one open for the community repo: google/adk-python-community#104

rohityan · 2026-04-01T20:55:18Z

Hi @ScottMansfield , Thank you for your contribution! We appreciate you taking the time to submit this pull request.
Closing this PR here as it belongs to adk-python-community repo.
We highly recommend releasing the feature as a standalone package that we will then share through: https://google.github.io/adk-docs/integrations/

rohityan · 2026-04-03T17:31:49Z

Hi @ScottMansfield , is this PR still in draft? If not can you please fill in the details for the PR.

@anmolg1997

These updates are derived from @anmolg1997 PR on the community repo: google/adk-python-community#104

ScottMansfield · 2026-04-09T22:35:06Z

I believe this is ready for review but I'm testing it with a real firestore instance

This creates a new memories collection to hold indexed events.

DeanChensj · 2026-04-10T02:18:22Z

src/google/adk/integrations/firestore/_stop_words.py

+
+from __future__ import annotations
+
+DEFAULT_STOP_WORDS = {


Is this something specific to the firestore implementation? Should this be something we apply to all memory service?

DeanChensj · 2026-04-10T02:21:19Z

src/google/adk/integrations/firestore/firestore_session_service.py

+  """Session service that uses Google Cloud Firestore as the backend.
+
+  It creates a hierarchy in Firestore to hold events by user and session:
+  adk-session


what about app?

DeanChensj · 2026-04-10T02:29:15Z

tests/unittests/integrations/firestore/test_firestore_session_service.py

+
+
+@pytest.mark.asyncio
+async def test_list_sessions_with_user_id(mock_firestore_client):


Add a test that there are multiple apps, and only specific app is fetched?

DeanChensj · 2026-04-10T02:31:52Z

src/google/adk/integrations/firestore/firestore_session_service.py

+    if event.partial:
+      return event
+
+    self._apply_temp_state(session, event)


Also a test covering this?

DeanChensj · 2026-04-10T02:33:27Z

src/google/adk/integrations/firestore/firestore_memory_service.py

+        self._search_by_keyword(app_name, user_id, keyword)
+        for keyword in keywords
+    ]
+    results = await asyncio.gather(*tasks)


Add a test to verify that failures in parallel tasks are handled

DeanChensj · 2026-04-10T02:40:38Z

src/google/adk/integrations/firestore/firestore_session_service.py

+        else:
+          session_updates[key] = value
+
+      if app_updates:


The current append_event implementation updates App, User, and Session states across multiple independent transactions and batches. This lacks atomicity; if the final batch.commit() fails after the state transactions have finished, the storage layers will become desynchronized. Please wrap all related state and event updates into a single Firestore transaction to ensure consistency.

DeanChensj · 2026-04-10T02:41:27Z

src/google/adk/integrations/firestore/firestore_memory_service.py

+      has_updates = True
+
+    if has_updates:
+      await batch.commit()


This adds all session events to a single write batch without checking size. This will crash if a session exceeds Firestore's 500-operation limit. Please implement a batch-splitting mechanism similar to the 500-count logic already used in delete_session

ScottMansfield added 2 commits March 31, 2026 13:14

Oneshot attempt at adding firestore support for memory and sessions

96d1dca

Formatting and fixing the bucket name handling

d2d2231

adk-bot added the services [Component] This issue is related to runtime services, e.g. sessions, memory, artifacts, etc label Mar 31, 2026

ScottMansfield added 8 commits March 31, 2026 13:50

Correct imports for firestore

8312dc8

Add firestore to test dependencies

7760b70

Fix tests

b29afb7

Fix mypy errors

31ffb86

Undo unintended changes

565cc61

Sorting imports

9387cb3

Fix async mocks

03910e9

Fixing tests again again again

49c7bf5

ScottMansfield force-pushed the feat/firestore branch from e3f5d6a to 49c7bf5 Compare March 31, 2026 22:52

Merge branch 'main' into feat/firestore

bf77d28

rohityan self-assigned this Apr 1, 2026

ScottMansfield added 2 commits April 1, 2026 00:17

Empty commit

fbd16eb

Fixing one more test to use the firestore mock client

5645fe8

rohityan closed this Apr 1, 2026

rohityan added the community repo [Community] FRs/issues well suited for google/adk-python-community repository label Apr 1, 2026

rohityan reopened this Apr 3, 2026

rohityan removed the community repo [Community] FRs/issues well suited for google/adk-python-community repository label Apr 3, 2026

ScottMansfield added 5 commits April 9, 2026 09:18

Move firestore integration into integrations package

9d8bb5d

Merge branch 'main' into feat/firestore

49580f6

Updating session service to address various concerns

bf47b5c

These updates are derived from @anmolg1997 PR on the community repo: google/adk-python-community#104

pyink and isort

28a571e

Addressing mypy errors

7d0b4cc

ScottMansfield added 8 commits April 9, 2026 15:53

Addressing deprecation warnings for firestore query syntax

9a27b7e

Make memory actually work by implementing add_session_to_memory.

cb9e4d1

This creates a new memories collection to hold indexed events.

Formatting

1f01174

Remove unnecessary firestore runner

72cc9d2

Merge branch 'main' into feat/firestore

16a4a86

formatting

bef661c

Adding more detailed comments for both session and memory services

e18a1f8

Much improved unit tests

b652669

DeanChensj reviewed Apr 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat: Firestore support#5088

Feat: Firestore support#5088
ScottMansfield wants to merge 26 commits intogoogle:mainfrom
ScottMansfield:feat/firestore

ScottMansfield commented Mar 31, 2026 •

edited

Loading

Uh oh!

adk-bot commented Mar 31, 2026

Uh oh!

ScottMansfield commented Apr 1, 2026

Uh oh!

rohityan commented Apr 1, 2026

Uh oh!

rohityan commented Apr 3, 2026

Uh oh!

ScottMansfield commented Apr 9, 2026

Uh oh!

DeanChensj Apr 10, 2026

Uh oh!

DeanChensj Apr 10, 2026

Uh oh!

DeanChensj Apr 10, 2026

Uh oh!

DeanChensj Apr 10, 2026

Uh oh!

DeanChensj Apr 10, 2026

Uh oh!

DeanChensj Apr 10, 2026

Uh oh!

DeanChensj Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants



		@pytest.mark.asyncio
		async def test_list_sessions_with_user_id(mock_firestore_client):

Conversation

ScottMansfield commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Link to Issue or Description of Change

Testing Plan

Checklist

Uh oh!

adk-bot commented Mar 31, 2026

Uh oh!

ScottMansfield commented Apr 1, 2026

Uh oh!

rohityan commented Apr 1, 2026

Uh oh!

rohityan commented Apr 3, 2026

Uh oh!

ScottMansfield commented Apr 9, 2026

Uh oh!

DeanChensj Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

DeanChensj Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

DeanChensj Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

DeanChensj Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

DeanChensj Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

DeanChensj Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

DeanChensj Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ScottMansfield commented Mar 31, 2026 •

edited

Loading