README.md

metadata

title: Text Adventure Agent Submission
emoji: 🗺
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

The core idea is to treat the game as an exploration problem where locations are the main progress signal. The agent keeps a per-location memory: which actions have already been tried, short summaries of their outcomes, and a priority queue of promising actions. A key function detects whether we entered a new location; when available, we use Jericho's API (player location id / world state) for stable identification, and otherwise fall back to the observation header (first line).

At each step, the agent requests Jericho's get_valid_actions() through an MCP tool. This provides a high-quality action space and prevents wasted steps on invalid commands. On entering a location, the agent:

1. gathers valid actions,
2. extracts "promising" actions using heuristics from the observation (objects, containers, doors, readable items) and intersects them with valid actions,
3. explores exits systematically (untried directions first).

The agent also maintains a stagnation counter. If the location doesn't change after several actions, it forces exploration by trying an untried movement action. This prevents the common failure mode of getting stuck repeatedly examining items.

To make the LLM reliable, the prompt contains a compact state: current location, score/moves, inventory, recently tried actions in this location, and a short candidate list of actions ranked by exploration value. The LLM is instructed to pick from the candidate list; if it outputs something malformed, the agent falls back to the top-ranked candidate.

On the MCP server side, we track a lightweight map: (location → exits tried → resulting location), plus action history and score deltas. This supports memory() and get_map() tools for debugging and better agent behavior.

Tools implemented in MCP server

• play_action(action: str) -> str: executes a command and appends score/move/done info
• memory() -> str: current location id/name, score/moves, recent actions, last observation
• inventory() -> str: returns inventory without wasting steps when possible
• get_map() -> str: explored location graph (based on movements)
• get_valid_actions() -> str: Jericho valid actions for current state (trimmed)

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

# 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