Skip to content
Back to search

text_adventure_agent

It is an MCP server in Python that exposes the actions and observations of a game environment to LLM-based agents. It involves integration of tools that enable agents to interact with their environment via standardized interfaces. Main code is in submission_template folder.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fatima-alharake--text-adventure-agent/badge.svg)](/listings/fatima-alharake--text-adventure-agent)

HTML

<a href="/listings/fatima-alharake--text-adventure-agent"><img src="/api/listings/fatima-alharake--text-adventure-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 222 lines
  1. ---
  2. title: Agentic Zork
  3. emoji: 🎮
  4. colorFrom: green
  5. colorTo: purple
  6. sdk: gradio
  7. sdk_version: 6.3.0
  8. app_file: app.py
  9. pinned: false
  10. license: mit
  11. hf_oauth: true
  12. ---
  13. # Text Adventure LLM Agent Project
  14. Build AI agents to play classic text adventure games (Zork, Colossal Cave, Enchanter, etc.) using the Model Context Protocol (MCP) and HuggingFace models.
  15. ## Overview
  16. This project provides:
  17. 1. **MCP Server** - Exposes text adventure games as MCP tools using FastMCP
  18. 2. **ReAct Agent** - An agent that uses MCP tools to play games with reasoning
  19. 3. **Submission Template** - Starter code for students to implement their own solutions
  20. 4. **Evaluation System** - Deterministic evaluation with seeded runs
  21. 5. **57 Games** - Zork trilogy, Infocom classics, and many more Z-machine games
  22. ## Architecture
  23. ```
  24. +-------------------+ MCP Protocol +------------------+
  25. | | <------------------> | |
  26. | ReAct Agent | (tool calls) | MCP Server |
  27. | (FastMCP Client)| | (FastMCP) |
  28. | | | |
  29. +-------------------+ +------------------+
  30. | |
  31. | LLM API | Game API
  32. v v
  33. +-------------------+ +------------------+
  34. | HuggingFace | | Text Adventure |
  35. | Inference API | | (Jericho) |
  36. +-------------------+ +------------------+
  37. ```
  38. ## Quick Start
  39. ### 1. Download Game Files
  40. The Z-machine game files are not included in this repository. Clone them from the BYU-PCCL repository:
  41. ```bash
  42. git clone https://github.com/BYU-PCCL/z-machine-games z-machine-games-master
  43. ```
  44. This provides 57 classic text adventure games including the Zork trilogy, Colossal Cave Adventure, Enchanter, and more.
  45. ### 2. Setup
  46. ```bash
  47. # Create virtual environment (using uv recommended)
  48. uv venv
  49. source .venv/bin/activate
  50. # Install dependencies
  51. uv pip install -r requirements.txt
  52. # Configure environment
  53. cp .env.example .env
  54. # Edit .env and add your HuggingFace token (HF_TOKEN)
  55. ```
  56. Get your HuggingFace token at: https://huggingface.co/settings/tokens
  57. ### 3. Run an Agent
  58. ```bash
  59. # Run the example MCP agent
  60. python run_agent.py
  61. # Play a different game
  62. python run_agent.py --game advent
  63. # Verbose output
  64. python run_agent.py -v
  65. # Limit steps
  66. python run_agent.py -n 50
  67. # List all 57 games
  68. python run_agent.py --list-games
  69. ```
  70. ## Project Structure
  71. ```
  72. .
  73. +-- run_agent.py # Agent runner
  74. +-- app.py # Gradio interface
  75. +-- evaluation/ # Evaluation system
  76. | +-- evaluate.py # Evaluation CLI (local and HF Spaces)
  77. | +-- runner.py # Agent execution
  78. | +-- metrics.py # Result tracking
  79. +-- example_submission/ # Working example submission
  80. | +-- agent.py # Full ReAct agent implementation
  81. | +-- mcp_server.py # Full MCP server implementation
  82. +-- submission_template/ # Student templates (HF Space template)
  83. | +-- README.md # Assignment instructions
  84. | +-- agent.py # Agent starter code
  85. | +-- mcp_server.py # MCP server starter code
  86. | +-- app.py # HF Spaces Gradio app
  87. | +-- requirements.txt # Space dependencies
  88. +-- games/
  89. | +-- zork_env.py # Jericho wrapper
  90. +-- z-machine-games-master/ # Game files
  91. ```
  92. ## Student Submission Workflow (Hugging Face Spaces)
  93. ### For Students
  94. 1. **Fork the template Space** on Hugging Face:
  95. ```
  96. https://huggingface.co/spaces/[COURSE]/text-adventure-template
  97. ```
  98. 2. **Clone your fork locally**:
  99. ```bash
  100. git clone https://huggingface.co/spaces/YOUR_USERNAME/text-adventure-agent
  101. cd text-adventure-agent
  102. ```
  103. 3. **Implement your agent** in `agent.py` and `mcp_server.py`
  104. 4. **Test locally**:
  105. ```bash
  106. # Test MCP server interactively
  107. fastmcp dev mcp_server.py
  108. # Run your agent
  109. python run_agent.py --agent . --game zork1 -v -n 20
  110. ```
  111. 5. **Push to your Space**:
  112. ```bash
  113. git add -A
  114. git commit -m "Implement my agent"
  115. git push
  116. ```
  117. 6. **Submit** your Space URL on the course platform
  118. ### For Instructors
  119. Evaluate student submissions from their HF Spaces:
  120. ```bash
  121. # Evaluate a single Space
  122. python evaluation/evaluate.py --hf-space student1/text-adventure-agent -g zork1 -t 5
  123. # Evaluate a local submission
  124. python evaluation/evaluate.py -s ./example_submission -g zork1 -t 5
  125. # Batch evaluate multiple local submissions
  126. python evaluation/evaluate.py --submissions-dir ./all_submissions -g zork1 -o results.json
  127. ```
  128. ## Assignment
  129. See [submission_template/README.md](submission_template/README.md) for the assignment instructions.
  130. You need to implement:
  131. 1. **MCP Server** (`mcp_server.py`) - Expose game functionality as MCP tools
  132. 2. **ReAct Agent** (`agent.py`) - Play text adventures using MCP tools
  133. A working example is provided in `example_submission/`.
  134. ## Evaluation
  135. Run the evaluator to test submissions:
  136. ```bash
  137. # Evaluate a submission
  138. python evaluation/evaluate.py -s ./submission_template -g zork1 -t 5
  139. # Evaluate the example
  140. python evaluation/evaluate.py -s ./example_submission -g zork1 -t 3
  141. # Evaluate multiple games
  142. python evaluation/evaluate.py -s ./example_submission -g zork1 advent enchanter -t 3
  143. # Save results to JSON
  144. python evaluation/evaluate.py -s ./example_submission -g zork1 -t 3 -o results.json
  145. ```
  146. Metrics:
  147. - **Score**: Points earned in-game (averaged over trials)
  148. - **Score %**: Score / Max possible score
  149. - **Steps**: Number of actions taken
  150. - **Time**: Elapsed time
  151. ## Configuration
  152. ### Environment Variables
  153. Create `.env` from `.env.example`:
  154. ```bash
  155. # Required: HuggingFace token
  156. HF_TOKEN=hf_your_token_here
  157. ```
  158. ### Fixed Model
  159. All submissions use the same model for fairness:
  160. - **Model**: `Qwen/Qwen2.5-72B-Instruct`
  161. - **Temperature**: `0.0` (deterministic)
  162. - **Seed**: Provided for reproducibility
  163. ## License
  164. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.