Northstar Resolve

Inspiration

Retail inventory systems can report that a product is available while the shelf is empty. The resulting task is deceptively complex: staff must check current inventory, search prior cases, distinguish replenishment delays from inventory errors, choose a response, assign an owner, and preserve evidence. I wanted an agent that completes that operational loop instead of producing another recommendation that someone must manually execute.

What it does

Northstar Resolve accepts a shelf-stock discrepancy from a store manager. The agent reads current store, product, and inventory context from MongoDB, retrieves similar historical incidents, and uses Gemini through Google ADK to classify severity and choose the next action.

It then creates both an incident and an assigned duty-manager action in MongoDB Atlas through the official MongoDB MCP Server. The agent reads both records back and reports success only when they exist.

The hosted interface includes a live product workflow and a technical proof view showing sanitized tool calls, record IDs, model usage, estimated cost, and read-back verification.

How we built it

The Next.js interface and FastAPI agent service run on Google Cloud Run. The agent is orchestrated with Google ADK and uses Gemini 2.5 Flash through Vertex AI. The official MongoDB MCP Server 1.12.0 runs beside the agent over stdio and connects to MongoDB Atlas M0.

Google Secret Manager supplies the Atlas connection string to a dedicated Cloud Run service account. Cloud Build creates the frontend and API images, and Artifact Registry stores them. Both Cloud Run services scale to zero and have a one-instance ceiling for cost control.

All retail records are deterministic synthetic data.

Challenges we ran into

The largest challenge was not model prompting; it was understanding the boundaries between products and credentials. Google Cloud ADC, Cloud Run service identities, Secret Manager, Atlas website accounts, and Atlas database users are separate concepts.

Cloud Run also does not provide a stable outbound IP by default. Local Atlas access worked, but the deployed agent was blocked until Atlas Network Access was adjusted for the prototype. A production design would use VPC egress, Cloud NAT, and a reserved static IP.

I also discovered that an MCP stdio cleanup error could replace a successful API result with HTTP 500 after the database writes had already completed. I fixed the lifecycle handling and documented the need for idempotency keys so a retry cannot create duplicate external state.

Accomplishments that we're proud of

• Deployed a real ADK agent using Gemini on Google Cloud.
• Used the official MongoDB MCP server for reads, writes, and verification.
• Persisted incidents and assignments in Atlas and read them back.
• Added technical evidence without exposing private chain-of-thought or secrets.
• Added per-run token usage and estimated Gemini cost.
• Kept the hosted prototype on scale-to-zero infrastructure and Atlas M0.

What we learned

A credible agent demo must prove more than a generated answer. It should expose the evidence it used, change external state, and verify that state before claiming success.

I also learned that infrastructure setup and cost uncertainty are major barriers to experimentation. Small controls such as scale-to-zero limits, project budgets, synthetic data, restricted database permissions, and per-request estimates made it possible to iterate with confidence.

What's next for Northstar Resolve

• Add idempotency keys and an atomic case-write strategy.
• Use controlled static outbound networking for Atlas.
• Expand from one flagship product to store-wide discrepancy prioritization.
• Add receiving and back-room evidence as separate operational signals.

Built With

• artifact-registry
• cloud-build
• cloud-run
• fastapi
• gemini-2.5-flash
• google-adk
• mongodb-atlas
• mongodb-mcp-server
• next.js
• python
• react
• secret-manager
• typescript
• vertex-ai