Your goal is to create an AI agent that can understand a user’s question, use a set of custom tools to work with data, and produce intelligent answers. This project brings together everything you’ve learned in this course: Python organization, data structures, database interaction, command-line interfaces, and version control.
Teams: Groups of 3 students
Project Proposal Deadline: November 10th - One team member emails Kevin and me with: - All team members’ names and email addresses - Your chosen domain and dataset - Brief outline of your agent’s capabilities (3-5 bullet points) - List of planned tool functions (5-8 tools minimum)
Final Presentation: January 12th at 9:00 AM - Live demo of your agent (10 minutes) - Code walkthrough (5 minutes) - Q&A session (5 minutes)
You’ll create an AI agent that connects a Large Language Model (LLM) to a custom toolkit you build in Python. The agent takes natural language questions, determines which tools to use, retrieves, and processes data, and returns comprehensive answers.
Your main task is designing and implementing the tools the LLM can use. Think of the LLM as the brain that decides what to do, and your tools as the hands that actually do the work.
Your agent should handle multi-step questions that require combining multiple tools. Here are examples across different domains:
E-commerce Analytics: - “Show me last month’s sales trends by category and compare them to the same period last year.”
Chess Database Analysis: - “What’s the win rate for players rated above 2000 who open with the King’s Indian Defense as Black?”
Machine Learning Benchmarking: - “Benchmark RandomForest, XGBoost, and LightGBM for predicting house prices. Use cross-validation and compare training time and accuracy.”
Financial Report Generation: - “Generate a quarterly financial report with revenue by product line, top 10 customers, profit margins, and growth analysis.”
Research Data Analysis: - “Analyze the correlation between study hours and exam scores, controlling for prior GPA. Identify outliers.”
Before diving into the example, let’s clarify what an AI agent is. Unlike a simple chatbot that just answers questions, an agent can:
Plan: Break down complex questions into steps
Use tools: Call functions you’ve written to get data, compute results, or perform actions
Reason: Decide which tools to use and in what order
Iterate: If one approach doesn’t work, try another
Synthesize: Combine results from multiple tools into a coherent answer
Think of it like this: You ask a question → The LLM (brain) decides what to do → It calls your tools (hands) → Tools return results → LLM interprets and responds.
Let’s walk through a complete example to understand the level of sophistication expected.
You build a personalized movie recommendation agent. The user has a database of movies they’ve watched with their ratings and comments. The agent helps them decide what to watch next based on what’s currently showing in their city.
User: “What movies are showing in Strasbourg this weekend? Recommend one based on what I’ve enjoyed before.”
Agent’s Workflow:
SELECT * FROM watched_moviesINSERT INTO watched_movies (title, date, rating, comments) VALUES (...)
For this movie recommendation agent, here’s a example of tools you could create
1. Database Tools These tools interact with your
local database of watched movies. You might use SQLite for this, with a
simple schema like
watched_movies(id, title, director, genre, rating, date_watched, user_comment).
get_user_watch_history() - Query all watched movies,
return as DataFrameget_favorite_genres() - Analyze which genres the user
rates highestget_favorite_directors() - Calculate average ratings
per directoradd_watched_movie(title, rating, comment) - Insert new
viewing recordupdate_movie_rating(title, new_rating) - Modify
existing entry if user changes their mind2. API Integration Tools These tools make HTTP
requests to external services to fetch real-time data. You’ll need API
keys (store them in .env!).
get_cinema_listings(city, date) - Call AlloCiné or
similar API to fetch current showings in the specified cityget_movie_details(title) - Query TMDB/IMDB for
comprehensive movie information (cast, crew, plot, ratings)get_director_filmography(director_name) - Retrieve all
movies by a director with their ratingsget_critic_reviews(movie_title) - Fetch professional
reviews from Rotten Tomatoes or Metacritic APIs3. Analysis Tools These tools process data and perform calculations. This is where Polars shines for fast data manipulation.
calculate_genre_preferences(watch_history) - Group by
genre, calculate average ratings, return ranked preferencesmatch_movie_to_preferences(movie, user_prefs) - Scoring
algorithm that compares a movie’s attributes to user preferencesfind_similar_movies(movie_title, database) -
Content-based filtering using genre, director, actors to find
matches4. Report Tools These tools format and present results to the user. The output format depends on your project’s design.
create_comparison_table(movies, scores) - Format
multiple movie options with scores in a readable tableWhy This Structure Works: The LLM can chain these
tools together. When you ask “Based on movies I’ve watched before, can
you recommend some films showing in Strasbourg cinemas this week?”, it:
1. Calls get_cinema_listings() to see options 2. Calls
get_user_watch_history() to understand preferences 3. For
top cinema options, calls get_movie_details() to get full
info 4. Calls match_movie_to_preferences() to score each
option 5. Calls create_comparison_table() to explain the
top choice
Each tool is independent, testable, and reusable in different combinations.
The core of your project is creating Python functions that serve as tools for the LLM. Your tools should be: - Modular: Each tool does one thing well - Composable: Tools can be combined in different ways
You need a database to store your data (mandatory). The format is your choice: - SQL (SQLite, PostgreSQL, MySQL) - NoSQL (MongoDB, JSON files) - File-based (Parquet, CSV, Pickle, text)
The format must be justified by your project needs. For example: - Relational data with complex queries → SQL - Nested/flexible structures → NoSQL/JSON - Large analytical datasets → Parquet - Simple, small data → CSV
Your database can be: - Static: Pre-populated data that’s only read - Dynamic: Updated by your tools as the agent runs
You’ll need tools to: - Query/read from the database - Optionally: Insert, update, or delete records
Fetch data from external sources to enrich your agent’s knowledge. Most APIs require registration for a free API key.
Common use cases: - Movie databases (TMDB, IMDB) - Get film information, cast, reviews - Weather APIs (OpenWeatherMap) - Current conditions, forecasts - Financial data (Alpha Vantage, Yahoo Finance) - Stock prices, company data - Geographic data (OpenStreetMap, Google Maps) - Locations, distances, routes - News APIs (NewsAPI) - Current articles, headlines by topic - Social media APIs (Twitter, Reddit) - Posts, trends, sentiment - Domain-specific APIs for your project (sports stats, recipe databases, etc.)
Analyze and transform data to extract insights. These tools often work with DataFrames returned by your database or API tools.
What these tools do: - Statistical calculations - Mean, median, standard deviation, correlations - Aggregations and grouping - Use Polars to group by categories, time periods, etc. - Filtering and ranking - Top N results, threshold filtering, sorting - Machine learning predictions - Train simple models, make predictions - Text analysis - Sentiment analysis, keyword extraction, summarization - Time series analysis - Trends, seasonality, forecasting
Example: A tool that takes sales data and calculates month-over-month growth rates, then identifies which products are trending up or down.
Create test, tables, charts, and plots to make data easier to understand.
Consider your output medium: - Text, tables: simple python print() - Image files: Generate PNG/JPG plots with matplotlib or plotly, save to disk - Interactive: Create HTML plots with plotly that allow zoom/pan - Embedded in reports: Generate images that get inserted into PDFs or documents
Compile results into structured, shareable outputs. Think about how your user wants to consume the final answer.
Output format options: - Markdown reports - Easy to read in terminal, convertible to other formats - HTML pages - Rich formatting, can embed images and tables, viewable in browser - PDF documents - Professional reports for sharing/printing (use libraries like reportlab or convert from HTML) - JSON/CSV exports - Structured data for further processing or import into other tools - Word documents - Editable reports using python-docx - Email reports - Send results via email with attachments —
Structure your code logically.
my_agent_project/
├── src/
│ └── agent_tools/ # Your package
│ ├── __init__.py
│ ├── database.py # Database tools
│ ├── api_clients.py # API integration
│ ├── analysis.py # Data processing
│ ├── visualization.py # Plotting tools
│ └── reports.py # Report generation
├── scripts/
│ ├── server.py # Main CLI script
│ └── setup_database.py # Initialize database
├── data/
│ ├── raw/ # Original datasets
│ └── processed/ # Cleaned data
├── config/
│ └── config.yaml # Configuration files
├── .env # API keys (DON'T commit!)
├── .gitignore # Ignore patterns
├── requirements.txt # Dependencies
└── README.md # Documentation