A collaborative multi-agent educational workspace powered by Band.ai, Groq, and the AI/ML API. Four specialized AI agents work together to help students learn any topic — from raw notes research to interactive testing and real-time remedial feedback loops.
🚀 Live Demo: https://studyband-multi-agent-ai-study-system.onrender.com
- Overview
- Core Features
- How It Works & The Handoff Flow
- Multi-Agent Architecture
- Tech Stack
- Project Structure
- Getting Started
- Environment Variables
- The Quiz Feedback Loop (Remedial Mode)
- License
StudyBand shifts study materials from passive reading to active learning. Instead of using a single LLM prompt wrapper, StudyBand utilizes four independent AI agents registered on Band.ai that communicate inside a secure Band room.
When a student inputs a topic (e.g., Recursion or Photosynthesis) and chooses their target education level (from Middle School to Professional), the agents activate in sequence:
- 🔍 Researcher creates detailed, structured academic notes.
- ✏️ Simplifier translates technical explanations into analogies and simple language.
- ❓ Quiz Master generates interactive multiple-choice questions.
- ✅ Evaluator grades answers, gives constructive feedback, and triggers remedial review if the student struggles.
| Feature | Description |
|---|---|
| 🤖 Band.ai Coordination | Agents communicate live via Band rooms using @mention handoffs, serving as a real coordination layer. |
| 🎛️ Dual Provider Switcher | Swap AI backends on-the-fly: Groq (for ultra-low latency) or AI/ML API (accessing Llama 3.3, Claude 3.5/4.5, DeepSeek, and GPT-4o). |
| 🎓 Educational Targeting | Adjusts complexity, vocabulary, and concepts automatically for Middle School, High School, College, or Professional levels. |
| 🔄 Intelligent Feedback Loop | The Evaluator dynamically signals the Quiz Master if a student scores below 80%. The Quiz Master then automatically creates exactly 2 simpler review questions on the weak topics. |
| 📂 Shared State Sync | Local processes synchronize via a lightweight state machine (shared_state.json), updating the Streamlit UI reactively. |
| ⚡ Zero-Friction Reset | Re-run or clear sessions instantly to study new subjects in a clean environment. |
The orchestration flows between a web UI, a local state coordinator, and the Band.ai cloud:
┌──────────────────────────────┐
│ STREAMLIT UI │
│ 📚 Study ❓ Quiz 🏆 Results│
└──────────────────────────────┘
│ ▲ │ ▲
Starts Topic │ Updates State │ │ Polls Score
▼ │ ▼ │
┌──────────────────────────────────┐
│ shared_state.json │
│ (Central Status Coordinator) │
└──────────────────────────────────┘
│ ▲ │ ▲ │ ▲ │ ▲
Polls │ │ Writes │ │ Writes │ │ Writes │ │ Writes
Topic ▼ │ ▼ │ ▼ │ ▼ │
┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ RESEARCHER │ │ SIMPLIFIER │ │ QUIZ MASTER │ │ EVALUATOR │
│ (local agent) │ │ (local agent) │ │ (local agent) │ │ (local agent) │
└────────────────┘ └────────────────┘ └────────────────┘ └────────────────┘
│ ▲ │ ▲ │ ▲ │ ▲
│ │ │ │ │ │ │ │
▼ │ ▼ │ ▼ │ ▼ │
┌─────────────────────────────────────────────────────────────────────────┐
│ BAND.AI CLOUD ROOM │
│ │
│ @Simplifier ──▶ @QuizMaster ──▶ @Evaluator ──▶ @QuizMaster (Remedial) │
└─────────────────────────────────────────────────────────────────────────┘
The student selects a topic (e.g. "Binary Trees") and an education level on the UI, and clicks Start Studying. The UI resets the state file and sets status to "starting".
- Researcher Agent detects
"starting", queries the selected model (via Groq or AI/ML API) to create exhaustive study notes, saves them to state, and broadcasts a message to the Band Room:SIMPLIFY_NOTES: <notes>mentioning@Simplifier. - Simplifier Agent receives the message, simplifies the notes to match the student's target education level, updates the state, and sends:
CREATE_QUIZ: <simplified_notes>mentioning@QuizMaster. - Quiz Master Agent receives the simplified notes, compiles a 5-question multiple-choice quiz, saves it to state, and sends:
QUIZ_READY: 5 questions created.mentioning@Evaluator. - Evaluator Agent waits for the student's answers from the UI, grades them, writes the teacher's evaluation to the state, and sends:
EVALUATION_DONE: <feedback>mentioning@QuizMaster.
- Frontend: Streamlit (Python) with custom premium layout and micro-animations.
- Orchestration Layer: Band.ai SDK (running
LangGraphAdapterandAgentTools). - LLM Engine:
- Groq API (Llama-3.3-70b-versatile, Llama-3.1-8b-instant, Mixtral-8x7b).
- AI/ML API (Claude 3.5 Sonnet, Claude 4.5 Sonnet, Llama 3.3 Turbo, DeepSeek Chat, GPT-4o Mini).
- State Management: Local JSON filesystem syncing.
study-band/
├── .env.example # Environment variables template
├── agent_config.yaml.example # Band.ai agent credentials template
├── requirements.txt # PIP dependencies
├── run_agents.py # Process runner for all 4 agents
├── app.py # Streamlit frontend & state loader
├── shared_state.json # Live state communication file
├── LICENSE # MIT License file
└── agents/
├── llm_helper.py # Dual provider (Groq / AI/ML API) helper
├── researcher.py # Structures academic concepts
├── simplifier.py # Lowers reading level / adds analogies
├── quiz_master.py # Creates questions & handles remedial tasks
└── evaluator.py # Validates answers and checks scores
First, clone the repository and set up a Python virtual environment:
# Clone the repository
git clone https://github.com/adhipatya3552/StudyBand.git
cd StudyBand
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# On Windows (Command Prompt):
venv\Scripts\activate.bat
# On Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# On macOS/Linux:
source venv/bin/activate
# Install the dependencies inside the virtual environment
pip install -r requirements.txt-
Copy the configuration templates:
cp .env.example .env cp agent_config.yaml.example agent_config.yaml
-
Edit
.envand fill in your keys:GROQ_API_KEY: Get from console.groq.comBAND_ROOM_ID: Create a room in Band.ai and copy the UUID from the URLAIMLAPI_API_KEY: (Optional) Get from aimlapi.com
-
Edit
agent_config.yamland paste the credentials for your 4 External Agents registered on app.band.ai/agents.
Open two separate terminal windows and ensure the virtual environment is activated in both terminals:
- Terminal 1 (Start the agents):
# Activate venv if not already done, then run: python run_agents.py - Terminal 2 (Start the Web UI):
# Activate venv if not already done, then run: streamlit run app.py
Your browser will automatically open to http://localhost:8501.
StudyBand includes a real agent-to-agent collaboration loop to help struggling students:
- When a student submits answers, the Evaluator checks the score.
- If the grade is below 80% (e.g. 3/5 or lower), the Evaluator appends
[REMEDIAL_REQUIRED]to the feedback. - The Quiz Master detects the tag, interrupts the normal flow, and generates exactly 2 simpler review questions focusing specifically on the concepts the student got wrong.
- The UI displays an alert banner in the Results tab. The student can switch back to the Quiz tab to complete their review questions, which will then be graded again by the Evaluator.
This project is licensed under the MIT License - see the LICENSE file for details.