AddressPilot AI

AddressPilot AI — AI-powered shipping address verification, correction, and risk detection before labels are printed.

Comment

AddressPilot AI

Live demo: https://addresspilot-ai-767656572248.us-central1.run.app
Code: https://github.com/zaiyiqi0604/addresspilot-ai

Inspiration

The idea came from real ecommerce shipping work: generating labels for customer orders and watching a surprising share of deliveries fail because of small address mistakes—missing unit numbers, postcode/state mismatches, odd abbreviations, or incomplete street lines.

Most shipping tools only check basic formatting. They rarely explain why an address is risky, or help a merchant fix it with confidence before printing a label. I wanted to see whether an AI agent could support that operational workflow—not as a chatbot, but as a copilot with clear reasoning, visible risk, and a safe path to action.

That question led to AddressPilot AI for the Google Cloud Rapid Agent Hackathon (MongoDB track): an agent that verifies addresses, gates risky output, and only writes to the database after explicit human approval.

What It Does

AddressPilot AI is a shipping safety agent for Australian addresses. It:

  1. Accepts input — paste an address or bulk-import CSV order data
  2. Verifies with an ADK agent — a Google ADK LlmAgent on Vertex AI (Gemini) analyzes structure, locality, and delivery risk
  3. Surfaces reasoning — risk level, confidence score, notes, and highlighted before/after formatting
  4. Applies a safety policy — if locality confidence is low or the suburb cannot be verified, the app withholds a ship-ready corrected label and blocks approval
  5. Requires human approval — the merchant must explicitly approve before any side effect
  6. Persists an audit trail — on approve, the app calls the official MongoDB MCP Server to insert-many into MongoDB Atlas (verification_audit)

The flow is intentionally Plan → Verify → Policy Gate → Human Approval → MCP Action, so AI assists without silently changing production data.

Example confidence framing (simplified):

$$ \text{Confidence} \approx 100 - (35 \times H) - (15 \times M) - (5 \times L) $$

where $H$, $M$, and $L$ are high-, medium-, and low-severity issues. Results map to bands like SAFE, ATTENTION, and HIGH RISK, with UI behavior tied to those bands—not just a numeric score in isolation.

How We Built It

Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS — mission-control UI with workflow steps, diff highlighting, CSV import, and dark mode.

Agent layer: Google ADK with structured JSON output from Gemini on Vertex AI. Verification runs through POST /api/verify-address with hackathon strict mode so judges can confirm meta.engine = adk and meta.authMode = vertex.

Human-in-the-loop partner action: POST /api/agent-action runs only after UI approval. Our server spawns the MongoDB MCP Server over stdio (Model Context Protocol), waits for Atlas auto-connect, then writes audit documents with runId, inputHash, risk metadata, and timestamp.

Deployment: Google Cloud Run (Docker + Node 20), with MongoDB URI in Secret Manager so judges can use a public HTTPS URL without exposing credentials.

Design choices that mattered for judges and users:

  • Visible agent reasoning instead of a black-box “valid/invalid” flag
  • Policy before persistence — no MongoDB write unless the human approves and safety rules pass
  • Partner integration that is real, not mocked — MCP insert-many into Atlas, inspectable after demo

Challenges

1. Balancing rules and AI reasoning
Some address issues are rule-like (postcode format); others need context (abbreviations, locality ambiguity). We combined structured ADK output with explicit withhold behavior when the model should not guess.

2. Making it feel like an agent, not a form
We invested in workflow visualization, confidence meters, highlighted diffs, and a deliberate approve step so users see what the agent did and when it is allowed to act.

3. Production-grade MCP on Cloud Run
The MongoDB MCP child process was fragile at first: connection string env handling, container startup paths, auto-connect races, and Atlas network access for Cloud Run egress (not judge IPs). Fixes included a dedicated MCP launcher script, Secret Manager for the URI, polling the MCP debug://mongodb resource, and Atlas 0.0.0.0/0 for the demo window.

4. Safety over flashy automation
The most important lesson: for operational workflows, value comes from trustworthy guardrails—withholding uncertain corrections and requiring approval—more than from maximizing autonomous writes.

What I Learned

Shipping errors are a strong agent use case because they are repetitive, costly, and workflow-shaped. The hackathon pushed us to connect Gemini + ADK + Vertex with a real partner MCP and persistent audit data in MongoDB Atlas. The result is not just “AI validated my address”—it is an auditable, human-approved agent workflow merchants could actually use before printing a label.

Built With

Share this project:

Updates