MomentMaker AI Agent

MomentMaker is an intelligent multi-agent system that helps you plan special moments - Diwali, birthdays, anniversaries, memorial days, festivals - by suggesting personalized gifts, activities, and experiences. Built with Google's Agent Development Kit (ADK) and powered by Gemini.

All prices and budgets are in Indian Rupees (₹).

Problem Statement

Planning special occasions manually is time-consuming and overwhelming. You need to:

Remember important dates and occasions
Research personalized gift ideas that match the recipient's interests
Find current prices and availability
Discover local events and experiences
Track budgets across multiple occasions
Coordinate delivery and write personalized messages

This process requires multiple tools, research, and mental effort. MomentMaker automates this entire workflow using specialized AI agents that work together seamlessly.

Solution Statement

MomentMaker is a multi-agent system that automates occasion planning through specialized agents:

Automated Research: Uses Google Search and MCP to find real-time product prices, events, and experiences
Intelligent Suggestions: AI agents analyze recipient profiles and suggest personalized gifts
Quality Assurance: LLM-as-a-Judge evaluation ensures gift suggestions are relevant and appropriate
Budget Management: Tracks spending and calculates remaining budget automatically
Human-in-the-Loop: Pauses for approval on expensive gifts (₹10,000+) before proceeding
End-to-End Planning: From occasion tracking to delivery coordination - all in one conversation

Value: Reduces planning time from hours to minutes, ensures personalized suggestions, and never misses important occasions.

Architecture

MomentMaker follows a coordinator pattern with specialized sub-agents. The system uses a dual-model architecture for optimal performance and cost efficiency.

Dual-Model Architecture

MomentMaker uses two Gemini models strategically:

critic_model (gemini-2.5-flash): Higher quality model for critical tasks
- Used by: gift_suggester (requires high-quality, personalized suggestions)
- Purpose: Ensures best quality for user-facing gift recommendations
worker_model (gemini-2.5-flash): Faster, cost-effective model for general tasks
- Used by: Main coordinator (MomentMaker) and 7 other sub-agents
- Purpose: Efficient coordination and routine tasks

Design Rationale: Critical tasks (gift suggestions) use the better model for quality, while coordination and routine tasks use the faster model for efficiency and cost optimization.

Architecture Overview

The system is built as a hierarchical multi-agent architecture with:

Main Coordinator Agent (MomentMaker) - Central orchestrator
8 Specialized Sub-Agents - Domain experts
2 LoopAgents - Robust, iterative processes with validation
15+ Tools - Custom tools, MCP tools, and built-in Google Search

Main Coordinator Agent

MomentMaker (gift_coordinator) - The central orchestrator:

Model: worker_model (fast, efficient coordination)
Role: Routes requests, coordinates workflows, manages agent-to-agent communication
Communication Method: Uses ADK's transfer_to_agent to delegate to sub-agents
Responsibilities:
- Understands user intent and routes to appropriate sub-agents
- Coordinates multi-step workflows (occasion → profile → gifts → activities)
- Handles approval flows (pause/resume for expensive gifts)
- Manages conversation context and state

Key Design: The coordinator doesn't perform tasks directly—it delegates to specialized agents, ensuring each agent focuses on its domain expertise.

Agent Communication Flow

How agents communicate:

User Input → MomentMaker (main coordinator)
MomentMaker analyzes request and decides which sub-agent(s) to use
MomentMaker calls transfer_to_agent(sub_agent_name) to delegate
Sub-Agent receives full conversation context and processes request
Sub-Agent may:
- Call tools (Google Search, MCP, custom tools)
- Return results to MomentMaker
- Request transfer to another sub-agent (via transfer_to_agent)
MomentMaker receives results and presents to user
For multi-part questions (e.g., "What's my relationship with Kush AND what's my budget status?"), MomentMaker can route to multiple sub-agents in sequence and stitch their answers into a single combined reply.

Example Flow:

User: "Plan a birthday for Kush on Dec 10th, budget ₹30000"
  ↓
MomentMaker → transfer_to_agent(robust_occasion_tracker)
  ↓
robust_occasion_tracker → validates and saves occasion
  ↓
MomentMaker → transfer_to_agent(recipient_profiler)
  ↓
recipient_profiler → extracts profile from conversation
  ↓
MomentMaker → transfer_to_agent(robust_gift_suggester)
  ↓
robust_gift_suggester → calls google_search() → calls evaluate_gift_suggestion()
  ↓
MomentMaker → presents results to user

Sub-Agents (8 Specialized Agents)

1. robust_occasion_tracker (LoopAgent)

Model: worker_model
Type: LoopAgent with validation checker
Purpose: Tracks special occasions (birthdays, anniversaries, festivals)
Internal Components:
- occasion_tracker: Core agent that extracts and saves occasion details
- occasion_validation_checker: Validates occasion data (date, recipient, type)
Validation Loop: Bidirectional feedback between tracker and checker ensures quality
Communication: Receives requests from MomentMaker, returns validated occasion data

2. recipient_profiler (Sequential Agent)

Model: worker_model
Type: Sequential Agent
Purpose: Builds detailed recipient profiles from conversation
Extracts: Name, age, profession, location, interests, relationship
Tools: Google Search (optional) for profession research
Communication: Can receive profile queries from MomentMaker or robust_gift_suggester

3. robust_gift_suggester (LoopAgent)

Model: critic_model ⭐ (Higher quality for critical task)
Type: LoopAgent with validation checker
Purpose: Suggests personalized gifts based on recipient profile and budget, and guarantees the requested number of gift ideas (e.g., exactly 2 gifts if the user asks for 2), even when approval flows are involved
Internal Components:
- gift_suggester: Core agent that generates gift suggestions
- gift_validation_checker: Validates gift suggestions (presence, format, completeness)
Tools Available:
- google_search: Real-time product prices and availability
- evaluate_gift_suggestion: LLM-as-a-Judge evaluation (relevance, personalization, budget)
- request_expensive_gift_approval: Long-running operation for gifts > ₹10,000
Validation Loop: Bidirectional feedback ensures high-quality suggestions
Communication:
- Receives requests from MomentMaker
- Can query recipient_profiler for profile details
- Pauses execution for approvals, then resumes after approval_manager processes and finishes the full gift list (including approved gifts or alternatives)
- Uses Google Search efficiently with 1–2 broad queries per request (not one search per gift), and reuses earlier search results where possible instead of spamming the API

4. activity_planner (Sequential Agent)

Model: worker_model
Type: Sequential Agent
Purpose: Suggests activities, events, and experiences
Tools Available:
- search_events: MCP tool for local events, concerts, workshops
- search_festivals: MCP tool for cultural festivals
- search_experiences: MCP tool for activities by location and budget
- google_search: Real-time current events
Strategy: Combines MCP results (structured) with Google Search results (current) for comprehensive coverage
Communication: Receives requests from MomentMaker, returns event lists

5. budget_manager (Sequential Agent)

Model: worker_model
Type: Sequential Agent
Purpose: Manages budgets and tracks spending
Features:
- Tracks spending from conversation history
- Calculates remaining budget
- Generates budget reports
- When the user explicitly asks about gifts (e.g., "what all gifts do I have"), lists all gifts and their prices alongside the budget status
Communication: Receives budget queries from MomentMaker, returns budget status

6. relationship_manager (Sequential Agent)

Model: worker_model
Type: Sequential Agent
Purpose: Tracks relationship context and history
Features: Extracts relationship type and duration from conversation
Communication: Receives relationship queries from MomentMaker

7. delivery_coordinator (Sequential Agent)

Model: worker_model
Type: Sequential Agent
Purpose: Coordinates gift delivery and generates personalized messages
Features:
- Schedules delivery
- Generates occasion-appropriate messages
Communication: Receives delivery requests from MomentMaker

8. approval_manager (Sequential Agent)

Model: worker_model
Type: Sequential Agent
Purpose: Manages human approvals for long-running operations
Tools Available:
- get_pending_approvals: Retrieves pending approval operations
- approve_operation: Approves a pending operation
- reject_operation: Rejects a pending operation
Features:
- Processes natural language approvals (yes/no/ok)
- Handles expensive gift approvals
- Implements pause/resume workflow
Communication Flow:
1. Receives approval request from MomentMaker (after user responds to approval prompt)
2. Calls get_pending_approvals() to find the operation
3. Calls approve_operation() or reject_operation() based on user response
4. Returns result to MomentMaker
5. MomentMaker transfers back to robust_gift_suggester to continue
- If the user message is not a clear approval/rejection reply (e.g., it asks about budget, relationship, or a new planning question), approval_manager immediately hands control back to MomentMaker, which then routes to the right sub-agent(s).

LoopAgents: Robust Iterative Processes

LoopAgents provide automatic retry with validation:

robust_occasion_tracker:
- occasion_tracker generates output
- occasion_validation_checker validates
- If invalid: LoopAgent retries automatically (up to max_iterations=3)
- If valid: Checker escalates → LoopAgent proceeds
robust_gift_suggester:
- gift_suggester generates suggestions
- gift_validation_checker validates
- If invalid: LoopAgent retries automatically
- If valid: Checker escalates → LoopAgent proceeds

Benefit: Ensures high-quality output through automatic retry without manual intervention.

Tool Integration Architecture

Tools are organized by category:

MCP Tools (Model Context Protocol):
- search_events, search_festivals, search_experiences
- Used by: activity_planner
- Provides: Structured access to event databases
Custom Tools (15+ tools):
- Occasion management, recipient profiling, gift suggestions, budget tracking, etc.
- Used by: Various agents based on need
- Provides: Domain-specific functionality
Built-in Tools:
- google_search: Real-time information
- Used by: gift_suggester, activity_planner, recipient_profiler
- Provides: Current product prices, events, trends
Long-Running Operation Tools:
- request_expensive_gift_approval: Creates pause point
- Used by: gift_suggester
- Provides: Human-in-the-loop approval mechanism

Approval Flow: Long-Running Operations

Complete approval flow:

User Request: "Plan birthday, budget ₹30000"
MomentMaker → robust_gift_suggester
gift_suggester finds expensive gift (₹15,000)
gift_suggester calls request_expensive_gift_approval(gift_name, price, recipient)
System Pauses: Operation created, execution paused
User Sees: "I found a gift that costs ₹15,000. Approve? (yes/no)"
User Responds: "yes"
MomentMaker → approval_manager (immediate transfer)
approval_manager:
- Calls get_pending_approvals() → finds operation
- Calls approve_operation(operation_id)
- Returns approval status
MomentMaker → robust_gift_suggester (immediate transfer back)
gift_suggester continues with approved gift included in suggestions
MomentMaker presents final suggestions to user

Key Points:

Pause happens automatically when request_expensive_gift_approval() is called
approval_manager must process the response (cannot skip)
Flow always returns to robust_gift_suggester after approval processing

Features

MomentMaker implements the following capabilities:

✅ 1. Multi-Agent System

Main Agent: MomentMaker (coordinator)
LoopAgents: robust_occasion_tracker, robust_gift_suggester (with validation)
Sequential Agents: 6 specialized agents for specific tasks
Agent-to-Agent Communication: Via transfer_to_agent (ADK built-in)

✅ 2. Tools

MCP Tools: Event search, festival search, experience search
Custom Tools: Gift suggestions, budget tracking, delivery coordination
Built-in Tools: Google Search (live, current information)
Tool Count: 15+ custom tools

✅ 3. Long-Running Operations

Pause/Resume: Expensive gift approvals (₹10,000+)
Human-in-the-Loop: Natural language approval flow
Implementation: approval_manager + long_running/operations.py

✅ 4. Sessions & Memory

Sessions: ADK's InMemorySessionService (conversation history)
Context Engineering: Context compaction for long conversations
Memory: memory_enabled: True in config

✅ 5. Observability

Logging: Structured logging with structlog (crisp, minimal logs)
Tracing: OpenTelemetry wiring via ADK (disabled by default via env flags to keep logs clean; can be re-enabled if needed)
Metrics: Prometheus metrics for agent performance
Implementation: observability/ module

✅ 6. Agent Evaluation

LLM-as-a-Judge: Evaluates gift suggestions for quality
Metrics: Relevance, personalization, budget appropriateness
Implementation: evaluation/evaluator.py
Tool: evaluate_gift_suggestion() available to agents

✅ 7. A2A Protocol (Infrastructure Ready)

A2A Infrastructure: a2a/agent_communication.py
Current: Uses transfer_to_agent for same-process efficiency
Future: Ready for distributed agent deployments across multiple servers

Real-Time Data Sources

Google Search Integration

Live Product Prices: Real-time pricing from Google Custom Search
Current Events: Up-to-date event information
Usage: Agents automatically use Google Search for current data

Event MCP (Model Context Protocol)

Event Search: Local events, concerts, workshops
Festival Search: Cultural festivals and celebrations
Experience Search: Activities by location and budget

Quick Start

Prerequisites

Python 3.10+
Google Gemini API Key (required)
Google Search API Key (optional - without it, you won't get real-time product prices and current events)

Installation

# Clone repository
git clone <repo-url>
cd MomentMaker

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration

Create .env file in project root:

# Required: Google Gemini API Key
GOOGLE_API_KEY=your_api_key_here

# Optional: Google Search API (for live search results)
# Without this, agents will use knowledge base instead of real-time data
GOOGLE_SEARCH_API_KEY=your_search_api_key_here
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id_here

Get API Keys:

GOOGLE_API_KEY: Google AI Studio
GOOGLE_SEARCH_API_KEY & GOOGLE_SEARCH_ENGINE_ID: Google Custom Search API
- 100 free queries/day
- Create Custom Search Engine at Google Programmable Search

Model Configuration (in MomentMaker/config.py):

MomentMaker uses a dual-model architecture:

critic_model: gemini-2.5-flash - Used for critical tasks requiring high quality
- Used by: gift_suggester (personalized gift recommendations)
worker_model: gemini-2.5-flash - Used for general tasks requiring efficiency
- Used by: Main coordinator and 7 other sub-agents

You can customize models in MomentMaker/config.py:

config = MomentMakerConfiguration(
    critic_model="gemini-2.5-flash",    # Higher quality for critical tasks
    worker_model="gemini-2.5-flash",    # Faster for general tasks
    max_iterations=3,                    # LoopAgent retry limit
    memory_enabled=True                  # Enable long-term memory
)

For Vertex AI deployments, set USE_VERTEXAI=TRUE and provide GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and credentials via GOOGLE_APPLICATION_CREDENTIALS; the same MomentMakerConfiguration will automatically switch to the appropriate Vertex model IDs.

Run

On macOS/Linux:

./run_adk.sh

On Windows:

# Activate virtual environment first
.venv\Scripts\activate

# Then run ADK
adk web

Access at: http://127.0.0.1:8000

Usage Examples

Example 1: Plan a Birthday

User: "I want to plan a birthday for my friend Kush on December 10th, 2025. 
      He's 30, works as a doctor in Mumbai, loves reading books. 
      We've been friends for 5 years. My budget is ₹30000."

MomentMaker:
1. Tracks occasion (robust_occasion_tracker)
2. Builds profile (recipient_profiler)
3. Suggests gifts (robust_gift_suggester) - uses Google Search
4. Evaluates suggestions (evaluate_gift_suggestion)
5. Requests approval for expensive gifts (approval_manager)
6. Suggests activities (activity_planner) - uses MCP + Google Search
7. Tracks budget (budget_manager)

Example 2: Check Budget Status

User: "What's my current budget status?"

MomentMaker → budget_manager:
- Extracts spending from conversation
- Calculates remaining budget
- Returns: Original Budget, Spending, Remaining

Example 3: Find Events

User: "What events are happening in Mumbai around December 10th?"

MomentMaker → activity_planner:
- Searches MCP events (search_events)
- Searches Google for current events
- Combines results
- Returns: List of events with dates

Project Structure

MomentMaker/
├── MomentMaker/
│   ├── agent.py                 # Main coordinator agent
│   ├── config.py                # Configuration (models, API keys)
│   ├── tools.py                 # Custom tools (15+ tools)
│   ├── sub_agents/              # 8 specialized sub-agents
│   │   ├── occasion_tracker.py
│   │   ├── recipient_profiler.py
│   │   ├── gift_suggester.py
│   │   ├── activity_planner.py
│   │   ├── budget_manager.py
│   │   ├── relationship_manager.py
│   │   ├── delivery_coordinator.py
│   │   └── approval_manager.py
│   ├── long_running/            # Long-running operations
│   │   └── operations.py
│   ├── mcp/                     # Model Context Protocol
│   │   └── event_mcp.py
│   ├── observability/           # Logging, tracing, metrics
│   │   ├── logging.py
│   │   ├── tracing.py
│   │   └── metrics.py
│   ├── evaluation/               # LLM-as-a-Judge evaluation
│   │   └── evaluator.py
│   ├── a2a/                     # A2A Protocol (for distributed)
│   │   └── agent_communication.py
│   └── validation_checkers.py    # Validation for LoopAgents
├── CONVERSATION_TEST.txt        # Test prompts
├── requirements.txt              # Dependencies
├── run_adk.sh                   # Run script
└── README.md                     # This file

Key Design Decisions

1. Multi-Agent Architecture

Why: Each agent specializes in one task (single responsibility)
Benefit: Easier to maintain, test, and improve individual agents

2. LoopAgents for Critical Tasks

Why: robust_occasion_tracker and robust_gift_suggester use LoopAgents
Benefit: Automatic retry with validation ensures quality

3. Google Search Integration

Why: Real-time product prices and current events
Benefit: Suggestions are always current, not outdated

4. LLM-as-a-Judge Evaluation

Why: Quality assurance for gift suggestions
Benefit: Ensures relevance and personalization

5. Natural Language Approvals

Why: User-friendly (yes/no/ok) instead of operation IDs
Benefit: Better user experience

6. Crisp Logging

Why: Minimal, readable logs instead of verbose JSON
Benefit: Easy debugging without noise

Testing

See CONVERSATION_TEST.txt for 8 comprehensive test prompts that:

Test all sub-agents
Trigger all tools (Google Search, MCP, evaluation)
Test approval flow
Test budget tracking
Test agent-to-agent transfers

Technologies Used

Google Agent Development Kit (ADK): Multi-agent framework
Google Gemini API: LLM models (gemini-2.5-flash by default; optionally Vertex AI Gemini models when USE_VERTEXAI=TRUE)
Model Context Protocol (MCP): Event and experience search
Google Custom Search API: Live product and event information
OpenTelemetry: Distributed tracing
Structlog: Structured logging
Prometheus: Metrics collection

Future Plans

1. A2A Protocol for Distributed Systems

Current: A2A infrastructure exists but not used (single-process setup)
Future: Deploy agents across multiple servers for scalability
Use Case: Separate gift suggestion service, event search service, etc.
Testing: Need to test over distributed system architecture

2. Enhanced Observability

Current: Basic logging and metrics
Future: Upgrade to paid Gemini version for better performance metrics
Planned: Detailed performance dashboards, cost tracking per agent

3. Multi-User Support

Current: Single user sessions
Future:
- User authentication (password/sign-in)
- User-specific profiles and preferences
- Per-user occasion tracking and history
- Personalized recommendations based on user history

4. Additional Sub-Agents

Gift Comparison Agent: Compare prices across multiple vendors
Reminder Agent: Proactive notifications for upcoming occasions
Social Media Agent: Share occasion plans and gift ideas

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
MomentMaker		MomentMaker
.gitignore		.gitignore
CONVERSATION_TEST.txt		CONVERSATION_TEST.txt
README.md		README.md
requirements.txt		requirements.txt
run_adk.sh		run_adk.sh

kuspia/MomentMaker

Folders and files

Latest commit

History

Repository files navigation