---
title: Text Adventure Agent Submission
emoji: "\U0001F5FA"
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: "5.12.0"
app_file: app.py
pinned: false
license: mit
---

# Text Adventure Agent Submission

## Overview

This is my submission for the Text Adventure Agent assignment. My agent uses the ReAct pattern to play text adventure games via MCP.

## Approach

### Agent Strategy

The agent follows the **ReAct pattern**: for each step, it produces a `REASONING` sentence, chooses a `TOOL`, and provides `ARGS` in JSON. This structured format makes the LLM output easy to parse and keeps responses short and focused.

At each step, the agent builds a rich prompt that includes:
- The current game observation
- The last 10 actions and their results
- The list of actions that already **failed** at the current location
- The list of **all attempted** actions at the current location
- Warnings when a loop or a stuck situation is detected

### MCP Server Tools

The MCP server exposes 5 tools to the agent:

| Tool | Description |
|------|-------------|
| `play_action` | Executes a game command and returns the observation + score info |
| `memory` | Returns a full summary: location, score, recent history, failed actions |
| `get_map` | Shows all explored locations and their directional connections |
| `inventory` | Lists the items currently carried by the player |
| `get_failed_actions` | Returns actions that were rejected or had no effect at a given location |

### Interesting Techniques

- **Anti-loop engine**: The agent has a 3-level system to break out of loops. If the same action is repeated 3 times in a row, it is replaced automatically. If an action was already tried at the current location, a different one is picked. If the agent is stuck for 10+ turns, it rotates through a list of escape actions (directions, `listen`, `wait`, etc.).
- **Per-location memory**: Failed and attempted actions are stored separately for each room. This means the agent never wastes a turn trying something it already knows does not work in that specific place.
- **Score-delta awareness**: Every tool response includes the score change. The agent is instructed to prefer actions that have earned points before.
- **Forbidden verb replacement**: The server and agent both replace verbs that confuse the Z-machine parser (e.g., `search` → `examine`, `grab` → `take`) to avoid unnecessary failures.
- **Automatic map building**: Each time the agent moves to a new room, the connection is recorded in a graph. The `get_map` tool presents this as a readable text map so the agent can plan routes without backtracking.

## Files

| File | Description |
|------|-------------|
| `agent.py` | ReAct agent with `StudentAgent` class |
| `mcp_server.py` | MCP server with game interaction tools |
| `app.py` | Gradio interface for HF Space |
| `requirements.txt` | Additional dependencies |

## How to Submit

1. Fork the template Space: `https://huggingface.co/spaces/LLM-course/text-adventure-template`
2. Clone your fork locally
3. Implement your agent in `agent.py` and `mcp_server.py`
4. Test locally (see below)
5. Push your changes to your Space
6. Submit your Space URL on the course platform

## Local Testing

```bash
# Install dependencies
pip install -r requirements.txt

# Test the MCP server interactively
fastmcp dev mcp_server.py

# Run your agent on a game
python run_agent.py --agent . --game lostpig -v -n 20

# Run evaluation
python -m evaluation.evaluate -s . -g lostpig -t 3
```