🌍 ADK & Gemini Trip Planner Agent

Note

Project Notice: This is a personal project created and developed with the assistance of AI tools (Antigravity & Google Gemini).

An enterprise-ready, autonomous Trip Planner AI Agent built using Google's official ADK (Agent Development Kit) and Gemini APIs (gemini-2.5-flash / gemini-1.5-pro).

---

🌟 Key Features & Workflow

The agent strictly follows the user-defined multi-phase travel planning protocol:

1. User Input Ingestion:
   • Takes start date, end date, target destination, budget, currency, and origin city/airport.
2. Phase 1 — Itinerary Preparation & Nearby Excursions:
   • Curates a rich day-by-day itinerary (Morning, Afternoon, Evening) with descriptions and estimated costs.
   • Highlights nearby day-trips, surrounding countryside spots, and hidden gems.
   • Calculates daily and total activity/dining expenses.
3. Mandatory User Confirmation Gate:
   • Displays the curated itinerary to the traveler and pauses for explicit user confirmation before touching booking pricing engines.
4. Phase 2 — Cheapest Economy Flight Discovery:
   • Automatically searches round-trip economy class flights for the date window.
   • Filters and highlights the absolute cheapest economy ticket, providing outbound and inbound flight numbers, departure/arrival schedules, and stops.
5. Phase 2 — Moderate 4+ Star Hotel Accommodations:
   • Pulls curated 4.0+ star hotel options in central locations near the planned itinerary attractions without overwhelming the traveler.
   • Focuses on moderate budget and exceptional guest ratings.
6. Phase 2 — Comprehensive Budget & Cost Audit:
   • Consolidates Flights + Hotel + Daily Sightseeing/Dining vs. User's Total Budget.
   • Highlights exact Surplus or Deficit with practical booking and packing advice.

---

🏗️ Architecture Overview

flowchart TD
    User["👤 Traveler / User"] -->|1. Destination, Dates, Budget| ADKAgent["🤖 ADK Agent (Gemini 2.5)"]
    
    subgraph Phase1 ["Phase 1: Itinerary Generation"]
        ADKAgent -->|Call| ItinTool["🗺️ prepare_itinerary()"]
        ItinTool -->|Return Days & Excursions| ItinDisplay["📋 Day-by-Day Itinerary"]
        ItinDisplay --> UserConfirm{"❓ User Confirmation Gate"}
    end
    
    UserConfirm -->|Confirmed| Phase2
    UserConfirm -->|Edit/Cancel| Adjust["🔄 Adjust Parameters"]
    
    subgraph Phase2 ["Phase 2: Bookings & Budget Analysis"]
        ADKAgent -->|Call| FlightTool["✈️ search_cheapest_economy_flights()"]
        ADKAgent -->|Call| HotelTool["🏨 search_hotel_prices() [4+ Stars, Moderate]"]
        ADKAgent -->|Call| BudgetTool["💰 calculate_budget_summary()"]
    end
    
    Phase2 --> Summary["🎉 Consolidated Trip Package & Budget Audit"]
    Summary --> User

Loading

---

🚀 Quick Start

1. Installation & Environment Setup

# Clone or navigate to the repository
cd /Users/ashish/git/trip_planner

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Configure API Key

Copy .env.example to .env and add your Google Gemini API key:

cp .env.example .env

Edit .env:

GEMINI_API_KEY=your_actual_gemini_api_key_here
GEMINI_MODEL=gemini-3.5-flash
DEFAULT_CURRENCY=USD
DEFAULT_ORIGIN="New York (JFK)"

Get your free Gemini API key from Google AI Studio.

---

💻 Usage

1. Interactive CLI Mode (Rich Terminal UI)

Launch the interactive CLI:

python main.py

The terminal interface will:

• Prompt for trip parameters (destination, dates, budget, origin).
• Present the colorized Day-by-Day itinerary and nearby excursions table.
• Ask for your confirmation (Do you confirm this itinerary? [y/n]).
• On confirmation, fetch and display the cheapest economy flight ticket, 4+ star moderate hotels, and full budget audit.

---

2. Web UI & REST API Server

Launch the FastAPI Web Application:

python main.py --api --port 8000

Open your browser and navigate to:

• Interactive Web App: http://localhost:8000
• OpenAPI Swagger Docs: http://localhost:8000/docs

---

🧪 Running Tests

Run the complete pytest test suite:

.venv/bin/pytest -v

---

📦 Project Structure

trip_planner/
├── trip_planner/
│   ├── __init__.py
│   ├── config.py             # App & Gemini configuration
│   ├── models.py             # Pydantic schemas (TripRequest, Flights, Hotels, etc.)
│   ├── agent.py              # Google ADK Agent definition & Runner service
│   ├── cli.py                # Rich CLI interface
│   ├── api.py                # FastAPI REST API & WebSocket service
│   ├── static/               # Modern Glassmorphic Web Dashboard
│   │   ├── index.html
│   │   ├── style.css
│   │   └── app.js
│   └── tools/
│       ├── __init__.py
│       ├── itinerary_tool.py # Day-by-day & nearby excursions engine
│       ├── flight_tool.py    # Cheapest round-trip economy flights finder
│       ├── hotel_tool.py     # Moderate 4+ star accommodations search
│       ├── budget_tool.py    # Cost audit & budget analysis
│       └── mcp_toolset.py    # Optional MCP server connector
├── tests/
│   ├── __init__.py
│   ├── test_tools.py         # Unit tests for tools
│   ├── test_agent.py         # ADK agent tests
│   └── test_api.py           # FastAPI integration tests
├── main.py                   # Unified CLI & API entrypoint
├── requirements.txt
├── pyproject.toml
├── .env.example
└── README.md

---

🛡️ License

MIT License. Built with Google ADK (Agent Development Kit) and Google GenAI Gemini APIs.