🌤️ Weather-Style Multi-Agent Orchestrator

A professional, extensible template for building multi-agent systems using Google ADK, FastAPI, CopilotKit, SurrealDB, and MCP. This app demonstrates an "Orchestrator" pattern where a Supervisor agent coordinates specialist agents and local tools to give perfect fashion advice.

---

⚡ Quickstart (Under 5 Minutes)

Step	Action	Command / Details
1	Get Gemini API Key	Get a free key from Google AI Studio
2	Set Environment	Copy app/.env.template to app/.env and add your GOOGLE_API_KEY.
3	SurrealDB (Optional)	Add SURREAL_URL, USER, PASS to .env if using a real DB. (Mock data included!)
4	Install & Run	cd client && npm install && npm run dev
5	Chat!	Open http://localhost:3000 and ask: "What should I wear to a cocktail party in San Diego tonight?"

🪟 Windows Tips

• Environment: Set keys in PowerShell: $env:GOOGLE_API_KEY="your_key".
• Scripts: npm run dev is cross-platform via a Node.js wrapper.
• Python: Ensure python is in your PATH. The project uses uv for isolated dependency management.

---

🏗️ Architecture Overview

This template demonstrates how to build a Compound Agentic System where data flows between multiple specialized units.

1. The Multi-Agent Handoff

graph TD
    UI[Next.js + CopilotKit] -- SSE (AG-UI Protocol) --> API[FastAPI + ADK Agent]
    API --> Supervisor[Supervisor Agent]
    Supervisor -- Tool Call --> WeatherAgent[Weather Specialist]
    Supervisor -- Tool Call --> Database[FashionDatabase MCP Server]
    Database --> SurrealDB[(SurrealDB)]
    Supervisor -- Synthesis --> StyleAgent[Style Specialist]
    StyleAgent --> Gemini[Gemini 2.5 Flash]

2. Local MCP (Model Context Protocol) Discovery

The project uses an Embedded MCP Server (app/tools/db_server.py) powered by FastMCP.

• The Handshake: On startup, the Supervisor Agent launches the MCP server as a local subprocess. They communicate via JSON-RPC over stdio.
• Auto-Discovery: The Agent automatically "discovers" every function in db_server.py that is marked with the @mcp.tool() decorator.
• Semantic Abstraction: The Agent is not allowed to write raw SurrealQL. Instead, it uses high-level "Semantic Tools" (like get_trends_for_event). This makes the system more secure, easier to test, and resilient to LLM "hallucinations."

3. Communication: AG-UI & SSE

Communication between the browser and FastAPI is handled via a nested SSE (Server-Sent Events) relay.

• Browser ↔ Next.js: The browser connects to /api/copilotkit.
• Next.js ↔ FastAPI: Next.js proxies the request using the AG-UI Protocol.
• Streaming: This allows the Supervisor to stream its "thoughts" and intermediate tool results (like the Weather Card) back to the UI in real-time.

---

🛠️ NPM Commands (Run from /client)

Command	Description
npm run dev	Start Everything: Boots the FastAPI backend and Next.js frontend in parallel.
npm run seed:db	Pushes the synthetic fashion trends from /app/seed-data to your live SurrealDB.
npm run lint	Runs ESLint to check for code quality and style issues.
npm run build	Compiles the Next.js application for production.

---

🗄️ Database Setup (SurrealDB)

This project uses SurrealDB to store fashion trends. You have two ways to get up and running:

Option A: SurrealDB Cloud (Recommended)

1. Sign up for a free instance at surrealdb.com/cloud.
2. Create a Namespace (e.g., jupyhealth) and a Database (e.g., main).
3. Add your credentials to app/.env.

Option B: Local Docker (SurrealDB 3.0)

If you have Docker installed, run the following command to start a local instance:

docker run --pull always -p 8000:8000 surrealdb/surrealdb:latest start --user root --pass root

Creating a dedicated Agent User

To create a non-root user for this application (as seen in our .env), run this SurrealQL command in your SurrealDB console:

-- Replace 'agentuser' and 'your_password' with your desired values
DEFINE USER agentuser ON NAMESPACE PASSWORD 'your_password' ROLES OWNER;

Note: Once your database is running and configured in .env, run npm run seed:db from the client/ folder to populate it with trends!

---

⚙️ Customization Guide

How to add a new Tool to the Database

Want to give the Agent a new database power? It's as easy as adding a Python function:

1. Open app/tools/db_server.py.
2. Add a new function with the decorator:

   @mcp.tool()
   async def find_venue_dress_code(venue_name: str) -> str:
       # Your SurrealDB logic here...
       return "Formal"
   

3. The Supervisor Agent will automatically see this tool on the next restart!

How to rename the Agent

To change the agent's name from "my_agent", you must update it in three places:

1. Next.js Route: client/src/app/api/copilotkit/route.ts
2. Root Layout: client/src/app/layout.tsx
3. Main Page Hook: client/src/app/page.tsx

---

🎓 Why this exists

Most agent tutorials stop at the console or a Jupyter notebook. This template provides a functional frontend, a modular backend, and secure database integration so you can see how real-world agentic software is architected.

Happy Hacking! 🚀