README.md

---
title: Isadora Teles - GAIA Agent - Final HF Agents Project
emoji: 🤖
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480
---

# 🎓 My GAIA RAG Agent - AI Agents Course Final Project

**Author:** Isadora Teles  
**Course:** AI Agents with LlamaIndex  
**Goal:** Build an agent that achieves 30%+ on the GAIA benchmark

## 📚 Project Overview

This is my final project for the AI Agents course. I've built a RAG (Retrieval-Augmented Generation) agent to tackle the challenging GAIA benchmark, which tests AI agents on diverse real-world questions.

### What I Built
- **Multi-LLM Agent**: Supports 5+ different LLMs with automatic fallback
- **Custom Tools**: Web search, calculator, file analyzer, and more
- **Smart Answer Extraction**: Handles GAIA's exact-match requirements
- **Robust Error Handling**: Manages rate limits and API failures gracefully

## 🚀 My Learning Journey

### Week 1: Initial Struggles
- Started with `AgentWorkflow` - too complex!
- Couldn't get past 0% due to answer formatting issues
- Learned that GAIA uses **exact string matching**

### Week 2: Architecture Switch
- Switched to `ReActAgent` - much simpler and more reliable
- Fixed LLM compatibility issues (especially with Groq)
- Discovered the importance of good system prompts

### Week 3: Fine-tuning
- Implemented comprehensive answer extraction
- Added special handling for:
  - Missing files → "No file provided"
  - Botanical fruits vs vegetables
  - Reversed text questions
  - Name extraction from verbose responses

### Week 4: Optimization
- Added multi-LLM fallback for rate limits
- Reduced token usage to conserve API limits
- Achieved **25%** and pushing for **30%+**!

## 🔧 Technical Architecture

```
┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
│   Multi-LLM     │────▶│ ReAct Agent  │────▶│    Tools    │
│   Manager       │     │              │     │             │
└─────────────────┘     └──────────────┘     └─────────────┘
         │                      │                     │
         ▼                      ▼                     ▼
   [Gemini, Groq,         [Reasoning &          [Web Search,
    Claude, etc.]          Planning]            Calculator,
                                               File Analyzer]
```

## 💡 Key Learnings

1. **Exact Match is Unforgiving**
   - "4 albums" ≠ "4" in GAIA's evaluation
   - Every character matters!

2. **Simple > Complex**
   - ReActAgent outperformed AgentWorkflow
   - Clear prompts beat clever engineering

3. **Tool Design Matters**
   - Good descriptions guide the agent
   - Error messages should be actionable

4. **LLM Diversity is Key**
   - Different LLMs have different strengths
   - Rate limits require fallback strategies

## 🛠️ Setup Instructions

### 1. Clone and Install
```bash
git clone [your-repo]
pip install -r requirements.txt
```

### 2. Set API Keys
Create a `.env` file or set in HuggingFace Spaces:
```
# Choose at least one LLM
GEMINI_API_KEY=your_key      # Recommended
GROQ_API_KEY=your_key        # Fast but limited
ANTHROPIC_API_KEY=your_key   # High quality

# For web search
GOOGLE_API_KEY=your_key
GOOGLE_CSE_ID=your_cse_id
```

### 3. Run Locally
```bash
python app.py
```

## 📊 Performance Metrics

| Metric | Value | Notes |
|--------|-------|-------|
| Target Score | 30% | Course requirement |
| Current Best | 25% | Close to target! |
| Avg Response Time | 8-15s | Depends on LLM |
| Questions Handled | 20/20 | All question types |

## 🎯 GAIA Question Types I Handle

1. **Web Search Questions**
   - Current events
   - Wikipedia lookups
   - Fact verification

2. **Math & Calculations**
   - Arithmetic operations
   - Python code execution
   - Percentage calculations

3. **File Analysis**
   - CSV/Excel processing
   - Python code analysis
   - Missing file detection

4. **Special Cases**
   - Reversed text puzzles
   - Botanical classification
   - Name extraction

## 🐛 Known Issues & Solutions

### Issue 1: Rate Limits
**Problem:** Groq limits to 100k tokens/day  
**Solution:** Automatic LLM switching

### Issue 2: File Not Found
**Problem:** Questions mention files that aren't provided  
**Solution:** Return "No file provided" instead of error

### Issue 3: Long Answers
**Problem:** Agent gives explanations when only name needed  
**Solution:** Enhanced answer extraction with patterns

## 🔮 Future Improvements

If I had more time, I would:
1. Add vision capabilities for image questions
2. Implement caching to reduce API calls
3. Create a custom fine-tuned model
4. Add more sophisticated web scraping

## 🙏 Acknowledgments

- **Course Instructors** - For the excellent LlamaIndex tutorials
- **GAIA Team** - For creating such a challenging benchmark
- **Open Source Community** - For all the amazing tools

## 📝 Lessons for Fellow Students

1. **Start Simple** - Don't overcomplicate your first version
2. **Log Everything** - Debugging is easier with good logs
3. **Test Incrementally** - Fix one question type at a time
4. **Read the Docs** - GAIA's exact requirements are crucial
5. **Ask for Help** - The community is super helpful!

## 🎉 Final Thoughts

This project taught me that building AI agents is as much about handling edge cases as it is about the core logic. Every percentage point on GAIA represents hours of debugging and learning. 

Even if I don't hit 30%, I've learned invaluable lessons about:
- Production-ready agent development
- Multi-LLM orchestration
- Tool design and integration
- The importance of precise specifications