README.md

---
title: GAIA Agent
emoji: 🌎
colorFrom: indigo
colorTo: indigo
sdk: gradio
sdk_version: 3.44.4
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480
---

# GAIA Agent - Grounded AI Assistant

![GAIA Agent Logo](https://huggingface.co/datasets/huggingface-course/documentation-images/resolve/main/en/chapter9/gaia-agent.png)

GAIA (Grounded AI Assistant) is a robust, LangGraph-based agent designed to provide accurate, well-reasoned responses by leveraging real-time web data and structured reasoning. This implementation offers a streamlined, production-ready version optimized for deployment on Hugging Face Spaces.

## Core Capabilities

GAIA Agent delivers high-quality answers through:

- **Web-Grounded Responses**: Retrieves current information from multiple search engines
- **Structured Reasoning Process**: Follows a systematic workflow for analysis, planning, and answer formulation
- **Adaptable Tool Usage**: Dynamically selects and executes appropriate tools based on question requirements
- **Robust Error Handling**: Includes multiple fallback mechanisms to ensure reliability

## Key Features

- **LangGraph Workflow Integration**: Manages the agent's reasoning process with a clear state-based approach
- **Multiple Search Backends**: Supports both DuckDuckGo and Serper API for web searches
- **Content Extraction**: Can analyze and extract relevant information from web pages
- **Memory Management**: Efficiently caches responses and manages conversation context
- **Special Case Detection**: Includes handling for edge cases like reversed text questions
- **Graceful Degradation**: Continues functioning even with limited API access or resources

## Setup & Installation

### Environment Requirements

The GAIA Agent requires the following environment variables:

```
OPENAI_API_KEY=your_openai_key_here
SERPER_API_KEY=your_serper_key_here  # Optional, falls back to DuckDuckGo
SUPABASE_URL=your_supabase_url       # Optional, for enhanced memory
SUPABASE_KEY=your_supabase_key       # Optional, for enhanced memory
```

### Installation Steps

1. Clone this repository
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
3. Set up environment variables (create a `.env` file or set them in your environment)
4. Run the application:
   ```bash
   python app.py
   ```

### Dependencies

The GAIA Agent requires the following key packages:

- `langchain` and `langgraph`: Core agent architecture components
- `langchain-openai`: Integration with OpenAI models
- `duckduckgo-search`: Web search capability
- `requests` and `beautifulsoup4`: Web content extraction
- `gradio`: User interface components

## Usage Instructions

### Basic Usage

1. Start the application with `python app.py`
2. Open the displayed URL in your browser
3. Type your question in the input box and click "Submit"
4. The agent will analyze your question, gather information, and provide a response

### API Usage

You can also use the agent programmatically by importing the `GAIAAgent` class:

```python
from agent import GAIAAgent

# Initialize the agent
agent = GAIAAgent()

# Process a question and get a simple string response
response = agent.process_question("What is the capital of France?")
print(response)

# Or get a detailed response with metadata
result = agent.query("What is the capital of France?")
print(result["answer"])
print(result["tools_used"])
```

### Testing the Agent

Run the test suite to verify the agent's functionality:

```bash
# Run all tests
python test_agent.py run

# Run specific test categories
python test_agent.py web     # Test web search functionality
python test_agent.py special # Test special case handling
python test_agent.py memory  # Test memory functionality
```

## Architecture & Design

The GAIA Agent follows a structured workflow implemented with LangGraph:

1. **Question Analysis**: Examines the question to determine its type, complexity, and required tools
2. **Plan Creation**: Generates a step-by-step plan for answering the question
3. **Tool Execution**: Runs necessary tools (web search, content extraction) according to the plan
4. **Answer Formulation**: Synthesizes information into a comprehensive, accurate response

### Component Architecture

```
GAIAAgent
├── LangGraph Workflow
│   ├── analyze_question()
│   ├── create_plan()
│   ├── execute_tool()
│   └── formulate_answer()
│
├── Tool Components
│   ├── WebSearchTool
│   │   ├── DuckDuckGo search
│   │   └── Serper API fallback
│   └── ContentExtractor
│
└── SimpleMemory
    ├── Conversation history
    └── Result caching
```

### File Structure

- `agent.py`: Core implementation of the GAIA Agent using LangGraph
- `app.py`: Gradio-based user interface for interacting with the agent
- `test_agent.py`: Comprehensive test suite for validating functionality
- `requirements.txt`: Required dependencies
- `run_test.py` and `run_test.sh`: Convenience scripts for testing

## API Requirements

For full functionality, GAIA requires:

- **OpenAI API**: Powers the large language model capabilities (required)
- **Serper API**: Alternative web search backend (optional, falls back to DuckDuckGo)
- **Supabase**: Enhanced memory capabilities (optional)

## Limitations & Known Issues

- **Rate Limiting**: Web search tools may be subject to rate limiting when used extensively
- **Content Extraction**: May struggle with some complex or JavaScript-heavy websites
- **Answer Quality**: Responses depend on the quality of available search results
- **Context Length**: Limited by the underlying LLM's context window size
- **Computation Time**: Complex questions requiring multiple searches may take longer to answer

## Troubleshooting

### Common Issues

1. **Missing API Keys**
   - Error: "Error: GAIA Agent is not initialized"
   - Solution: Ensure the required environment variables are set, especially `OPENAI_API_KEY`

2. **Search Limitations**
   - Error: "Error searching with DuckDuckGo"
   - Solution: Retry with a different search query or try enabling the Serper API

3. **Model Errors**
   - Error: "Error during question analysis" or "Error formulating answer"
   - Solution: Check your OpenAI API key and quota, or try a less complex question

4. **Web Content Issues**
   - Error: "Error extracting content"
   - Solution: The target website may be blocking scraping; try a different source

### Debug Mode

For enhanced debugging, modify the logging level in `agent.py`:

```python
logging.basicConfig(
    level=logging.DEBUG,  # Change from INFO to DEBUG
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```

## Extending GAIA

You can extend GAIA's capabilities by:

1. **Adding New Tools**: Implement new tools in the `execute_tool` function in `agent.py`
2. **Customizing Prompts**: Modify the prompt templates in `analyze_question`, `create_plan`, and `formulate_answer`
3. **Enhancing Memory**: Extend the `SimpleMemory` class with additional storage options
4. **Optimizing Search**: Implement additional search backends or content extraction methods

## License & Attribution

GAIA Agent is developed as part of the Hugging Face Agents course and is intended for educational and demonstration purposes.

---

*For more information, questions, or issues, please visit the repository on Hugging Face Spaces or submit an issue on GitHub.*