---
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.  
Author: Félix LEBEL

## Approach

<!-- Describe your approach here -->

### What strategy does your agent use?
General strategy: The agent is encourage to explore (use mouvement actions) and examine/interact with its environment as possible.

Here is an excerpt from my system prompt:
EXPLORATION STRATEGY (follow this priority):
1. EXPLORE a lot! Try new locations and exits frequently (north, south, east, west, northeast, northwest, southeast, southwest, up, down, enter, exit)
2. ALWAYS EXAMINE everything that could be interesting, especially details in objects, rooms... EXAMINE where you could find some loot or useful items, or clues for puzzles. INTERACT with characters and objects to discover new possibilities.
3. ALWAYS take items that seem useful (lamp, sword, key, etc.)
4. Open containers (mailbox, cases, doors, windows)
5. Try ALL exits from a location before moving on
6. Use get_map and location_log frequently to plan which unexplored exits to try, and what actions to take. It also helps you remember what you've tried at the current location and their outcomes, so you can avoid repeating failed actions and focus on promising ones.
7. Use memory to check if you're repeating yourself
8. If you've been in the same location for 3+ turns, MOVE to a new location

### What tools did you implement in your MCP server?

```python
def play_action(action: str) -> str:
    """
    Execute a game command and return the result.
    
    This is the main tool for interacting with the game.
    
    Args:
        action: The command to execute (e.g., "north", "take lamp", "open mailbox")
        
    Returns:
        The game's response to the action
        
    Valid commands include:
        - Movement: north, south, east, west, northeast, northwest, southeast, southwest, up, down, enter, exit
        - Objects: take <item>, drop <item>, open <thing>, examine <thing>
        - Other: look, inventory, read <thing>, turn on lamp
    """
```
```python
def memory() -> str:
    """
    Get the current game state summary.
    
    Returns:
        A summary including current location (number of visits, actions tried, promising actions), 
        recent actions and current observation
    """
```
```python
def inventory() -> str:
    """
    Check what the player is carrying.
    
    Returns:
        List of items in the player's inventory
    """
    return get_game().get_inventory()
```
```python
def get_map() -> str:
    """
    Get a map of explored locations, connections and exits.
    Useful for navigation and avoiding getting lost.
    
    Returns:
        A text representation of explored locations and connections
    """
```
```python
def location_log() -> str:
    """
    Shows what actions were tried and their outcomes at the current location, along with any promising actions to try.
    
    
    Returns:
        A detailed log of the current location, including visit count, actions taken and their outcomes, and promising leads.
    """
```
### Any interesting techniques or optimizations?

Here list of ideas and techniques I implemented:
- I used Jericho API to extract cleaner Locations
- I used these "cleaner" locations to write a function that determines when a player enters a new location
- I kept the log of every actions (I made the distinction between movements and non-movement actions) at every locations
- When building the LLM prompt for the agent, I implemented another LLM whose task is to extract promising actions from: the current observation, the general history of actions/tool calls taken by the agent and the log of actions taken by the agent at the specific current locations (to prevent the agent from getting stuck, and for it to be aware of its last actions)
- I implemented an "Exploration Pressure" in several ways:
    * if the agent stays too long at the same locations, the LLM-agent-prompt changes and suggest more movements (or using get_map, or look)
    * if the agents keeps coming again and again to the same location while having already massively interact with objects, I show him the directions/movements it hasn't already tried (at the current location)
- I refined massively the system prompt and the extraction prompt

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