README.md

metadata

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

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

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