README.md

---
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](https://huggingface.co/learn/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

```bash
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](https://console.groq.com) has a generous free tier and very fast,
tool-capable models. Create a key at https://console.groq.com/keys, then:

```powershell
$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](https://ollama.com) instead — no quota, fully offline:

```powershell
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.