Repository navigation
feat(integrations): add MongoDB-backed session service - #7511
Closed
theshanbhag wants to merge 8 commits into
Closed
theshanbhag wants to merge 8 commits into
theshanbhag wants to merge 8 commits into
Conversation
Add `use_mongodb_auto_embedding` and `mongodb_auto_embedding_model` to MongoDbToolSettings. When enabled, the search tools send the query as plain text (`query.text`) instead of embedding it through the genai client first: Atlas generates the embedding itself with the Voyage AI model configured on the index's `autoEmbed` field (Atlas Automated Embedding, Preview), so deployments that already store data on Atlas need no Google embedding credentials. The default mode (Google embedding models via `queryVector`) is unchanged. Split from google#7291.
MongoDbSessionService persists sessions, events, and app:/user:-scoped state in MongoDB, exported from google.adk.integrations.mongodb behind the MONGODB_SESSION_SERVICE experimental feature (default on). Concurrency model: within a process a per-session lock serializes append_event; across runner replicas the optimistic-concurrency revision on the session document is the only guard, and the losing writer gets StaleSessionError. Multi-document writes run in a transaction on replica sets / sharded clusters / Atlas; on deployments without transaction support (standalone mongod) the verdict is cached and writes fall back to sequential with the revision check. Optional `ensure_indexes` creates the recommended secondary indexes on first use. mongomock joins the test dependencies for the new unit tests. NO_UNIT_GUIDE=The integration README documents the service, including its document layout, concurrency model, and least-privilege setup; a per-unit guide will follow when the experimental API stabilizes. Split from google#7291.
9 tasks done
This was referenced Oct 12, 2026
…b-session-service # Conflicts: # constraints-3.11.txt # constraints-3.12.txt # constraints-3.13.txt # constraints-3.14.txt
…n MongoDbSessionService Review follow-up from google#7533: list_sessions fetched each user's state with a separate find_one per user (N+1); it now issues a single $in query against the user_states collection. Index creation on first use is also serialized with a thread lock (double-checked flag), so concurrent first calls no longer issue duplicate create_index calls. Addresses gemini-code-assist review comments on google#7533.
…b-session-service # Conflicts: # docs/guides/integrations/mongodb/mongodb_toolset/index.md # src/google/adk/integrations/mongodb/README.md # tests/unittests/integrations/mongodb/test_search_tool.py
These local-only sample/utility files (mongodb_samples/, .codegraph/, setup_mongodb_sample.py) were never meant to be committed; a git add -A in the merge commit included them by mistake. They stay on disk, just untracked again.
copybara-service Bot
pushed a commit
that referenced
this pull request
Oct 22, 2026
Merge #7511 Adds `MongoDbSessionService` under `google.adk.integrations.mongodb` behind `FeatureName.MONGODB_SESSION_SERVICE` to persist sessions, events, and `app:` / `user:` / session-scoped state in MongoDB. PiperOrigin-RevId: 1005083413
Collaborator
|
Thank you @theshanbhag for your contribution! 🎉 Your changes have been successfully imported and merged via Copybara in commit 9833835. Closing this PR as the changes are now in the main branch. |
adk-bot
pushed a commit
that referenced
this pull request
Oct 22, 2026
Merge #7511 Adds `MongoDbSessionService` under `google.adk.integrations.mongodb` behind `FeatureName.MONGODB_SESSION_SERVICE` to persist sessions, events, and `app:` / `user:` / session-scoped state in MongoDB. PiperOrigin-RevId: 1005083413
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
MongoDbSessionService: sessions, events, andapp:/user:/ session-scoped state persisted in MongoDB, exported fromgoogle.adk.integrations.mongodbbehind the newMONGODB_SESSION_SERVICEexperimental feature (default on, matching the integration's existing flags).Split 3 of 4 from #7291 (reviewer-requested split). #7509 has landed on main; this PR now diffs cleanly against it.
Please ensure you have read the contribution guide before creating a pull request.
Link to Issue or Description of Change
Problem:
ADK's MongoDB integration provides search tools only; persisting sessions in MongoDB requires a custom service.
Solution:
MongoDbSessionServicestores one document per session (<app>/<user>/<session>, with an optimistic-concurrencyrevision), one per event, and one per app/user state bucket (JSON-encoded so./$in state keys round-trip).ensure_indexes=Trueoptionally creates the two recommended secondary indexes (app_user_session_tson events,app_useron sessions).Deployment targets (reviewer question on #7291): the service targets replica sets, sharded clusters, and Atlas, where every multi-document write (state buckets + revision bump + event insert) runs in a transaction so concurrent writers cannot lose each other's state updates. On deployments without transactions (standalone mongod), the first write's failure verdict is cached and later writes run sequentially with the revision check — the fallback exists for local development, not for production scale-out.
Concurrency across runner replicas (reviewer question on #7291): the per-session
asyncio.Lockis deliberately in-process — it only serializes appends within one runner. With several runner replicas writing to the same session, the revision check on the session document is the only cross-process guard: the losing writer getsStaleSessionError, reloads, and retries. This is now documented in the README's "Concurrency model and deployment targets" section.Not in this PR, per the #7291 review: pickling for Agent Engine (comes with the follow-up that wires the services into Agent Engine) — today the service backs self-hosted runners (
adk run,adk web, Cloud Run).NO_UNIT_GUIDE=The integration README documents the service, including its document layout, concurrency model, and least-privilege setup; a per-unit guide will follow when the experimental API stabilizes.
Testing Plan
Unit Tests:
pytest tests/unittests/integrations/mongodb/ tests/unittests/features/→ 110 passed (mongomock-backed): create/get/list/delete, scoped state merge, revision conflicts (StaleSessionError), transaction fallback with cached verdict, index creation, and feature-registry tests. All pre-commit hooks pass.mongomockis added to the test dependencies (constraints regenerated).Manual End-to-End (E2E) Tests:
Against a live Atlas 8.0.34 cluster: session create/append/get/list/delete with
app:/user:-scoped state deltas round-trip correctly, and a concurrent-writer run confirmed the losing append raisesStaleSessionErrorrather than silently overwriting.Checklist