🤖 AI21 Maestro + Bright Data Template

🚀 A production-ready template for building AI agents with web access

Combine AI21's Maestro platform with Bright Data's web scraping capabilities to create powerful AI agents that can research and analyze real-time web data.

Getting Started • Demo • Documentation • Contributing

---

📸 Demo

AI Agent Dashboard

Configure and run AI agents with different personalities and budgets

Interactive API Documentation

Explore and test all endpoints with FastAPI's automatic documentation

---

✨ Features

Feature	Description
🤖 AI Agent Dashboard	Configure and run AI agents with different personalities and budgets
🌐 Web Data Access	Integration with Bright Data's free and pro web scraping tools
📊 Real-time Results	Watch your agents work and see results as they happen
📝 Run History	Track all your agent runs with detailed logs and results
🎨 Beautiful UI	Modern, responsive interface built with HeroUI components
⚡ Fast API	High-performance FastAPI backend with async support
🔒 Production Ready	Environment configuration, error handling, and security best practices
📚 Auto Documentation	Interactive API docs with FastAPI's automatic OpenAPI generation

---

🛠️ Tech Stack

Backend

Frontend

---

📋 Table of Contents

• 🤖 AI21 Maestro + Bright Data Template
  • 📸 Demo
    • AI Agent Dashboard
    • Interactive API Documentation
  • ✨ Features
  • 🛠️ Tech Stack
    • Backend
    • Frontend
  • 📋 Table of Contents
  • 🚀 Quick Start
    • Prerequisites
    • Backend Setup
    • Frontend Setup
  • 📖 API Documentation
    • Key Endpoints
  • 🔧 Available Tools
    • 🆓 Free Tools (Rapid Mode)
    • 💎 Pro Tools (Premium)
  • ⚙️ Configuration
    • Agent Personalities
    • Budget Levels
    • Environment Variables
  • 🏗️ Project Structure
  • 🧪 Development
    • Backend Development
    • Frontend Development
  • 🤝 Contributing
    • Development Process
    • Pull Request Guidelines
  • 📄 License
  • 🙏 Acknowledgments
  • 🔗 Useful Links

---

🚀 Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.8 or higher
• Node.js 16 or higher
• 🔑 AI21 Labs API key - Sign up for free
• 🌐 Bright Data token - Get your web scraping access

Backend Setup

1. Clone the repository

   git clone https://github.com/brightdata/ai21labs-brightdata-template
   cd maestro-brightdata

2. Create virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment

   cp .env.example .env
   # Edit .env and add your API keys

5. Start the API server

   python api_server.py

   🎉 API will be available at http://localhost:8000

Frontend Setup

1. Navigate to UI directory

   cd ui

2. Install dependencies

   npm install

3. Start development server

   npm run dev

   🎉 Web interface will be available at http://localhost:5173

---

📖 API Documentation

Once the backend is running, visit http://localhost:8000/docs for interactive API documentation powered by FastAPI's automatic OpenAPI generation.

Key Endpoints

Method	Endpoint	Description
POST	/run	Execute an AI agent with web access
GET	/status/{run_id}	Get the status of a specific run
GET	/runs	List all runs with their status
GET	/tools	Get information about available Bright Data tools
POST	/quick-run	Simplified endpoint for basic queries

---

🔧 Available Tools

🆓 Free Tools (Rapid Mode)

• Search Engine - Scrape search results from Google, Bing, or Yandex
• Web Scraper - Extract clean markdown from any webpage

💎 Pro Tools (Premium)

• E-commerce - Amazon, Walmart, eBay, Home Depot, Zara, Etsy, Best Buy
• Social Media - LinkedIn, Instagram, Twitter, TikTok, Facebook
• Business Intelligence - ZoomInfo, Crunchbase, job listings
• Browser Automation - Navigate, click, type, screenshot

---

⚙️ Configuration

Agent Personalities

Personality	Description
Web Researcher	Helpful assistant focused on web data research
Data Analyst	Technical assistant for data analysis tasks
Content Creator	Creative assistant for content generation
Technical Expert	Detailed technical responses with sources

Budget Levels

Level	Resources	Best For
Low	Basic computation	Simple queries
Medium	Standard computation	Most use cases
High	Maximum computation	Complex analysis

Environment Variables

# Required
AI21_LABS_KEY=your_ai21_labs_api_key_here
BRIGHTDATA_TOKEN=your_brightdata_token_here

# Optional
PORT=8000
HOST=0.0.0.0

---

🏗️ Project Structure

maestro-brightdata/
├── 📄 api_server.py          # FastAPI server
├── 📋 requirements.txt       # Python dependencies
├── 🔧 .env.example          # Environment variables template
├── 🚫 .gitignore            # Git ignore rules
├── 📖 README.md             # This file
└── 🎨 ui/                   # Frontend React app
    ├── 📁 src/
    │   ├── 🧩 components/   # Reusable UI components
    │   ├── 📄 pages/        # Page components
    │   ├── ⚙️ config/       # Configuration files
    │   └── 📝 types/        # TypeScript type definitions
    ├── 📦 package.json      # Node.js dependencies
    └── ⚡ vite.config.ts    # Vite configuration

---

🧪 Development

Backend Development

# Run with auto-reload
uvicorn api_server:app --reload --host 0.0.0.0 --port 8000

# Format code
black .
isort .

Frontend Development

cd ui

# Development server with hot reload
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

---

🤝 Contributing

We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

• 🐛 Reporting a bug
• 💡 Discussing the current state of the code
• 🚀 Submitting a fix
• 💫 Proposing new features
• 🎯 Becoming a maintainer

Development Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Pull Request Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass

---

📄 License

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

MIT License - feel free to use this template for your own projects!

---

🙏 Acknowledgments

Special thanks to the amazing teams and projects that make this template possible:

• 🤖 AI21 Labs - For the powerful Maestro platform
• 🌐 Bright Data - For comprehensive web data collection tools
• 🎨 HeroUI - For the beautiful, accessible component library
• ⚡ FastAPI - For the amazing, fast web framework
• ⚛️ React Team - For the incredible frontend library
• 🎯 Vite - For the lightning-fast build tool

---

🔗 Useful Links

• 📚 AI21 Maestro Documentation
• 🌐 Bright Data Platform Documentation
• 🎨 HeroUI Component Library
• ⚡ FastAPI Documentation

---

⭐ If this template helped you, please consider giving it a star!

Made with ❤️ by the Bright Data & AI21 Labs communities