README.md

metadata

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 (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:

   pip install -r requirements.txt
   

3. Set up environment variables (create a .env file or set them in your environment)
4. Run the application:

   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:

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:

# 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:

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.