Content
# 🏁 DotNet AI Chess
[](https://dotnet.microsoft.com/download)
[](https://avaloniaui.net/)
[](https://a2aproject.github.io/A2A/)
**A distributed chess application using the Agent2Agent (A2A) Protocol for agent communication, featuring AI-powered gameplay with real-time visualization.**
## 🎯 Project Overview
This project demonstrates the **Agent2Agent (A2A) Protocol v0.2.9** through an engaging chess application where AI agents communicate over HTTP using JSON-RPC 2.0. The application features:
- **🤖 AI vs AI Gameplay**: Grok AI-powered chess agents making strategic moves
- **📡 A2A Protocol Communication**: Real-time agent communication using JSON-RPC 2.0 over HTTP(S)
- **🎨 Cross-Platform UI**: Beautiful Avalonia-based chess visualization
- **📊 Real-Time Monitoring**: Live view of A2A messages and game state changes
- **🔄 Agent Discovery**: Automatic agent discovery via Agent Cards
- **⚡ Optimistic Updates**: Fast UI responses with rollback capability
- **🎮 Game Control**: Pause/resume/reset functionality via A2A protocol
## 🏗️ Architecture
### Agent-to-Agent Chess Communication
```
┌─────────────────┐ A2A Protocol ┌─────────────────┐
│ Chess Agent │◄────────JSON-RPC 2.0────────►│ Chess Agent │
│ (White) │ over HTTP(S) │ (Black) │
│ │ │ │
│ ┌─────────────┐ │ │ ┌─────────────┐ │
│ │ Grok AI │ │ │ │ Grok AI │ │
│ │ Integration │ │ │ │ Integration │ │
│ └─────────────┘ │ │ └─────────────┘ │
│ ┌─────────────┐ │ │ ┌─────────────┐ │
│ │ Avalonia UI │ │ │ │ Avalonia UI │ │
│ │ (Observer) │ │ │ │ (Observer) │ │
│ └─────────────┘ │ │ └─────────────┘ │
└─────────────────┘ └─────────────────┘
```
### External Agent Integration (e.g., Claude)
```
┌─────────────────────────────┐ A2A Protocol ┌─────────────────┐
│ External Agent │◄────────JSON-RPC 2.0────────►│ Chess Agent │
│ (Claude) │ over HTTP(S) │ (SERVER) │
│ │ │ │
│ ┌─────────────────────────┐ │ │ ┌─────────────┐ │
│ │ Claude AI Engine │ │ │ │ Grok AI │ │
│ │ (Move Generation) │ │ │ │ Integration │ │
│ └─────────────────────────┘ │ │ └─────────────┘ │
│ ┌─────────────────────────┐ │ Discovery: │ ┌─────────────┐ │
│ │ A2A Client Library │ │ /.well-known/agent.json │ │ A2A Server │ │
│ │ (HTTP Requests) │ │◄─────────────────────────────┤ │ (Port 8081) │ │
│ └─────────────────────────┘ │ │ └─────────────┘ │
│ │ Game Communication: │ ┌─────────────┐ │
│ Actions: │ • game-invitation │ │ Avalonia UI │ │
│ • Discover agent │ • make-move │ │ (Observer) │ │
│ • Send game invitation │ • poll-game-update │ └─────────────┘ │
│ • Make chess moves │ • game-pause/resume │ │
│ • Poll for updates │ • move confirmations │ │
└─────────────────────────────┘ └─────────────────┘
```
**Flow for External Agent Integration:**
1. **Discovery**: Claude discovers Chess Agent via `GET /.well-known/agent.json`
2. **Invitation**: Claude sends `game-invitation` with preferred color
3. **Acceptance**: Chess Agent responds with `game-accepted` and role assignment
4. **Gameplay**:
- Claude (CLIENT) continuously polls Chess Agent (SERVER) for updates
- Chess Agent queues moves and game state changes for Claude's polls
- Both agents exchange moves using `make-move` action
5. **Game Control**: Chess Agent can pause/resume game, Claude detects via polling
## 🛠️ Technology Stack
- **Framework**: .NET 9
- **UI**: Avalonia (Cross-platform XAML)
- **Chess Logic**: Gera.Chess library
- **A2A Protocol**: JSON-RPC 2.0 over HTTP(S)
- **AI Integration**: Grok API
- **Communication**: ASP.NET Core HTTP servers with Agent Cards discovery
## 🚀 Quick Start
### Prerequisites
- [.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)
- [Git](https://git-scm.com/)
- Grok API Key (for AI integration)
### Development Setup
#### Configure Grok API Key
You need a Grok API key for AI move suggestions.
Option 1 – Environment variable (macOS/Linux):
```bash
export GROK_API_KEY="your_real_key"
echo 'export GROK_API_KEY="your_real_key"' >> ~/.zshrc
# Reload current shell
source ~/.zshrc
```
Option 2 – .NET User Secrets (if configuration binding is added):
```bash
dotnet user-secrets init
dotnet user-secrets set "Grok:ApiKey" "your_real_key"
```
#### Clone, install and run
```bash
# Clone the repository
git clone [repository-url]
cd dotnet-ai-chess
# Install dependencies (once project is created)
dotnet restore
# Run the application
dotnet run
```
### Running Two Chess Agents
#### Option 1: Server + Client Setup
```bash
# Terminal 1 - Black Server Agent (Karpov)
dotnet run --project src/UI/DotNetAiChess.UI.csproj -- --players-mode multi --game-mode ai-plays --color black --port 8081 --agent-name "Karpov"
# Terminal 2 - White Client Agent (Kasparov)
dotnet run --project src/UI/DotNetAiChess.UI.csproj -- --players-mode multi --game-mode ai-plays --color white --agent-name "Kasparov" --opponent-url "http://localhost:8081"
```
#### Option 2: Alternative Client + Server Setup
```bash
# Terminal 1 - White Server Agent
dotnet run --project src/UI/DotNetAiChess.UI.csproj -- --players-mode multi --game-mode ai-plays --color white --port 8080 --agent-name "Kasparov"
# Terminal 2 - Black Client Agent
dotnet run --project src/UI/DotNetAiChess.UI.csproj -- --players-mode multi --game-mode ai-plays --color black --agent-name "Karpov" --opponent-url "http://localhost:8080"
```
#### Option 3: Server Setup to play external agent
```bash
# Terminal 1 - White Server Agent (color can be negotiated during game invitation phase)
dotnet run --project src/UI/DotNetAiChess.UI.csproj -- --players-mode multi --game-mode ai-plays --color white --port 8080 --agent-name "Kasparov"
```
#### Key Parameters:
- `--players-mode multi`: Enables multiplayer A2A protocol mode
- `--game-mode ai-plays`: Activates AI-powered gameplay
- `--color`: Sets piece color (white/black)
- `--port`: Server port for A2A communication
- `--agent-name`: Friendly name for the chess agent
- `--opponent-url`: Client-only parameter for server discovery
## 🎬 Previews
### Single Player – AI Plays Mode (Grok Integration)
Real-time AI-assisted move generation, board updates, and UI responsiveness.
*Showcases: Grok-3 AI move generation, validation pipeline, activity logging, Avalonia rendering.*
### Multi Player – AI vs AI (A2A Protocol)
Two autonomous agents (CLIENT/SERVER) exchanging moves over the A2A Protocol v0.2.9.
*Showcases: Agent discovery, game invitation handshake, JSON-RPC polling loop, synchronized state updates.*
### Multi Player – AI vs Claude (External Agent Integration)
Demonstrates interoperability with an external (Claude) agent using discovery + invitation + move exchange over HTTP via JSON-RPC.
*Showcases: External agent discovery (`/.well-known/agent.json`), invitation negotiation (color/roles), cross-agent move cadence, and protocol transparency.*
## 📚 Documentation
- **[Implementation Plan](IMPLEMENTATION_PLAN.md)** - Complete development roadmap
- **[A2A Protocol Research](docs/A2A_PROTOCOL_RESEARCH.md)** - Protocol specification and examples
- **[Chess Library Research](docs/CHESS_LIBRARY_RESEARCH.md)** - Library evaluation and selection
- **[AI Integration Research](docs/AI_INTEGRATION_RESEARCH.md)** - Grok API integration details
## 🎮 Features
### Core Functionality
- **Automated Chess Gameplay**: AI agents play complete chess games using Grok
- **A2A Protocol Communication**: Standards-compliant agent messaging
- **Real-time Visualization**: Live chess board with move animations
- **Agent Discovery**: Automatic discovery via Agent Cards at `/.well-known/agent.json`
- **Optimistic Updates**: Fast UI responses with rollback capability
- **Game Control**: Pause, resume, and reset games via A2A protocol
- **Polling-Based Sync**: CLIENT instances poll SERVER for game updates
### Advanced Features
- **Move Validation**: Complete chess rule enforcement
- **Game State Monitoring**: FEN notation and move history tracking
- **Communication Logging**: Real-time A2A message inspection
- **Cross-Platform Support**: Windows, macOS, Linux compatibility
- **CLIENT/SERVER Roles**: Flexible agent role assignment based on configuration
- **Error Recovery**: Move timeout and rollback mechanisms
## 🤝 A2A Protocol Implementation
This project showcases the **Agent2Agent Protocol v0.2.9** with:
- **JSON-RPC 2.0** messaging over HTTP(S)
- **Agent Cards** for service discovery
- **Fast acknowledgment** patterns for responsive communication
- **Optimistic updates** with rollback for robust UX
- **Context management** for multi-turn conversations
- **Polling-based synchronization** for real-time game state
- **CLIENT/SERVER architecture** with flexible role assignment
### Example A2A Chess Move
```json
{
"jsonrpc": "2.0",
"id": "move-001",
"method": "message/send",
"params": {
"contextId": "game-context-001",
"message": {
"role": "user",
"parts": [
{
"type": "data",
"data": {
"action": "make-move",
"move": "e2-e4",
"san": "e4",
"fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
"gameId": "chess-001",
"moveNumber": 1,
"playerColor": "white"
}
}
]
}
}
}
```
## 📖 Learning Objectives
This project serves as a comprehensive example of:
1. **A2A Protocol Implementation** - Standards-compliant agent communication
2. **Distributed System Design** - Multi-agent coordination and messaging
3. **Real-time UI Development** - Responsive visualization with Avalonia
4. **AI Integration Patterns** - External AI service integration
5. **Cross-Platform Development** - .NET 9 and Avalonia best practices
## 🎯 Goals
- **Primary**: Demonstrate A2A Protocol capabilities through engaging chess gameplay
- **Secondary**: Create a robust foundation for multi-agent applications
- **Educational**: Provide clear examples of distributed agent communication
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **A2A Protocol Specification** - [A2A Project Documentation](https://a2aproject.github.io/A2A/)
- **Gera.Chess Library** - [Chess Logic Implementation](https://github.com/GarageInc/Gera.Chess)
- **Avalonia UI** - [Cross-Platform UI Framework](https://avaloniaui.net/)
- **Grok AI** - [AI-Powered Chess Strategy](https://grok.x.ai/)
