README.md

metadata

title: Agentic Zork
emoji: 🎮
colorFrom: green
colorTo: purple
sdk: gradio
sdk_version: 6.5.1
app_file: app.py
pinned: true
license: mit
hf_oauth: true
short_description: 'Third assignment: Playing Zork has never been so boring!'

Text Adventure LLM Agent Project

Build AI agents to play classic text adventure games (Zork, Colossal Cave, Enchanter, etc.) using the Model Context Protocol (MCP) and HuggingFace models.

Overview

This project provides:

1. MCP Server - Exposes text adventure games as MCP tools using FastMCP
2. ReAct Agent - An agent that uses MCP tools to play games with reasoning
3. Submission Template - Starter code for students to implement their own solutions
4. Evaluation System - Deterministic evaluation with seeded runs
5. 57 Games - Zork trilogy, Infocom classics, and many more Z-machine games

Architecture

+-------------------+     MCP Protocol     +------------------+
|                   | <------------------> |                  |
|   ReAct Agent     |    (tool calls)      |   MCP Server     |
|   (FastMCP Client)|                      |   (FastMCP)      |
|                   |                      |                  |
+-------------------+                      +------------------+
        |                                           |
        | LLM API                                   | Game API
        v                                           v
+-------------------+                      +------------------+
|   HuggingFace     |                      |   Text Adventure |
|   Inference API   |                      |   (Jericho)      |
+-------------------+                      +------------------+

Quick Start

1. Download Game Files

The Z-machine game files are not included in this repository. Clone them from the BYU-PCCL repository:

git clone https://github.com/BYU-PCCL/z-machine-games z-machine-games-master

This provides 57 classic text adventure games including the Zork trilogy, Colossal Cave Adventure, Enchanter, and more.

2. Setup

# Create virtual environment (using uv recommended)
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your HuggingFace token (HF_TOKEN)

Get your HuggingFace token at: https://huggingface.co/settings/tokens

3. Run an Agent

# Run the example MCP agent
python run_agent.py

# Play a different game
python run_agent.py --game advent

# Verbose output
python run_agent.py -v

# Limit steps
python run_agent.py -n 50

# List all 57 games
python run_agent.py --list-games

Project Structure

.
+-- run_agent.py              # Agent runner
+-- app.py                    # Gradio interface
+-- evaluation/               # Evaluation system
|   +-- evaluate.py           # Evaluation CLI (local and HF Spaces)
|   +-- runner.py             # Agent execution
|   +-- metrics.py            # Result tracking
+-- submission_template/      # Student templates (HF Space template)
|   +-- README.md             # Assignment instructions
|   +-- agent.py              # Agent starter code
|   +-- mcp_server.py         # MCP server starter code
|   +-- app.py                # HF Spaces Gradio app
|   +-- requirements.txt      # Space dependencies
+-- games/
|   +-- zork_env.py           # Jericho wrapper
+-- z-machine-games-master/   # Game files

Student Submission Workflow (Hugging Face Spaces)

1. Fork the template Space on Hugging Face:

   https://huggingface.co/spaces/[COURSE]/text-adventure-template
   

2. Clone your fork locally:

   git clone https://huggingface.co/spaces/YOUR_USERNAME/text-adventure-agent
   cd text-adventure-agent
   

3. Implement your agent in agent.py and mcp_server.py

4. Test locally:

   # Test MCP server interactively
   fastmcp dev mcp_server.py
   
   # Run your agent
   python run_agent.py --agent . --game zork1 -v -n 20
   

5. Push to your Space:

   git add -A
   git commit -m "Implement my agent"
   git push
   

6. Submit your Space URL on the course platform

Assignment

See submission_template/README.md for the assignment instructions.

You need to implement:

1. MCP Server (mcp_server.py) - Expose game functionality as MCP tools
2. ReAct Agent (agent.py) - Play text adventures using MCP tools

Evaluation

Run the evaluator to test submissions:

# Evaluate a submission
python evaluation/evaluate.py -s ./submission_template -g zork1 -t 5

# Evaluate the example
python evaluation/evaluate.py -s ./submission_template -g zork1 -t 3

# Evaluate multiple games
python evaluation/evaluate.py -s ./submission_template -g zork1 advent enchanter -t 3

# Save results to JSON
python evaluation/evaluate.py -s ./submission_template -g zork1 -t 3 -o results.json

Configuration

Environment Variables

Create .env from .env.example:

# Required: HuggingFace token
HF_TOKEN=hf_your_token_here

Fixed Model

All submissions use the same model for fairness:

• Model: Qwen/Qwen2.5-72B-Instruct
• Temperature: 0.0 (deterministic)
• Seed: Provided for reproducibility

License

MIT