Content
# Gaming Agent Template
**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.
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://pnpm.io/)
---
## Table of Contents
- [Overview](#overview)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Package Guide](#package-guide)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Acknowledgments](#acknowledgments)
---
## Overview
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
### Key Features
- **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
### Use Cases
- Autonomous game tournaments
- AI strategy competitions
- Agent behavior research
- Economic simulation experiments
---
## Architecture
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 Roles
| 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 |
### The Three Pillars
1. **Google ADK** - The "brain": LLM-powered cognitive reasoning
2. **A2A Protocol** - The "voice": Standardized agent communication
3. **x402** - The "stakes": HTTP-based cryptocurrency micropayments
For detailed architecture documentation, see [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
---
## Quick Start
### Prerequisites
- **Node.js** 20.x or later ([download](https://nodejs.org/))
- **pnpm** package manager: `npm install -g pnpm`
- **Google Gemini API Key** ([get free key](https://aistudio.google.com/app/apikey))
### Installation
```bash
# 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 .env
```
### Configuration
Edit `.env` and add your Gemini API key:
```bash
GOOGLE_API_KEY=your_actual_gemini_api_key_here
```
### Run the Demo
```bash
# Starts Arbiter (3000) + 2 Gladiators (3001, 3002) + UI (4000)
./start-all.sh
```
Open http://localhost:4000 to watch the agents compete in real-time.
### Expected Output
```
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
```
### Running with Different Games
```bash
# 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
```
### Running with Different LLMs
```bash
# 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 gladiator
```
For full configuration options, see [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).
---
## Package Guide
### Core Packages
| 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 |
### Game Packages
| 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 |
### Creating Custom Games
See [docs/GAME-DEVELOPMENT.md](./docs/GAME-DEVELOPMENT.md) for a complete guide on creating your own games.
Quick overview:
1. Create package in `packages/games/your-game/`
2. Implement `GameInterface` from `@gaming-agent/games-core`
3. Define tools and system prompt for AI agents
4. Build and run: `GAME_TYPE=your-game ./start-all.sh`
---
## Documentation
| Document | Description |
|----------|-------------|
| [Architecture](./docs/ARCHITECTURE.md) | System design, protocols, data flow |
| [Configuration](./docs/CONFIGURATION.md) | Environment variables, LLM setup |
| [Game Development](./docs/GAME-DEVELOPMENT.md) | Creating custom games |
| [Troubleshooting](./docs/TROUBLESHOOTING.md) | Common issues and solutions |
### External Resources
- [Google ADK Docs](https://google.github.io/adk-docs/)
- [A2A Protocol Specification](https://a2aprotocol.ai/)
- [x402 Whitepaper](https://www.x402.org/x402-whitepaper.pdf)
---
## Contributing
This is a template project designed to be forked and customized.
### Ways to Contribute
1. **Fork for your game** - Build poker, chess, or your own game
2. **Extend the architecture** - Add features, improve performance
3. **Improve documentation** - Add tutorials, examples, guides
4. **Report issues** - Found a bug? Open an issue
5. **Share your creation** - Built something cool? Let us know!
### Development Setup
```bash
# 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
```
### Code Style
- TypeScript strict mode
- Functional programming preferred
- Descriptive variable names
- Comments for complex logic
See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
---
## Acknowledgments
Built on top of cutting-edge open-source projects:
- **[Google ADK](https://github.com/google/adk-js)** - Agent Development Kit for TypeScript
- **[A2A Protocol](https://github.com/a2aproject/a2a-js)** - Agent-to-Agent communication standard
- **[x402](https://github.com/coinbase/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!**
