💣 Minesweeper Agent - Play Minesweeper with a Local LLM
This case uses a 4×4 Minesweeper board as the Agent's runtime environment, demonstrating how an Agent interacts with an environment through tools and corrects its behavior based on feedback. The model is Gemma 4 E4B-it Q4_K_M, served via llama.cpp with an OpenAI-compatible API.
- Notebook: minesweeper_agent.ipynb
- Game environment: minesweeper_game.py
What's Covered
- Structural differences between a Chatbot and an Agent.
- Downloading, starting, and verifying llama.cpp (ROCm prebuilt).
- Minesweeper environment initialization and manual interaction.
- Step-by-step Agent loop breakdown: Observation → Candidate Actions → LLM selection → Tool execution → Feedback.
- Comparison experiment: model free-generation vs Python deterministic candidates.
- Full constrained Agent loop (with candidate actions).
- Full autonomous Agent loop (with action history + retry mechanism).
- Stability design: candidate action constraints, low temperature, JSON format, fallback, action history.
Prerequisites
Option 1: AMD Radeon Cloud (no local GPU required)
If you don't have an AMD GPU, you can use the official AMD free cloud compute platform. Log in via browser and run the Jupyter Notebook directly:
- Platform: https://developer.amd.com.cn/login?source=91kadjjnI
- 100 free GPU hours upon registration
- Built-in Jupyter environment, no local setup needed
See the full guide: AMD Radeon Cloud
Option 2: Local Setup
Hardware:
- AMD GPU with ROCm 7.0+ support (e.g., Ryzen AI Max+ 395, Radeon RX 7000/9000 series)
Software:
- Ubuntu 24.04 or Windows 11 (ROCm 7.12+)
- Python 3.12
- Jupyter Notebook
Local environment setup:
bash
# Create virtual environment
uv venv --python=3.12
source .venv/bin/activate # Linux
# .venv\Scripts\activate # Windows
# Install dependencies
uv pip install jupyter requestsLaunch the Notebook:
bash
cd src/amd-yes/minesweeper_agent/
jupyter notebookInference Service
- llama.cpp ROCm prebuilt (lemonade-sdk/llamacpp-rocm b1292)
- Model: Gemma 4 E4B-it Q4_K_M GGUF (~5.4 GB)
📖 For full ROCm environment setup, see 00-Environment.
Model Download
ModelScope (direct access from China, no login required):
bash
wget https://www.modelscope.cn/models/bartowski/google_gemma-4-E4B-it-GGUF/resolve/master/google_gemma-4-E4B-it-Q4_K_M.ggufHugging Face:
bash
wget https://huggingface.co/bartowski/google_gemma-4-E4B-it-GGUF/resolve/main/google_gemma-4-E4B-it-Q4_K_M.gguf