Travel Buddy AI

A production-oriented multi-agent travel planning system built with FastAPI, LangGraph, MCP, supervisor routing, guardrails, and human-in-the-loop approval.

🚀 Live: Travel Buddy AI

🚀 Try the live application: Travel Buddy AI

Travel Buddy AI converts natural-language travel requests into structured, reviewable travel plans. Instead of relying on a single LLM call, it coordinates specialist agents for flights, hotels, weather, budget analysis, and itinerary generation through a LangGraph state workflow.

The system also supports supervisor-based routing, input guardrails, PostgreSQL-backed workflow state, MCP tool integrations, and a human approval checkpoint before the final plan is produced.

---

Demo Video 🎬

Watch the Travel Buddy AI walkthrough and see the multi-agent workflow in action:

---

---

📌 Overview

Travel planning often requires several independent information sources and decisions:

• Flight availability and guidance
• Hotel and destination research
• Weather information
• Budget feasibility
• Day-by-day itinerary construction
• Human review before finalization

Travel Buddy AI models these concerns as a coordinated multi-agent workflow.

🏗️ Architecture

The application is centered around a LangGraph state graph that coordinates specialist agents, external tools, persistent workflow state, and human approval.

---

---

✨ Key capabilities

Capability	Implementation
Natural-language trip requests	FastAPI + LLM workflow
Multi-agent orchestration	LangGraph
Dynamic agent selection	Supervisor
Input validation and guardrails	Supervisor guardrail layer
Flight research	AviationStack via MCP
Hotel and travel research	Tavily
Weather data	Custom MCP weather service + OpenWeather
Budget analysis	Dedicated budget specialist
Itinerary generation	Dedicated itinerary agent
Human review	LangGraph approval checkpoint
Resumable workflows	PostgreSQL checkpoint state
API documentation	FastAPI / OpenAPI
Containerization	Docker
Frontend	HTML, CSS, JavaScript

---

Workflow stages

1. Request validation
The guardrail checks whether the incoming request is appropriate for the travel-planning workflow.

2. Supervisor routing
The supervisor determines which specialist agents are required for the request.

3. Specialist research

• flight_agent — flight research through AviationStack MCP tools
• hotel_agent — hotel and travel research through Tavily
• weather_agent — current and forecast weather information
• budget_agent — affordability and budget analysis
• itinerary_agent — draft itinerary generation

4. Draft generation
The collected information is synthesized into a draft travel plan.

5. Human approval
The workflow pauses for user review. The user can approve the draft or provide feedback.

6. Final synthesis
After approval, the final agent produces the polished travel plan.

---

🧠 Why this architecture?

The project deliberately avoids treating an LLM as a single monolithic planner.

Instead, responsibilities are separated into specialist components:

                    +----------------+
                    |   Supervisor   |
                    +-------+--------+
                            |
          +-----------------+-----------------+
          |                 |                 |
          v                 v                 v
      Research           Analysis         Planning
          |                 |                 |
     +----+----+            |           +-----+------+
     |         |            |           |            |
  Flights   Hotels       Budget     Itinerary     Weather
     |         |            |           |            |
     +---------+------------+-----------+------------+
                          |
                          v
                    Human Review
                          |
                          v
                    Final Synthesis

This separation makes the workflow easier to extend, debug, and reason about than a single prompt-driven pipeline.

---

🛠️ Tech stack

Backend

• Python 3.10+
• FastAPI
• LangGraph
• LangChain
• langchain-groq
• PostgreSQL

Agent and tool layer

• MCP
• LangChain MCP adapters
• AviationStack
• Tavily
• OpenWeather
• Custom weather MCP server

Frontend

• HTML
• CSS
• JavaScript

Deployment

• Docker
• Render-compatible deployment

---

📁 Project structure

Travel-Buddy-AI/
│
├── app.py
├── backend.py
├── mcp_client.py
├── custom_weather_mcp_server.py
├── requirements.txt
├── Dockerfile
├── LICENSE
│
├── templates/
│   └── index.html
│
├── static/
│   ├── script.js
│   └── style.css
│
└── docus/
    ├── arch-img.png
    └── Recording 2026-08-11 095810.mp4

Core modules

File	Responsibility
app.py	FastAPI application, routes, frontend integration
backend.py	LangGraph workflow, agents, supervisor, approval flow, PostgreSQL checkpointing
mcp_client.py	MCP configuration, tool discovery, wrappers, retry logic
custom_weather_mcp_server.py	Example custom weather MCP service
templates/index.html	Travel request interface
static/script.js	Request, approval, resume, and frontend interaction logic
static/style.css	Frontend presentation
requirements.txt	Python dependencies

---

🔌 API

Health check

GET /health

Create a travel plan

POST /api/travel
Content-Type: application/json

Request:

{
  "message": "Plan a 3-day trip to Tokyo with a budget of $1200"
}

The workflow returns the generated planning state, including a thread_id that can be used to continue an approval workflow.

Approve or revise a draft

POST /api/travel/approve
Content-Type: application/json

Request:

{
  "thread_id": "<thread-id>",
  "approved": true,
  "feedback": ""
}

For a revision, set approved to false and provide feedback.

---

⚙️ Configuration

Create a .env file in the project root:

DATABASE_URL=postgresql://user:password@localhost:5432/travel_db

GROQ_API_KEY=your_groq_api_key
AVIATIONSTACK_API_KEY=your_aviationstack_api_key
TAVILY_API_KEY=your_tavily_api_key
OPENWEATHER_API_KEY=your_openweather_api_key

DEFAULT_ORIGIN_IATA=DAC

Environment variables

Variable	Purpose
DATABASE_URL	PostgreSQL connection used for workflow state
GROQ_API_KEY	LLM provider authentication
AVIATIONSTACK_API_KEY	Flight data access
TAVILY_API_KEY	Web and hotel/travel research
OPENWEATHER_API_KEY	Weather data
DEFAULT_ORIGIN_IATA	Default departure airport IATA code

Never commit .env files or API keys to version control.

---

💻 Local development

Prerequisites

• Python 3.10+
• PostgreSQL
• Git
• Optional: Docker

1. Clone

git clone https://github.com/Sauravdas007/Travel-Buddy-LangGraph-Multi-Agent-MCP-Supervisor-Gaurdrails-HITL-
cd Travel-Buddy-AI

2. Create a virtual environment

Windows

python -m venv .venv
.venv\Scripts\activate

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

Create .env using the variables described above.

5. Start the application

python app.py

Open:

http://127.0.0.1:8000/

Interactive API documentation:

http://127.0.0.1:8000/docs

---

🐳 Docker

Build the image:

docker build -t travel-buddy-ai .

Run the application:

docker run -p 8000:8000 --env-file .env travel-buddy-ai

Then open:

http://127.0.0.1:8000/

---

🔗 MCP integration

MCP is used as a tool integration layer between the agent workflow and external capabilities.

The project includes:

• AviationStack flight tooling
• Tavily research tooling
• A custom weather MCP server
• MCP tool discovery and initialization
• Retry handling for MCP startup

The custom weather server also serves as an example of how an application-specific capability can be exposed through MCP.

---

🔄 State management and human-in-the-loop

A key part of the architecture is resumable approval.

Request
  |
  v
Generate Draft
  |
  v
Persist Workflow State
  |
  v
Pause
  |
  +---- User approves ----> Final Agent
  |
  +---- User gives feedback
               |
               v
        Resume Thread
               |
               v
          Revised Draft

thread_id identifies the workflow session. PostgreSQL-backed LangGraph checkpoints allow the application to resume the workflow instead of starting the planning process from scratch.

The frontend also retains the thread_id so an approval flow can continue across requests.

---

💬 Example prompts

Plan a complete 7-day Japan trip from India under 2 lakhs.

Plan a 5-day Dubai vacation with flights, hotels, and sightseeing.

Create a weekend escape itinerary for Bangkok with budget-friendly hotels.

Recommend a family-friendly UK trip with weather and budget advice.

---

📝 Engineering notes

• thread_id is used to resume approval workflows.
• PostgreSQL stores LangGraph checkpoint state for resumable sessions.
• mcp_client.py contains MCP initialization, discovery, wrappers, and retry behavior.
• custom_weather_mcp_server.py demonstrates a locally exposed MCP weather capability.
• app.py uses nest_asyncio to bridge synchronous FastAPI execution with async MCP helpers.
• FastAPI automatically exposes OpenAPI documentation at /docs.

---

🧩 Development principles

The project is structured around several engineering principles:

Separation of concerns
Agent responsibilities, API handling, MCP integrations, and frontend behavior are kept in distinct modules.

Workflow orchestration
LangGraph manages state transitions instead of relying on an unstructured chain of LLM calls.

Tool abstraction
External capabilities are exposed through MCP/tool wrappers so the agent layer is not tightly coupled to individual service implementations.

Human oversight
The system does not immediately finalize a generated itinerary. A draft is exposed for review before final synthesis.

Resumability
Workflow state is checkpointed so approval and revision can continue without rebuilding the entire session.

Containerization
The application can be packaged and run consistently with Docker.

---

🤝 Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Test the workflow locally.
5. Open a pull request with a clear description of the change.

---

📄 License

This project is open source under the Apache 2.0 license. See LICENSE for details.

---

🚀 Project summary

Travel Buddy AI demonstrates how modern AI application architecture can combine:

FastAPI
   +
LangGraph
   +
Multi-Agent Systems
   +
MCP Tooling
   +
Supervisor Routing
   +
Guardrails
   +
Human-in-the-Loop
   +
PostgreSQL Checkpointing
   +
Docker

The result is a stateful travel-planning workflow designed to move beyond a simple chatbot toward a structured, tool-using, reviewable AI application.