--- title: "Capsules, Google Cloud Agents, and MongoDB Atlas" slug: "google-cloud-agents-mongodb-capsules" summary: "A deployment and access pattern for connecting authorized users and agents to MongoDB Atlas on Google Cloud through Capsule instructions, event provenance, and host-managed credentials." status: "draft" version: "0.1" updated: "2026-05-07" audience: - "cloud architects" - "agent builders" - "database teams" tags: - "google cloud" - "agents" - "mongodb" - "atlas" - "security" - "capsule" canonical_path: "/research/google-cloud-agents-mongodb-capsules" --- # Capsules, Google Cloud Agents, and MongoDB Atlas ## Connecting Authorized Users and Agents to a Cloud Database Through a Verifiable Work Artifact ### Abstract Google's current agent platform direction emphasizes managed agent runtime, sessions, memory, agent identity, gateways, tracing, logging, monitoring, evaluation, and secure connectivity. MongoDB Atlas on Google Cloud provides a managed document database, marketplace procurement, Google Cloud integrations, private endpoints through Private Service Connect, and vector search capabilities for AI applications. A Capsule can bridge those systems. It can carry the intent, schema contract, connection instructions, authorization requirements, tool wrapper, verification steps, and event history for a database-backed agent workflow. The Capsule should not carry secrets. It should carry the instructions and provenance that allow an authorized host to connect a user or agent to MongoDB Atlas safely. Related MOGO research artifacts are staged in [capsules-extra/MOGO/Research](https://github.com/virionai/capsules-extra/tree/main/MOGO/Research). --- ## 1. Current platform facts Google Cloud's agent documentation now redirects the older Vertex AI Agent Engine path into Gemini Enterprise Agent Platform material. The docs describe Agent Runtime for managed deployment and scaling, plus sessions, memory, code execution, governance, agent identity, agent gateway, tracing, logging, monitoring, and Private Service Connect interfaces. The ADK deployment docs describe deploying agents to Google Cloud Agent Runtime and Cloud Run. The Cloud Run path remains important because it lets teams host ordinary services and tool adapters that agents can call. MongoDB Atlas is available on Google Cloud and through Google Cloud Marketplace. MongoDB documents private endpoints for Atlas, including Google Cloud Private Service Connect, and Google Cloud documents a private-connectivity example for MongoDB Atlas through Integration Connectors. MongoDB Vector Search supports semantic, hybrid, and generative search use cases in Atlas. --- ## 2. Capsule role A MongoDB agent capsule can contain: - `program.md`: human-readable purpose, risk, setup, connect, query, verify, and handoff steps - `agents.md`: participant roles, authorization notes, and trust context - `manifest.json`: content index and skill trust metadata - `payload/db/schema.json`: collection names, expected document shapes, indexes - `payload/db/vector-index.json`: vector search index requirements if relevant - `payload/db/queries/*.json`: allowed query templates or aggregation pipelines - `payload/deploy/google-cloud.md`: host setup instructions - `payload/security/authorization.md`: who may connect and under what grant - `chain/events.jsonl`: connection, query, and deployment events - `skills/`: optional portable instructions for the agent host - `provenance/envelope.json`: signed package metadata and verification boundary The capsule becomes the deployment and access record. It does not become the database. --- ## 3. Authorized connection pattern The safe pattern is: 1. Capsule declares the desired database capability. 2. Human or policy grants access to an authorized user/agent. 3. Host obtains credentials using Google Cloud IAM, ADC, service account attachment, OAuth, or a secrets manager flow appropriate to the environment. 4. Host connects to MongoDB Atlas using the approved network path: public allowlist for development, private endpoint/Private Service Connect for controlled environments. 5. Agent issues only allowed queries or tool calls. 6. Host returns a structured result envelope. 7. Capsule appends a Pith-compressed event preserving the exact machine result under `llm_return`. The capsule never invents credentials. It can say what is required. The host decides whether the actor is authorized and supplies the credential. --- ## 4. Agent tool surface A minimal MongoDB capsule tool wrapper could expose: - `mongo_capability_check(capsule_ref)` - `mongo_connect_status(capsule_ref)` - `mongo_list_collections(capsule_ref)` - `mongo_find(capsule_ref, collection, filter, projection)` - `mongo_aggregate(capsule_ref, collection, pipeline_id)` - `mongo_vector_search(capsule_ref, index_id, query_vector, filter)` - `mongo_append_result_event(capsule_ref, result_envelope)` The agent should not receive a raw unrestricted MongoDB client. It should receive bounded tools whose permissions match the capsule plan and the user's authorization. --- ## 5. Google Cloud deployment sketch One practical architecture: - Agent built with ADK or another supported framework - Agent deployed to Agent Runtime or Cloud Run - Tool adapter deployed to Cloud Run or as part of the agent runtime - MongoDB Atlas cluster deployed on Google Cloud - Private connectivity through Private Service Connect where required - Secrets stored in Secret Manager or supplied through authorized runtime identity - Capsule stored in Cloud Storage, MongoDB, or passed directly as a `.capsule` file - Events appended after each meaningful query/deployment action The capsule is the control document. Google Cloud provides identity, runtime, networking, logs, and monitoring. MongoDB Atlas provides the database and vector/document query layer. The agent provides reasoning. The host adapter enforces permissions. --- ## 6. Why this matters Without the capsule, the connection between an agent and a database tends to live in code, secrets, dashboard settings, and chat instructions. That is difficult to audit. With a capsule, the task can say: - this is the data shape expected - this is the authorized actor - this is the allowed query surface - this is the network/credential assumption - this is what the agent did - this is what result it returned - this is what should happen next That is the bridge from database infrastructure to model collaboration. --- ## 7. Open questions - Should the capsule define a standard database capability schema? - Should query templates be hashed and whitelisted in the manifest? - Should private endpoint readiness be recorded as a capability grant event? - How should revoked database access be represented in an append-only chain? - Should vector indexes be treated as resources, output contracts, or capabilities? --- ## Related Capsules Extra lanes - [MOGO research artifacts](https://github.com/virionai/capsules-extra/tree/main/MOGO/Research) - [Hosted Capsules for Websites](https://github.com/virionai/capsules-extra/blob/main/use-cases/Hosted_Capsules_for_Websites.md) - [Data infrastructure examples](https://github.com/virionai/capsules-extra/tree/main/capsule-examples/public/data-infra) ## Sources reviewed - Gemini Enterprise Agent Platform scale/runtime docs: https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale - ADK Agent Runtime deployment docs: https://adk.dev/deploy/agent-runtime/deploy/ - ADK Cloud Run deployment docs: https://adk.dev/deploy/cloud-run/ - Google Cloud IAM authentication docs: https://docs.cloud.google.com/iam/docs/authentication - MongoDB Atlas on Google Cloud: https://www.mongodb.com/products/platform/atlas-cloud-providers/google-cloud - MongoDB Atlas private endpoints with Google Cloud Private Service Connect: https://www.mongodb.com/docs/atlas/security-private-endpoint/?cloud-provider=gcp - Google Cloud private connectivity example for MongoDB Atlas: https://docs.cloud.google.com/integration-connectors/docs/connectors/mongodb/configure-psc-mongodb - MongoDB Vector Search overview: https://www.mongodb.com/docs/vector-search/