feat(integrations): add MongoDB-backed session and memory services

[theshanbhag]

Add MongoDbSessionService, which persists sessions, events, and app:/user:-scoped state in MongoDB with optimistic-concurrency revisions and multi-document transactions (with a cached fallback to sequential writes on deployments without transaction support), and MongoDbMemoryService, which ingests session events into a keyword-indexed memory collection for long-term recall.

The search tools now support both embedding modes: Google embedding models via the genai client (default, queryVector), and Atlas Automated Embedding (Preview), where MongoDbToolSettings.use_mongodb_auto_embedding sends the query as plain text (query.text) and Atlas embeds it with the index's Voyage AI model — no Google embedding credentials needed.

MongoDbToolset, MongoDbSessionService, and MongoDbMemoryService are picklable when constructed with connection_string, so agents using them deploy cleanly to Agent Engine (which packages apps with cloudpickle): the client is dropped at pickle time and rebuilt on the runtime. The MONGODB_* experimental feature flags are dropped; the integration is always on.

The integration README documents the embedding modes, optional secondary indexes (ensure_indexes), Agent Engine deployment, and a required-permissions (least-privilege) section — including the fact that the model chooses the collection at run time, with a before_tool_callback allowlist example. mongomock is added to the test dependencies for the new unit tests.

NO_UNIT_GUIDE=The integration README added in this change documents all MongoDB units; per-unit guides will follow when the API stabilizes.

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: #issue_number
• Related: #issue_number

2. Or, if no issue exists, describe the change:

Problem:

ADK's MongoDB integration provided search tools only: no MongoDB-backed session or memory persistence, and no way to deploy agents using them to Agent Engine, where apps cross a cloudpickle boundary that a live pymongo.MongoClient (sockets, locks, background threads) cannot survive. Query embedding also required Google embedding credentials even when the Atlas cluster could embed queries itself.

Solution:

• Add MongoDbSessionService (sessions, events, and app:/user:-scoped state with optimistic-concurrency revisions; multi-document writes run in transactions where the deployment supports them, with per-session locking and a cached fallback otherwise) and MongoDbMemoryService (keyword-indexed long-term recall with idempotent ingestion).
• Add Atlas Automated Embedding support via MongoDbToolSettings.use_mongodb_auto_embedding / mongodb_auto_embedding_model, alongside the default Google embedding mode.
• Make the toolset and both services picklable: constructed with connection_string, they drop the live client at pickle time and rebuild it on the destination, so Agent Engine deployments work unchanged.
• Document embedding modes, ensure_indexes, Agent Engine deployment, and least-privilege database setup (read-only search user vs. read-write state user, per-collection scoping, and a before_tool_callback collection allowlist).

Testing Plan

Unit Tests:

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

pytest tests/unittests/integrations/mongodb/ tests/unittests/features/ → 126 passed (98 MongoDB integration tests, mongomock-backed: search tools in both embedding modes, toolset exposure/injection, pickle round-trips, session-service transactions and fallback, memory-service recall/idempotency; plus the 28 feature-registry tests). All pre-commit hooks (pyink, isort, ruff, mdformat, codespell, compliance checks) pass.

Manual End-to-End (E2E) Tests:

Verified against a live MongoDB Atlas cluster seeded with a 10-product catalog (products with an autoEmbed vector index, products_google with text-embedding-005 embeddings under a regular vector index, both with a full-text index):

1. mongodb_vector_search and mongodb_hybrid_search in Atlas auto-embedding mode return ranked, filtered results with search_score (e.g. "cordless robot vacuum for pet hair" ranks "Robot Vacuum Pro" first; a category filter restricts hits).
2. The same searches in Google embedding mode (query embedded with Vertex AI text-embedding-005) return equivalent rankings.
3. Session create/append/get/list/delete with app:/user:-scoped state round-trips, and memory ingest + keyword recall works per user without duplication on re-ingest.
4. Agent Engine packaging: pickle.loads(pickle.dumps(root_agent)) round-trips the agent → toolset chain with tools intact and clients rebuilt.

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.

Additional context

Wiring MongoDbSessionService / MongoDbMemoryService into Agent Engine deployments directly (as managed-service alternatives) is planned for a follow-up; today Agent Engine deployments use the managed Vertex AI session and memory services, while the MongoDB services back self-hosted runners (adk run, adk web, Cloud Run).

[theshanbhag]

Add MongoDbSessionService, which persists sessions, events, and app:/user:-scoped state in MongoDB with optimistic-concurrency revisions and multi-document transactions (with a cached fallback to sequential writes on deployments without transaction support), and MongoDbMemoryService, which ingests session events into a keyword-indexed memory collection for long-term recall.

The search tools now support both embedding modes: Google embedding models via the genai client (default, queryVector), and Atlas Automated Embedding (Preview), where MongoDbToolSettings.use_mongodb_auto_embedding sends the query as plain text (query.text) and Atlas embeds it with the index's Voyage AI model — no Google embedding credentials needed.

MongoDbToolset, MongoDbSessionService, and MongoDbMemoryService are picklable when constructed with connection_string, so agents using them deploy cleanly to Agent Engine (which packages apps with cloudpickle): the client is dropped at pickle time and rebuilt on the runtime. The MONGODB_* experimental feature flags are dropped; the integration is always on.

The integration README documents the embedding modes, optional secondary indexes (ensure_indexes), Agent Engine deployment, and a required-permissions (least-privilege) section — including the fact that the model chooses the collection at run time, with a before_tool_callback allowlist example. mongomock is added to the test dependencies for the new unit tests.

NO_UNIT_GUIDE=The integration README added in this change documents all MongoDB units; per-unit guides will follow when the API stabilizes.

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: #issue_number
• Related: #issue_number

2. Or, if no issue exists, describe the change:

Problem:

ADK's MongoDB integration provided search tools only: no MongoDB-backed session or memory persistence, and no way to deploy agents using them to Agent Engine, where apps cross a cloudpickle boundary that a live pymongo.MongoClient (sockets, locks, background threads) cannot survive. Query embedding also required Google embedding credentials even when the Atlas cluster could embed queries itself.

Solution:

• Add MongoDbSessionService (sessions, events, and app:/user:-scoped state with optimistic-concurrency revisions; multi-document writes run in transactions where the deployment supports them, with per-session locking and a cached fallback otherwise) and MongoDbMemoryService (keyword-indexed long-term recall with idempotent ingestion).
• Add Atlas Automated Embedding support via MongoDbToolSettings.use_mongodb_auto_embedding / mongodb_auto_embedding_model, alongside the default Google embedding mode.
• Make the toolset and both services picklable: constructed with connection_string, they drop the live client at pickle time and rebuild it on the destination, so Agent Engine deployments work unchanged.
• Document embedding modes, ensure_indexes, Agent Engine deployment, and least-privilege database setup (read-only search user vs. read-write state user, per-collection scoping, and a before_tool_callback collection allowlist).

Testing Plan

Unit Tests:

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

pytest tests/unittests/integrations/mongodb/ tests/unittests/features/ → 126 passed (98 MongoDB integration tests, mongomock-backed: search tools in both embedding modes, toolset exposure/injection, pickle round-trips, session-service transactions and fallback, memory-service recall/idempotency; plus the 28 feature-registry tests). All pre-commit hooks (pyink, isort, ruff, mdformat, codespell, compliance checks) pass.

Manual End-to-End (E2E) Tests:

Verified against a live MongoDB Atlas cluster seeded with a 10-product catalog (products with an autoEmbed vector index, products_google with text-embedding-005 embeddings under a regular vector index, both with a full-text index):

1. mongodb_vector_search and mongodb_hybrid_search in Atlas auto-embedding mode return ranked, filtered results with search_score (e.g. "cordless robot vacuum for pet hair" ranks "Robot Vacuum Pro" first; a category filter restricts hits).
2. The same searches in Google embedding mode (query embedded with Vertex AI text-embedding-005) return equivalent rankings.
3. Session create/append/get/list/delete with app:/user:-scoped state round-trips, and memory ingest + keyword recall works per user without duplication on re-ingest.
4. Agent Engine packaging: pickle.loads(pickle.dumps(root_agent)) round-trips the agent → toolset chain with tools intact and clients rebuilt.

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.

Additional context

Wiring MongoDbSessionService / MongoDbMemoryService into Agent Engine deployments directly (as managed-service alternatives) is planned for a follow-up; today Agent Engine deployments use the managed Vertex AI session and memory services, while the MongoDB services back self-hosted runners (adk run, adk web, Cloud Run).

[wukath]

Thanks for the thorough PR, @theshanbhag!

This is too big for us to review as one change: it's four separate features in about 2.4k lines. Could you split it into separate PRs that we can review and land one at a time? Roughly:

• Atlas auto-embedding: use_mongodb_auto_embedding / mongodb_auto_embedding_model and the _search_tool.py changes.
• Picklable toolset: the getstate/setstate support on MongoDbToolset for Agent Engine deployment.
• MongoDbSessionService
• MongoDbMemoryService

Some other notes:

• Please keep the MONGODB_TOOLSET / MONGODB_TOOL_SETTINGS feature flags. Graduating the integration out of experimental is a separate decision for the maintainers, and it shouldn't ride along with a feature change. New classes should also start out experimental.
• Session service: the transaction fallback, the per-session locks and the revision checks add up to a lot of concurrency logic. In the split PR, could you explain which deployment types you're targeting? Please also cover how the in-process lock behaves with several runner replicas writing to the same session, since revision checks are the only cross-process guard.
• Memory service: retrieval is keyword-only right now. Do you plan to use vector search here, given the integration already supports it? If keyword matching is intentional, please say so in the PR description.
• Agent Engine: the README says the session and memory services can't yet be used on Agent Engine. In that case, could pickling support for the services move into the follow-up that adds Agent Engine wiring?

Happy to review each piece as it comes in.