A voice-enabled AI agent that provides detailed information about movies, directors, actors, genres, and personalized recommendations using the SignalWire AI Agents SDK and The Movie Database (TMDb) API.
- Movie Search: Find movies by title
- Detailed Movie Information: Get comprehensive details including plot, ratings, runtime, and budget
- Movie Discovery: Discover movies by genre, release year, and popularity
- Trending Movies: See what's currently popular
- Recommendations: Get movie recommendations based on films you like
- Cast and Crew: Access detailed cast and crew information
- Person Details: Look up actors and directors with their filmographies
- Theater Listings: Find movies currently playing or coming soon
- Similar Movies: Discover movies similar to ones you enjoy
The agent is built using:
- SignalWire AI Agents SDK: Provides the
AgentBaseframework for building voice AI agents with SWAIG (SignalWire AI Gateway) functions - TMDb API: Supplies real-time movie data
- ElevenLabs TTS: Natural voice synthesis for responses
moviebot/
├── app.py # Main agent (MovieBot class extending AgentBase)
├── tmdb_api.py # TMDb API module with typed functions
├── requirements.txt # Python dependencies
├── env.example # Environment variable template
└── prompt.md # Reference prompt documentation
- Python 3.8+
- TMDb API key (get one here)
- SignalWire account (sign up)
-
Clone the repository:
git clone https://github.com/briankwest/moviebot.git cd moviebot -
Install dependencies:
pip install -r requirements.txt
-
Configure environment variables:
cp env.example .env
Edit
.envand set:TMDB_API_KEY: Your TMDb API keySWML_BASIC_AUTH_USER: Basic auth username for SWAIG endpointsSWML_BASIC_AUTH_PASSWORD: Basic auth password for SWAIG endpointsPORT: Server port (default: 5000)
python app.pyThe agent will start on http://0.0.0.0:5000/swaig.
Use swaig-test to verify the agent:
# List all available tools
swaig-test app.py --list-tools
# Test a specific function
swaig-test app.py --exec search_movie --query "Inception"
# Dump the generated SWML
swaig-test app.py --dump-swmlThe agent provides 12 tools for movie information:
| Function | Description |
|---|---|
search_movie |
Search for movies by title |
get_movie_details |
Get detailed information about a movie |
discover_movies |
Discover movies by genre, year, or sorting criteria |
get_trending_movies |
Get currently trending movies |
get_movie_recommendations |
Get recommendations based on a movie |
get_movie_credits |
Get cast and crew for a movie |
get_person_details |
Get information about an actor or director |
get_genre_list |
Get the list of movie genres with IDs |
get_upcoming_movies |
Get movies coming soon |
get_now_playing_movies |
Get movies currently in theaters |
get_similar_movies |
Get movies similar to a specified movie |
multi_search |
Search across movies, TV shows, and people |
-
Create the app:
dokku apps:create moviebot
-
Set environment variables:
dokku config:set moviebot TMDB_API_KEY=your_api_key dokku config:set moviebot SWML_BASIC_AUTH_USER=your_username dokku config:set moviebot SWML_BASIC_AUTH_PASSWORD=your_password
-
Deploy:
git remote add dokku dokku@your-server:moviebot git push dokku main
-
Enable SSL (optional):
dokku letsencrypt:enable moviebot
docker build -t moviebot .
docker run -p 5000:5000 \
-e TMDB_API_KEY=your_api_key \
-e SWML_BASIC_AUTH_USER=your_username \
-e SWML_BASIC_AUTH_PASSWORD=your_password \
moviebotTo connect the agent to SignalWire:
- Create an External SWML Handler pointing to your agent URL
- Create a Subscriber with the handler
- Assign a phone number or use WebRTC for browser-based access
See the SignalWire AI documentation for detailed setup instructions.
This project is licensed under the MIT License. See the LICENSE file for details.
- SignalWire - AI Gateway and voice infrastructure
- TMDb - Movie database API
- ElevenLabs - Text-to-speech synthesis