Trip Guide — Conversational Trip Planner

Multi-agent travel assistant with live trip board + map

AI Agent Project

Google ADK orchestrator + specialists
Gemini → Groq → Ollama failover
SSE streaming chat
Leaflet + OSRM free-stack maps

Trip Guide understands multi-stop trips from natural language, updates a live trip board + map, and delegates climate, places, and stays to specialist agents. Built with Google ADK on a mostly free stack (Open-Meteo, DuckDuckGo, OSM/OSRM, optional Groq). Part of the Agents monorepo alongside Recruiting Agent.

View architecture & UI ↓

What it does

Architecture overview — FastAPI SSE, model failover, orchestrator + specialists, trip board and map

Capability	Detail
Multi-stop NLU	Parses destinations, dates, prefs; tolerates typos (banglore → Bengaluru)
Trip spine	Ordered stops, dates, weather chips, click-to-focus on map
Route map	Numbered markers + driving polyline via public OSRM
Specialists	Climate (Open-Meteo), places/food/stays (DuckDuckGo + optional Compound)
Streaming UX	Status labels: Updating trip board… Checking climate… Searching places…
Model resilience	Gemini primary → Groq fallback → local Ollama last resort

Monorepo context

Agents/
├── README.md
├── recruiting-agent/       # AI-powered ATS / resume scoring
└── Trip_planner-agent/     # Trip Guide (this project)
    ├── trip_planner/       # agents, API, tools, chat service
    ├── web/                # three-column UI + Leaflet
    ├── page_images/        # screenshots
    └── scripts/            # run_server.sh, demo_queries.py

Agents and agent types

Live chat uses one orchestrator + three specialists wired as ADK AgentTools (not SequentialAgent/ParallelAgent on the UI path).

Agent	Type	Job	Tools
`trip_guide`	Orchestrator	Understand trip, update UI state, delegate, merge reply	`publish_trip_board`, `publish_trip_prefs`, `get_directions`, AgentTools
`weather_specialist`	Specialist (AgentTool)	Climate for stops/dates	`get_weather_for_dates`, `get_live_weather_forecast`
`places_specialist`	Specialist (AgentTool)	Attractions / best-rated places	`suggest_places`, `compound_research`, `web_search`
`stays_specialist`	Specialist (AgentTool)	Food + lodging when asked	`suggest_food`, `search_lodging`, `compound_research`

End-to-end planning flow

User chat
  → FastAPI SSE /api/chat/stream
  → Model failover (Gemini → Groq → Ollama)
  → trip_guide orchestrator
      → publish_trip_board / publish_trip_prefs
      → weather_specialist / places_specialist / stays_specialist
      → get_directions
  → Chat + spine + map
  → POST /api/trip/geometry (OSRM polyline)

User sends destinations, dates, prefs, and what they want (climate, places, …).
SSE starts: UI shows Thinking… then tool status labels.
Orchestrator calls publish_trip_board → left spine + map geocode/OSRM polyline.
If prefs stated → publish_trip_prefs → prefs strip (budget · chill · beaches).
Same turn: weather and/or places specialists (and stays if asked).
Cards stream into chat; orchestrator writes a short merged answer.
On Gemini failure (503/quota/timeout), chat service retries fallbacks then Ollama.

Model failover

Order	Model	Role
1–3	Gemini Flash family	Primary + Gemini fallbacks
4–5	Groq Llama (tool-capable)	Cloud fallback when Gemini busy/quota
6–7	Ollama (local GPU)	Last resort tool-capable local models

Three-column live UI

Left Trip plan spine · center Trip Guide chat · right Route map. Empty panels fill as the agent publishes the board, weather, places, and geometry.

Trip Guide UI with chat prompt in flight — **In flight** — user multi-stop Karnataka prompt while tools stream status updates

Trip spine with weather cards — **Board filled** — ordered stops, prefs strip, climate timelines

Trip Guide full UI layout — **Layout** — map markers and teal OSRM route with streaming chat

Example prompt

I'm planning a trip to Gokarna, Jog Falls and Murudeshwar in Karnataka from Oct 1 to Oct 5.
We start from Bangalore on Wednesday Sep 30 and should be back on Oct 5 by evening.
Budget, chill pace, beaches. See climate and best rated places.

Expect: prefs strip, trip spine, map route, weather cards, places with reference links.

Tech stack

Layer	Technology
Agent runtime	Google ADK (`Agent`, `AgentTool`, `Runner`)
Primary LLM	Google Gemini (AI Studio)
Fallback LLM	Groq via ADK LiteLLM
Last-resort LLM	Local Ollama (tool-capable)
API	FastAPI + SSE (`/api/chat/stream`)
UI	Static HTML/CSS/JS — three-column shell
Map	Leaflet + OpenStreetMap tiles
Route geometry	Public OSRM (`/api/trip/geometry` proxy)
Weather	Open-Meteo (geocode + forecast/archive)
Places / food / stays	DuckDuckGo text search (+ optional Compound)

Package layout

Path	Role
`trip_planner/agents/`	Orchestrator + weather/places/stays specialists
`trip_planner/api/app.py`	FastAPI chat + geometry + static UI
`trip_planner/runtime/chat_service.py`	Sessions, SSE, model failover
`trip_planner/tools/`	Weather, maps, search, board, prefs
`web/`	Three-column Leaflet UI

Quick start

git clone https://github.com/Harish-nika/Agents.git
cd Agents/Trip_planner-agent

# Prerequisites: Python 3.10+, Gemini API key
# Optional: Groq key, Ollama (tool-capable model), Google Maps key

cp .env.example .env   # set GOOGLE_API_KEY at minimum

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

PYTHONPATH=. python3 -m uvicorn trip_planner.api.app:app --host 127.0.0.1 --port 8080
# Or: ./scripts/run_server.sh

# Open http://127.0.0.1:8080

No public hosted demo — run locally. Never commit .env. Set TRIP_PLANNER_SKIP_GEMINI=1 when free-tier Gemini quota is exhausted; set TRIP_PLANNER_PREFER_OLLAMA=1 to try local GPU before cloud APIs.

View on GitHub Recruiting Agent case study

Back to Portfolio