Tripper: Embabel Travel Planner Agent

<div >

</div>

Tripper is a travel planning agent that helps you create personalized travel itineraries, based on your preferences and interests. It uses web search, mapping and integrates with Airbnb. It demonstrates the power of the Embabel agent framework.

Key Features:

🤖 Demonstrates Embabel's core concepts of deterministic planning and centering agents around a domain model
🌍 Illustrates the use of multiple LLMs (Claude Sonnet, GPT-4.1-mini) in the same application
🗺️ Extensive use of MCP tools for mapping, image and web search, wikipedia and Airbnb integration
📱 Modern web interface with htmx
🐳 Docker containerization for MCP tools
🚀 CI/CD with GitHub Actions

</td> </tr> </table>

🚀 Quick Start

Warning: Tripper is a genuinely useful travel planner. But be aware that its extensive LLM usage will cost money. A typical run costs around $0.10c.

Prerequisites

Java 21+
Docker
Maven 3.6+
Make sure you have 'Docker Model Runner' up and running and exposed on port 12434 ( docker desktop enable model-runner --tcp=12434)

Environment Setup

Configure API Keys

export OPENAI_API_KEY=your_openai_api_key_here
export ANTHROPIC_API_KEY=your_anthropic_api_key_here
# Set your Brave API key for image search
export BRAVE_API_KEY=your_brave_api_key_here

Set MCP Environment variables for MCP tools running in Docker

# Copy the example environment file
cp mcp.env.example .mcp.env

# Edit mcp.env with your configuration
nano .mcp.env

Running the Application

Start Background Services

docker compose --file compose.yaml --file compose.dmr.yaml up

Launch the Travel Planner

Option A: Using Shell Script
```
./run.sh
```
Option B: Using IDE
- Open the project in your IDE
- Run it in the way your IDE runs Spring Boot apps. In IntelliJ IDEA, simply run the main method in TripperApplication.kt.
Access the Application
- Travel Planner: http://localhost:8080/
- Platform Info: http://localhost:8080/platform

Running the Application with Docker

Launch the Travel Planner
```
docker compose --profile in-docker up
```
Access the Application
- Travel Planner: http://localhost:8747/
- Platform Info: http://localhost:8747/platform

Note that the default port is 8747 not the usual Java 8080. This is because we often run multiple Embabel servers at once and don't want them to conflict. The specific port is a reference to an iconic aircraft. It's easy to change the port in application.properties.

Setup OAuth Credentials

Enable security by changing the following line in application.properties:

embabel.security.enabled=true

Then follow these steps to set up Google OAuth:

Get Google OAuth credentials from Google Cloud Console
Add redirect URI: http://localhost:8747/login/oauth2/code/google

Set your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables:

export GOOGLE_CLIENT_ID=your_google_client_id_here
export GOOGLE_CLIENT_SECRET=your_google_client_secret_here

For more details, see the Security Guide.

📸 Screenshots

Itinerary Input

Input form for travel preferences

Generated Itinerary

AI-generated travel itinerary with detailed recommendations

Link to Interactive Map

Map link included in output

Link to Airbnb

Airbnb links for each stay of the trip

Plan and Usage Information

Information about plan and usage, including total cost

Event Stream

Emits events about process flow

</div>

🏗️ Architecture

The Tripper agent follows a modern microservices architecture:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Spring Boot/  │    │      LLMs       │
│   (htmx)        │◄──►│ Embabel Backend │◄──►│ (Claude,GPT 4)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │   Docker        │
                       │   MCP tools     │
                       └─────────────────┘

Components:

Frontend: Modern web interface built with htmx for seamless interactions
Backend: Kotlin-based Spring Boot application handling business logic. Key flow is defined in TripperAgent.kt.
LLMs: Illustrates use of multiple LLMs
Containerization: Docker for consistent deployment across environments and MCP tool management

🛠️ Development

Tech Stack

Backend: Kotlin, Embabel, Spring Boot, Apache Tomcat
Frontend: htmx, JSON APIs
Build: Apache Maven
DevOps: Docker, GitHub Actions

Note For Linux Developers

Ensure proper software version: Docker Desktop 4.43.1
Linux Docker Desktop does not support yet Model Runner in GUI. Please follow Model Runner Documentation
Validation step:

  docker model pull  jimclark106/all-minilm:23M-F16

Thereafter below compose would not be required (due to temparary lack of support on Linux):

  docker compose --file compose.dmr.yaml up

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the Apache License - see the LICENSE file for details.

🤝 Support

For questions, issues, or contributions, please visit our GitHub repository or open an issue.

Contributors

🌐 Website • 📧 Contact • 🐦 Twitter

Tripper

Install / Use

README