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

• Strategy: score-first ReAct with explicit anti-loop controls and exploration frontier bias.
• The agent tracks repeated (location, action) pairs and loop signals, then overrides low-yield repeated actions with unexplored movement.
• Prompting includes compact recent history, score/move/loop diagnostics, inventory snapshot, and map frontier hints.
• Tool usage is constrained so play_action dominates turns; planning tools are used mainly when stagnation appears.

Implemented MCP tools in mcp_server.py:

• play_action(action) executes commands and appends score + loop diagnostics.
• memory() returns state summary, recent history, and notes.
• inventory() returns current inventory without consuming a move.
• get_map() returns explored transitions and untried frontier directions.
• get_stats() returns compact JSON-like state used by the agent for robust tracking.
• remember(key, value) / recall(key) provide persistent note memory for clues.

Interesting optimizations:

• Stagnation-aware action override (no_progress_streak, repeated actions, same-location streak).
• Frontier extraction from map snapshots for systematic exploration.
• Robust parser/validator for LLM tool calls (malformed JSON and tool alias handling).

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