Autonomous AI agents compete in turn-based games with real economic stakes.
A production-ready template for building Agent Arenas - digital environments where AI agents powered by Large Language Models compete autonomously using standardized protocols for communication and payments.
This template enables you to build Agent Arenas - autonomous gaming environments where:
- AI Agents use Large Language Models (LLMs) to make strategic decisions
- Standardized Communication via the A2A (Agent-to-Agent) protocol
- Real Economic Stakes through x402 cryptocurrency micropayments
- Turn-Based Competition with asynchronous, fault-tolerant gameplay
- Type-Safe: Full TypeScript with strict mode enabled
- Modular Architecture: Clean separation of concerns (Arbiter, Gladiator, Games)
- Multi-LLM Support: Gemini, OpenAI, Anthropic, and Ollama
- Protocol-First: Open standards for maximum interoperability
- Plugin Games: Easy to add custom games
- Autonomous game tournaments
- AI strategy competitions
- Agent behavior research
- Economic simulation experiments
The system follows a Hub-and-Spoke topology:
+-----------------------------+
| ARBITER (Hub) |
| - Game Server |
| - Rule Enforcement |
| - State Management |
| - x402 Payment Collection |
+-------------+---------------+
|
+---------------------+---------------------+
| | |
v v v
+---------------+ +---------------+ +---------------+
| GLADIATOR #1 | | GLADIATOR #2 | | UI |
| - LLM Agent | | - LLM Agent | | - Dashboard |
| - A2A Server | | - A2A Server | | - Spectator |
+---------------+ +---------------+ +---------------+
| Component | Role | Technologies |
|---|---|---|
| Arbiter | Game host, state authority, payment collector | Express, A2A Client, x402 |
| Gladiator | AI player, decision maker | Google ADK, A2A Server, LLM SDKs |
| UI | Real-time spectator dashboard | Next.js, React, SSE |
- Google ADK - The "brain": LLM-powered cognitive reasoning
- A2A Protocol - The "voice": Standardized agent communication
- x402 - The "stakes": HTTP-based cryptocurrency micropayments
For detailed architecture documentation, see docs/ARCHITECTURE.md.
- Node.js 20.x or later (download)
- pnpm package manager:
npm install -g pnpm - Google Gemini API Key (get free key)
# 1. Clone or download this template
cd gaming-agent-template
# 2. Install dependencies
pnpm install
# 3. Build all packages
pnpm build
# 4. Set up environment
cp .env.example .envEdit .env and add your Gemini API key:
GOOGLE_API_KEY=your_actual_gemini_api_key_here# Starts Arbiter (3000) + 2 Gladiators (3001, 3002) + UI (4000)
./start-all.shOpen http://localhost:4000 to watch the agents compete in real-time.
Starting Arbiter...
Arbiter running on port 3000
Starting Gladiator 1...
Gladiator running on port 3001
Starting Gladiator 2...
Gladiator running on port 3002
Agent chose tool: guess { number: 50 }
Move applied: Too High
Agent chose tool: guess { number: 25 }
Move applied: Too Low
...
Game finished!
Winner: player1
# Run rock-paper-scissors instead of guess-number
./start-all.sh rock-paper-scissors
# Or set via environment
GAME_TYPE=rock-paper-scissors ./start-all.sh# OpenAI
MODEL_PROVIDER=openai MODEL_NAME=gpt-4o OPENAI_API_KEY=sk-... pnpm gladiator
# Anthropic
MODEL_PROVIDER=anthropic MODEL_NAME=claude-3-5-sonnet-20241022 ANTHROPIC_API_KEY=sk-ant-... pnpm gladiator
# Ollama (local)
MODEL_PROVIDER=ollama MODEL_NAME=llama3.1 pnpm gladiatorFor full configuration options, see docs/CONFIGURATION.md.
| Package | Location | Description |
|---|---|---|
| @gaming-agent/shared | packages/shared/ |
Type definitions and Zod schemas |
| @gaming-agent/arbiter | packages/arbiter/ |
Game server with A2A client and x402 middleware |
| @gaming-agent/gladiator | packages/gladiator/ |
AI agent with A2A server and multi-LLM support |
| @gaming-agent/ui | packages/ui/ |
Next.js dashboard with real-time SSE |
| Package | Location | Description |
|---|---|---|
| @gaming-agent/games-core | packages/games/core/ |
GameInterface and GameRegistry |
| @gaming-agent/game-guess-number | packages/games/guess-number/ |
Number guessing game (1-100) |
| @gaming-agent/game-rock-paper-scissors | packages/games/rock-paper-scissors/ |
Classic RPS game |
See docs/GAME-DEVELOPMENT.md for a complete guide on creating your own games.
Quick overview:
- Create package in
packages/games/your-game/ - Implement
GameInterfacefrom@gaming-agent/games-core - Define tools and system prompt for AI agents
- Build and run:
GAME_TYPE=your-game ./start-all.sh
| Document | Description |
|---|---|
| Architecture | System design, protocols, data flow |
| Configuration | Environment variables, LLM setup |
| Game Development | Creating custom games |
| Troubleshooting | Common issues and solutions |
This is a template project designed to be forked and customized.
- Fork for your game - Build poker, chess, or your own game
- Extend the architecture - Add features, improve performance
- Improve documentation - Add tutorials, examples, guides
- Report issues - Found a bug? Open an issue
- Share your creation - Built something cool? Let us know!
# Clone the repo
git clone https://github.com/HeimLabs/gaming-agent-template.git
cd gaming-agent-template
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run in development mode
pnpm dev- TypeScript strict mode
- Functional programming preferred
- Descriptive variable names
- Comments for complex logic
See CONTRIBUTING.md for detailed guidelines.
Built on top of cutting-edge open-source projects:
- Google ADK - Agent Development Kit for TypeScript
- A2A Protocol - Agent-to-Agent communication standard
- x402 - HTTP-based payment protocol by Coinbase
Special thanks to the teams building the future of autonomous agents.
Ready to build autonomous gaming arenas? Start coding!