README.md

---
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

- What strategy does your agent use?
- What tools did you implement in your MCP server?
- Any interesting techniques or optimizations?

I implemented the full reasoning loop as expected, but I tried to add internal state tracking and improve the interaction between the agent and the MCP server. I designed my agent to explore systematically rather than acting randomly. The agent keeps track of visited locations, previous actions, discovered exits and items in the inventory, in order to avoid repeating failed actions and loops, and try to help it to perform "quality" actions.

A key improvement I added is a "world model". The agent builds a map of locations and connections between them, including which exits work and which are blocked or explored. It also keeps a frontier of unexplored exits in mind and I tried to make it prioritize exploring these new locations first. To improve the understanding of the environment, I use the LLM to extract valid exits from descriptions of the current location and generate short summaries of locations and current status to guide future actions and make it focus on meaningful mentioned locations. I also implemented safeguards such as avoiding repeating the same failed action too many times or detecting when the agent is stuck.

I extended the MCP server by implementing the play_action tool and adding some tracking features inside the GameManager.I needed it to track action history, visited locations, location connections, score changes and movement transitions. I also implemented an exhaustive memory tool which returns a detailed context summary to give the agent structured information about the current status. I used an inventory tool as well.

Overall, compared to the original template, my main improvements include the internal world mapping, the priority for structured exploration using a frontier-based approach and unexplored exits tracking automated with the use of the LLM, improved prompt construction, locations summary also using the LLM, and safeguards to prevent loops, repeated failed actions and getting stuck.

## 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
```