solarianofc/gaia-agent

GAIA agent (Hugging Face Agents Course, Unit 4)

A smolagents CodeAgent for the final assignment of the Hugging Face Agents Course (GAIA level 1 subset).

• Model: deepseek/deepseek-v4-flash-0731 via OpenRouter
• Local score: 17/20 (85%) against the GAIA validation answers

Code

• alfred/gaia/runner.py: builds the agent (build_gaia_agent), runs the questions with an answer cache, and submits them
• alfred/gaia/tools.py: the GAIA tools
• alfred/gaia/api.py: the client for the course scoring API
• alfred/gaia/scoring.py: answer cleanup and local scoring
• common/models.py: model factories (OpenRouter / Ollama)

Tools

Tool	What it does
web_search	Tavily search with a query cache (falls back to DuckDuckGo without TAVILY_API_KEY)
wiki_search	Wikipedia full-text search, plain text of the best articles
wiki_page	A Wikipedia page by exact title or URL as markdown with tables, a single section, or an old revision (as_of)
visit_webpage	Any webpage as compact markdown (navigation and link URLs stripped; hidden sections listed on truncation)
read_file	Attachments: csv/xlsx, text/code, audio (faster-whisper), images (description from a vision model)
youtube_transcript	YouTube subtitles via youtube-transcript-api

Running

The agent needs these environment variables:

• OPENROUTER_API_KEY
• TAVILY_API_KEY
• HF_TOKEN: lets the agent download attachments from the gated gaia-benchmark/GAIA dataset

Install and run:

pip install -r requirements.txt
AGENTS_PROVIDER=openrouter OPENROUTER_MODEL=deepseek/deepseek-v4-flash-0731 python -m alfred.gaia.runner