nexuschain-ai-navigator

NexusChain AI Navigator — a serverless multi-agent system built on Google AI Studio and Cloud Run that transforms complex supply chain data into real-time, actionable intelligence.

Comment

Inspiration

Supply chains are complex, interconnected systems where small disruptions can cascade rapidly. We were inspired by the idea of a unified, automated assistant that can reason across multiple supply chain domains (sourcing, manufacturing, inventory, logistics, returns) and produce a concise, actionable report for a human decision-maker.

Two concrete drivers:

  • The need for fast, explainable analysis across heterogeneous data sources (public market data, ERP extracts, telemetry).
  • The rise of agentic AI patterns and serverless platforms (ADK + Cloud Run) that enable composable, scalable AI workflows.

This project is an attempt to combine modern LLM-powered tooling, structured data (BigQuery), and serverless deployment to deliver practical supply chain intelligence.

What it does

NexusChain AI Navigator accepts a high-level supply-chain query and returns a structured, JSON-schema-compliant report. The flow (high level):

  1. User submits a query via the Next.js UI.
  2. The Manager Agent (ADK) plans a multi-step workflow and selects specialist agents as tools.
  3. Each specialist agent executes focused research or analysis using web search, internal heuristics, and (optionally) BigQuery data.
  4. The Manager synthesizes agent outputs into a final report, which is returned to the UI and can be downloaded as a PDF.

Key features:

  • Multi-agent orchestration (ADK + Genkit)
  • Data integration with BigQuery and Cloud Storage
  • Optional GPU-accelerated inference (NVIDIA L4) for heavier models
  • Deployable, horizontally scalable services on Google Cloud Run

Success criteria we targeted:

  • Correctness of the agent pipeline (produces a coherent report)
  • Reproducible deployments to Cloud Run
  • Low-latency responses for interactive demos

How we built it

This section explains the architecture, the main components, and the engineering decisions.

Technology stack

  • Frontend: Next.js (React) + Tailwind CSS — fast interactive UI and SSR when needed.
  • Agent framework: Genkit + ADK patterns for tool-based agents.
  • Hosting: Google Cloud Run (serverless services and jobs), region europe-west4 for GPU availability.
  • Data: BigQuery for analytics and Cloud Storage for artifacts.
  • Models: Google Gemini (via googleai/gemini-2.0-flash), Vertex AI where appropriate.

Code organization (key files)

  • src/app/ — Next.js application and UI components
    • src/components/main-page.tsx — main query interface
    • src/components/report-display.tsx — report renderer
  • src/ai/flows/main-query-flow.ts — Manager Agent entry point (planning, scheduling, synthesis)
  • src/ai/flows/ — additional flows: task distribution, synthesis helpers
  • src/ai/agents/ — specialist agents (sourcing, manufacturing, inventory, delivery, returns, anomaly detection)
  • src/services/bigquery.ts — BigQuery helper (mocked during demo; replace with client for production)
  • src/ai/genkit.ts — Genkit/ADK configuration and model bindings
  • apphosting.yaml — Firebase hosting config (optional)

Manager Agent & Subagents

This project is centered around a single Manager Agent (the orchestrator) that plans workflows and invokes several specialist subagents to execute focused tasks. Below are technical details, file locations, responsibilities, and the small, strict contract each agent uses to remain composable.

Manager Agent (Orchestrator)

  • File Location: src/ai/flows/main-query-flow.ts
  • Responsibilities:
    • Parse the high-level user query and produce a plan consisting of ordered tasks.
    • Select which specialist subagents (tools) to call based on the plan.
    • Aggregate and validate structured responses from subagents.
    • Synthesize the final JSON-schema-compliant report returned to the frontend.
  • Runtime Settings:
    • Longer timeout (e.g., 900s) and higher memory (4Gi) when deployed to Cloud Run.
    • Environment variables: GEMINI_API_KEY, PROJECT_ID, and monitoring flags.
  • Input / Output Contract:
    • Input: {query: string, context?: object, constraints?: object}
    • Output: A structured report object (see example schema below).

Specialist Subagents (Files & Roles)

Each subagent implements a small, consistent interface (a Genkit tool) so the Manager can call them interchangeably. The contract requires returning a JSON object with {summary, confidence, details}.

  • src/ai/agents/sourcing-agent.ts

    • Role: Supplier discovery, pricing signals, lead-time estimates.
    • Uses web sources + BigQuery lookups for historical pricing trends.

  • src/ai/agents/manufacturing-agent.ts

    • Role: Production constraints, capacity planning, quality issues.
    • Runs heuristics and consults model-based risk predictors.

  • src/ai/agents/inventory-agent.ts

    • Role: Stock-level analysis, reorder suggestions, safety stock calculations.
    • Integrates with BigQuery-simulated inventory tables.

  • src/ai/agents/delivery-agent.ts

    • Role: Routing, carrier performance, ETA predictions, disruption impact.
    • Interfaces with route-planning utilities and latency predictors.

  • src/ai/agents/returns-agent.ts

    • Role: Reverse logistics, return rates, cost-to-serve analysis.

  • src/ai/agents/planning-agent.ts

    • Role: Demand forecasting, market trend correlation, scenario simulation.

  • src/ai/agents/anomaly-detection-agent.ts

    • Role: Monitor streaming metrics, detect outliers in price or lead time.

Agent Interface Example (JSON)

{
   "summary": "Sourcing: identified 3 qualified suppliers for lithium batteries, avg lead-time 12 weeks",
   "confidence": 0.82,
   "details": {
      "suppliers": [
         {"name": "Supplier A", "country": "KR", "lead_time_weeks": 10, "price_usd": 12.5},
         {"name": "Supplier B", "country": "CN", "lead_time_weeks": 14, "price_usd": 11.8}
      ],
      "data_sources": ["bigquery:supply_chain.supplier_prices","web:trade-db"]
   }
}

Validation & Reconciliation

The Manager applies a small validation layer that checks each subagent's confidence and details fields, and can request re-runs if the confidence is below a threshold. The Manager also merges agent outputs into a canonical report structure before synthesis to preserve traceability and auditability.

Extension Points

  • Add new subagents by creating a Genkit tool that returns the same {summary,confidence,details} shape and registering it in src/ai/flows/main-query-flow.ts.
  • For heavy ML tasks, subagents may call the ml-inference GPU service via src/services/gpu-manager.ts to offload model inference.

Deployment strategy

We used Cloud Run because it provides:

  • Rapid deployments (gcloud run deploy ... --source)
  • Autoscaling to zero for cost efficiency
  • GPU options (NVIDIA L4) for inference-heavy workloads

Services we deploy separately for clarity and scaling:

  • nexuschain-frontend — Next.js UI
  • manager-agent — orchestrator service (longer timeout, more memory)
  • *-agent services — specialized agent jobs/services
  • ml-inference — GPU-attached inference service

Deployment configuration examples are included in README.md under Deployment Guide.

Engineering tradeoffs

  • We kept agents lightweight and stateless where possible so Cloud Run can scale them independently.
  • For heavy ML batches we route requests to a GPU-backed ml-inference service to control costs and maintain low latency for interactive agents.
  • We used local mocks for BigQuery during development to simplify the demo; production requires setting up IAM and a real dataset.

A short math model for expected cost per query

We estimate cost per query using a simplified model:

$$ C_{query} = c_{frontend} \cdot t_{frontend} + c_{manager} \cdot t_{manager} + \sum_{i=1}^{N} (c_{agent_i} \cdot t_{agent_i}) + c_{gpu} \cdot t_{gpu} $$

Where:

  • $c_*$ are per-second costs for CPU/GPU resources
  • $t_*$ are durations of each component
  • $N$ is the number of specialist agents used by the plan

This helps us tune min-instances, memory and CPU for each Cloud Run service to hit a target cost-per-query while respecting latency constraints.

Challenges we ran into

  1. Agent Reasoning & Consistency

    • Keeping multiple agents aligned on the same facts was non-trivial. We solved this by defining a shared intermediate schema and forcing agents to return structured sub-objects (e.g., {summary,confidence,details}) that the Manager can validate and reconcile.

  2. Latency vs. Depth

    • Deep analysis (web research + BigQuery joins + model-heavy inference) increases latency. We introduced progressive disclosure: agents return a short summary first and a detailed report asynchronously. The UI shows updates in real time.

  3. Cloud Run GPU constraints

    • GPU support on Cloud Run has region constraints and quota limitations. We designed the pipeline to only call GPU-backed inference for heavy operations and used smaller models for quick iterations.

  4. Data privacy and mocked data

    • Demo used mocks for BigQuery to avoid working with sensitive company data. Integrating with real datasets requires IAM, dataset design, and careful access controls.

Accomplishments that we're proud of

  • Implemented a full ADK-style multi-agent orchestration that produces structured reports.
  • Built a reproducible, serverless deployment model using Cloud Run and documented it end-to-end in README.md.
  • Created a small, performant frontend that shows progressive results and allows export to PDF.
  • Demonstrated GPU-accelerated inference integration and measured end-to-end latencies under demo workloads.

What we learned

  • Agentic architectures are powerful but require strict contracts (schemas) between agents and the orchestrator to keep outputs composable and verifiable.
  • Serverless is a great fit for bursty, prototype workloads — but productionizing a multi-agent system requires careful attention to cold starts, timeouts, and idempotency.
  • Using a mix of cheap CPU-backed services for orchestration and GPU-backed services for heavy inference is a cost-effective balance.

What's next for NexusChain AI Navigator

Short-term:

  • Replace BigQuery mocks with real dataset queries and add automated ingestion pipelines.
  • Add role-based access controls for enterprise deployments and secure the service account permissions.
  • Polish demo UX: add export templates, richer charts, and explainability traces for each agent decision.

Medium-term:

  • Implement hierarchical agent planning: a higher-level planner that composes sub-plans and delegates to agent clusters to better parallelize work.
  • Add more advanced model explainability, integrate Vertex Explainable AI tooling, and add counterfactual analysis.
  • Add realtime telemetry and anomaly streaming via Pub/Sub or Workflows for continuous monitoring.

Long-term:

  • Support on-premise connectors for enterprises that cannot move data to the cloud.
  • Build a marketplace of domain-specific specialist agents that can be plugged into the Manager.

Built With

Share this project:

Updates

Submission history