Flight Agent

AI-powered multi-city flight search using browser automation.

Flight Agent uses browser-use to autonomously navigate Google Flights, search complex multi-city itineraries, and return the cheapest options.

How it works

flowchart LR
    User[You] -->|Describe itinerary| CLI[flight-agent CLI]
    CLI -->|"browser-use Agent"| GF[Google Flights]
    GF -->|Select Multi-city| GF
    GF -->|Fill all segments| GF
    GF -->|Extract prices| CLI
    CLI -->|Cheapest options| User

Loading

The Agent from browser-use handles the entire flow -- no manual Playwright code or DOM selectors required.

Quickstart

# 1. Create .env with your API key
cp .env.example .env
# edit .env: GOOGLE_API_KEY="your-key"
# optionally set GEMINI_MODEL (default: gemini-2.5-flash)

# 2. Install
uv sync --group dev
uv run playwright install chromium

# 3. Run a search
uv run flight-agent search --headless "ZRH-HKG Oct 1"

Usage

Single search from the CLI

uv run flight-agent search --headless \
  "flight 1: ZRH-Hong-Kong (Oct 1-3), non-stop
   flight 2: Hong Kong-Tokyo (Oct 3-8), non-stop
   flight 3: Tokyo-Hong Kong (Oct 24-27), non-stop
   flight 4: Hong Kong-Zurich (Oct 27-31), non-stop"

Omit --headless to watch the browser navigate Google Flights in real time.

Batch search via script

Edit the dates in scripts/run-flight-queries.sh and run:

./scripts/run-flight-queries.sh

Interactive mode

Run without a plan argument to type or paste a flight plan interactively:

uv run flight-agent search

Development

Setup

make install        # install dependencies (includes dev tools)
make install-dev    # same as install (no separate test group)
make playwright-install   # download Chromium for Playwright
make pre-commit           # install git hooks

Quality checks

make lint          # ruff check
make format        # ruff format (auto-fixes)
make format-check  # check formatting without changes
make typecheck     # mypy static analysis

Testing

make test          # pytest
make test-cov      # pytest with coverage

CI

make ci            # lint + format-check + typecheck + test

Utilities

make run           # uv run flight-agent (alias)
make clean         # remove build artifacts and caches

Project structure

flight_agent/
├── flight_agent/
│   ├── agent.py          search_flights() wrapping browser-use Agent
│   ├── main.py           Click CLI
│   └── __init__.py
├── build/                build artifacts
├── .env.example
├── .gitignore
├── .pre-commit-config.yaml
├── LICENSE
├── Makefile
├── pyproject.toml
├── README.md
├── scripts/
│   └── run-flight-queries.sh  pre-configured multi-city search script
└── uv.lock

License

MIT