🍳 Multi-Agent Recipe, Shopping & Wallet System (ADK + MCP)

This project implements a stateful, multi-agent system using Google ADK and exposes selected capabilities via an MCP server so multiple users (or agents) can interact with each other’s agents.

The system supports:

• Recipe recommendation
• Ingredient shopping planning
• Wallet-based checkout simulation
• Agent-to-agent access using MCP

---

🧠 Architecture Overview

Core Design Principles

• RootAgent is a pure orchestrator (no tools)
• Sub-agents own tools and logic
• Stateful tools manage selections, pantry, and wallet
• Stateless tools handle extraction, search, ranking
• SequentialAgent is used where execution order matters (checkout)

Agents

Agent	Responsibility
RootAgent	Routes user intent to the correct sub-agent
RecipeAgent	Extracts preferences, searches & recommends recipes
ShoppingAgent	Computes missing ingredients & shopping plans
WalletPayAgent	Simulates wallet payment lifecycle
CheckoutFlow	Sequential flow: Shopping → Wallet

---

📁 Project Structure

your_project/
├── agents/
│   ├── root_agent.py
│   ├── recipe_agent.py
│   ├── shopping_agent.py
│   ├── wallet_agent.py
│   └── checkout_flow.py
│
├── tools/
│   ├── recipe_tools.py
│   ├── state_tools.py
│   ├── shopping_tools.py
│   └── wallet_tools.py
│
├── state/
│   └── session_store.py
│
├── mcp/
│   └── mcp_server.py
│
├── requirements.txt
└── README.md

---

⚙️ Installation

1️⃣ Create a virtual environment (recommended)

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

2️⃣ Install dependencies

pip install -r requirements.txt

3️⃣ Environment variables

Create a .env file:

OPENAI_API_KEY=your_openai_key_here
RECIPE_CSV_PATH=recipes_db.csv

---

🚀 Running the Agents

Run RootAgent (ADK entrypoint)

Depending on how you run ADK (CLI / web / custom runner), ensure:

# agents/root_agent.py
agent = root_agent

RootAgent will automatically route requests to sub-agents.

---

🔄 Stateful vs Stateless Tools

Stateless tools

• Pure computation
• Safe to retry
• No memory

Examples:

• extract_ingredients_from_text
• search_recipes
• rank_recipes

Stateful tools

• Read/write session state
• Affect future behavior

Examples:

• select_recipe
• update_pantry
• wallet_authorize_purchase
• wallet_capture_purchase

Rule: Stateless tools compute facts. Stateful tools change reality.

---

🌐 MCP Server (Agent Sharing)

The MCP server allows:

• Your friend to call your agent’s tools
• Your RootAgent to call your friend’s agent

Start MCP server

python -m mcp.mcp_server

Server runs at:

http://localhost:8000/mcp

Inspect MCP server

npx -y @modelcontextprotocol/inspector

---

🤝 Agent-to-Agent Access

• Each user runs their own MCP server
• RootAgent can treat remote MCP tools as external capabilities
• Enables collaborative agent ecosystems

---

🔐 Security Note

This MCP setup is for development only.

If exposed publicly:

• Add authentication headers
• Use a reverse proxy
• Never expose wallet endpoints without auth

---

🧪 Known Limitations

• In-memory session state (resets on restart)
• Mock shopping inventory
• Simulated wallet (no real payments)
• Single-process concurrency only

---

📌 Why This Design Is Correct (ADK-aligned)

• No private ADK internals used
• RootAgent does orchestration only
• SequentialAgent used only where order matters
• Clean separation of tools vs agents
• MCP isolated from agent logic

---

📜 License

Standard MIT License

---