README.md

metadata

title: GAIA Final Agent
emoji: 🕵️
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
hf_oauth: true

GAIA Final Agent

A submission for the Hugging Face Agents Course Unit 4 final assignment.

It runs a LangGraph ReAct agent over the 20 filtered GAIA level-1 validation questions, then submits the answers to the course scoring API for leaderboard placement.

Architecture

File	Responsibility
app.py	Gradio UI: HF OAuth login, fetch questions, run agent, submit answers.
agent.py	GaiaAgent — a LangGraph create_react_agent loop over a HF Inference chat model, with a GAIA-formatted system prompt and answer cleanup.
tools.py	Tools bound to the agent: web_search, wikipedia_search, visit_webpage, read_task_file, calculator.

The agent uses the Hugging Face Inference API as its LLM backend (Qwen/Qwen2.5-72B-Instruct by default, which supports tool calling).

Setup

On a Hugging Face Space (recommended)

1. Duplicate / create a Gradio Space and push these files.
2. In Settings → Variables and secrets, add a secret named HF_TOKEN containing a Hugging Face access token with Inference permission.
3. Open the Space, log in with the Hugging Face button, then click Run Evaluation & Submit All Answers.

Keep the Space public so the leaderboard's code link works.

Locally

pip install -r requirements.txt
# PowerShell:
$env:HF_TOKEN = "hf_xxx"
python app.py

Then open the printed local URL.

Behind a corporate TLS-intercepting proxy? If you see CERTIFICATE_VERIFY_FAILED: self-signed certificate in certificate chain, install pip install pip-system-certs so Python trusts the Windows certificate store (where your corporate CA lives). This is only needed locally — it is not required on a Hugging Face Space.

Configuration (environment variables)

Variable	Default	Purpose
GAIA_BACKEND	hf	hf = HF Inference API; groq = Groq free API; ollama = local (free).
HF_TOKEN	—	HF token for the Inference API (required when GAIA_BACKEND=hf).
GROQ_API_KEY	—	Groq key (required when GAIA_BACKEND=groq); get one at https://console.groq.com/keys.
GAIA_MODEL_ID	Qwen/Qwen2.5-7B-Instruct	HF Inference model.
GAIA_GROQ_MODEL	llama-3.3-70b-versatile	Groq model (must support tool calling).
GAIA_OLLAMA_MODEL	qwen2:7b	Local Ollama model (must support tool calling).
GAIA_API_URL	https://agents-course-unit4-scoring.hf.space	Scoring API base URL.

Free Groq backend (fast, no HF credits)

Groq has a generous free tier and very fast, tool-capable models. Create a key at https://console.groq.com/keys, then:

$env:GAIA_BACKEND = "groq"
$env:GROQ_API_KEY = "gsk_..."
python submit_official.py

Free local backend (no HF credits)

If your HF Inference credits are depleted, run a local model with Ollama instead — no quota, fully offline:

ollama pull qwen2:7b          # tool-capable; qwen2.5:7b / llama3.1:8b also work
$env:GAIA_BACKEND = "ollama"
python submit_official.py

Notes

• Answers are graded by exact string match, so the system prompt enforces the GAIA answer-format rules and the code strips stray prefixes/quotes.
• Per the course guidance, the agent never emits the literal text "FINAL ANSWER" — it replies with the answer only.