Content
# Game Balance A2A System
A system where three AI agents communicate via the A2A protocol to analyze game balance.
## Architecture
```
┌─────────────────────────────────────────────────────┐
│ Game Balance Agent (9000) │
│ Coordinator + A2A Server │
└─────────────────────────────────────────────────────┘
↓ A2A Protocol ↓ A2A Protocol
┌──────────────────────┐ ┌──────────────────────┐
│ CS Feedback Agent │ │ Data Analysis Agent │
│ (9001) │ │ (9002) │
│ A2A Server │ │ A2A Server │
└──────────────────────┘ └──────────────────────┘
```
## Agent Configuration
### 1. Game Balance Agent (Port 9000)
- **Role**: Coordinator - Coordinates other agents
- **GUI**: http://localhost:8501
- **Function**: Comprehensive balance analysis and patch suggestions
### 2. CS Feedback Agent (Port 9001)
- **Role**: Provides CS feedback data
- **GUI**: http://localhost:8502
- **Function**: Customer complaint retrieval and analysis
### 3. Data Analysis Agent (Port 9002)
- **Role**: Analyzes game data
- **GUI**: http://localhost:8503
- **Function**: Win rate calculation, balance issue detection
## Installation and Execution
### 1. Install Dependencies
```bash
pip install -r requirements.txt
```
### 2. Set AWS Credentials
```bash
# AWS CLI configuration or environment variable
export AWS_REGION=us-east-1
```
### 3. Start the Entire System
#### Run Agents
```bash
# Terminate all agents
pkill -f "game_balance_agent|data_analysis_agent|cs_feedback_agent"
# Start agents (order matters)
cd "/Users/hyeonsup/aws goa 2025/msk-a2a-demo/game-balance-a2a"
venv/bin/python agents/cs_feedback_agent.py > /tmp/cs_agent.log 2>&1 &
venv/bin/python agents/data_analysis_agent.py > /tmp/data_agent.log 2>&1 &
sleep 3
venv/bin/python agents/game_balance_agent.py > /tmp/balance_agent.log 2>&1 &
# Check ports
lsof -i :8000,9001,9002 | grep LISTEN
```
#### Run GUI
```bash
# Start all GUIs
./run_gui.sh
# Start individual GUIs
venv/bin/streamlit run gui/balance_gui.py --server.port 8501
venv/bin/streamlit run gui/cs_gui.py --server.port 8502
venv/bin/streamlit run gui/analysis_gui.py --server.port 8503
```
**Access GUI:**
- **Balance Agent GUI**: http://localhost:8501 (A2A Hub - calls other agents)
- **CS Feedback Agent GUI**: http://localhost:8502 (Feedback retrieval)
- **Data Analysis Agent GUI**: http://localhost:8503 (Statistical analysis)
**Terminate GUI:**
```bash
pkill -f streamlit
```
### 4. Testing
#### CLI Testing
```bash
# Balance analysis (including A2A calls)
./trace.sh "Analyze game balance"
# Specific race feedback
./trace.sh "Show only Terran feedback"
# Win rate inquiry
curl -X POST http://localhost:9001/ask \
-H "Content-Type: application/json" \
-d '{"query": "What is the win rate for Terran?"}'
```
#### GUI Testing
1. Input "Analyze game balance" in the Balance Agent GUI (http://localhost:8501)
2. The Data Agent and CS Agent will be automatically called via A2A
3. Direct questions can also be asked in each agent's GUI
## System Structure
### Agent Ports
- **Game Balance Agent**: 8000 (A2A Hub)
- **Data Analysis Agent**: 9001
- **CS Feedback Agent**: 9002
### GUI Ports
- **Balance GUI**: 8501
- **CS GUI**: 8502
- **Analysis GUI**: 8503
### A2A Communication Flow
```
User → Balance Agent (8000)
├─→ Data Analysis Agent (9001) [A2A call]
└─→ CS Feedback Agent (9002) [A2A call]
User → Data Analysis Agent (9001) [Direct call]
User → CS Feedback Agent (9002) [Direct call]
```
```bash
# Start all agents
python run_system.py
```
### 4. Start Individual Agents (Optional)
```bash
# CS Feedback Agent
python agents/cs_feedback_agent.py
# Data Analysis Agent
python agents/data_analysis_agent.py
# Game Balance Agent
python agents/game_balance_agent.py
```
### 5. Start Streamlit GUI
```bash
# Run in separate terminals
# Game Balance GUI (Port 8501)
streamlit run gui/balance_gui.py
# CS Feedback GUI (Port 8502)
streamlit run gui/cs_gui.py --server.port 8502
# Data Analysis GUI (Port 8503)
streamlit run gui/analysis_gui.py --server.port 8503
```
## Usage Examples
### Game Balance Agent
```
Question: "Please analyze the current game balance."
Response:
1. Retrieve win rate data from Data Analysis Agent
- Terran: 60% win rate
- Zerg: 20% win rate
- Protoss: 20% win rate
2. Retrieve feedback from CS Feedback Agent
- Terran nerf requests: 4 (high urgency)
- Zerg buff requests: 3 (high urgency)
3. Comprehensive analysis and recommendations:
- Nerf Terran attack power by -5%
- Buff Zerg health by +10%
```
### CS Feedback Agent
```
Question: "Show feedback for Terran."
Response:
- Marine rush is too strong (high urgency, 245 upvotes)
- Tank range is too long (medium urgency, 189 upvotes)
- Bunker construction speed is too fast (high urgency, 201 upvotes)
```
### Data Analysis Agent
```
Question: "Show win rate statistics."
Response:
- Terran: 60% (18 wins)
- Zerg: 20% (6 wins)
- Protoss: 20% (6 wins)
- Balance issue detected: Terran is 40% higher (high severity)
```
## A2A Protocol Testing
### Visualizing Agent Conversation Flow with trace.sh
```bash
# Basic usage
./trace.sh "What is the win rate for Terran?"
# Example output:
# 🎯 Query: What is the win rate for Terran?
# 📊 Total Cycles: 3
# 🆕 New Request: Cycle 2 ~ 3
#
# 📍 Cycle 2 🆕
# 🧠 [Thinking] ...
# 📞 → Data Analysis Agent: Retrieve win rate statistics for Terran race.
# ✅ ← Data Analysis Agent: Terran has a win rate of 100.00%...
```
### Direct Testing with curl
```bash
# Game Balance Agent
curl -X POST http://localhost:9000/send_message \
-H "Content-Type: application/json" \
-d '{
"message": {
"role": "user",
"parts": [{"type": "text", "text": "Analyze game balance"}],
"messageId": "test-1"
}
}'
# AgentCard retrieval
curl http://localhost:9000/.well-known/agent.json
```
## Project Structure
```
game-balance-a2a/
├── agents/
│ ├── game_balance_agent.py # Coordinator (9000)
│ ├── cs_feedback_agent.py # CS Feedback (9001)
│ └── data_analysis_agent.py # Data Analysis (9002)
├── data/
│ ├── feedback_data.json # Sample feedback (10 entries)
│ └── game_logs.json # Sample game logs (30 entries)
├── gui/
│ ├── balance_gui.py # Balance GUI (8501)
│ ├── cs_gui.py # CS GUI (8502)
│ └── analysis_gui.py # Analysis GUI (8503)
├── run_system.py # Run the entire system
├── requirements.txt
└── README.md
```
## Implementation Features
### Explicit Task Management
- Task creation and state management with AgentExecutor
- TaskStatusUpdateEvent (working → completed/failed)
- TaskArtifactUpdateEvent (result transmission)
### Explicit AgentCard
- Definition of AgentSkill
- AgentCapabilities (streaming, pushNotifications)
- Includes example queries
### A2A Protocol
- Standard Message/Task structure
- HTTP-based communication
- Loose coupling between agents
## Agent Management
### Restarting Agents (Reset History)
Agents store conversation history in memory, which can lead to "too large" errors if they run for an extended period.
```bash
# 1. Terminate all agents
pkill -f "game_balance_agent|data_analysis_agent|cs_feedback_agent"
# 2. Restart (use absolute path)
cd "/Users/hyeonsup/aws goa 2025/msk-a2a-demo/game-balance-a2a"
venv/bin/python agents/cs_feedback_agent.py > /tmp/cs_agent.log 2>&1 &
venv/bin/python agents/data_analysis_agent.py > /tmp/data_agent.log 2>&1 &
sleep 3
venv/bin/python agents/game_balance_agent.py > /tmp/balance_agent.log 2>&1 &
# 3. Check (wait 10 seconds)
sleep 10
lsof -i :8000,9000,9001,9002 | grep LISTEN
```
### Check Agent Status
```bash
# Check ports
lsof -i :8000,9000,9001,9002 | grep LISTEN
# Check logs
tail -f /tmp/balance_agent.log
tail -f /tmp/cs_agent.log
tail -f /tmp/data_agent.log
# Check the last 50 lines
tail -50 /tmp/balance_agent.log
tail -50 /tmp/cs_agent.log
tail -50 /tmp/data_agent.log
# Check for errors only
grep -i error /tmp/balance_agent.log
grep -i error /tmp/cs_agent.log
grep -i error /tmp/data_agent.log
```
### Log File Locations
- Game Balance Agent: `/tmp/balance_agent.log`
- CS Feedback Agent: `/tmp/cs_agent.log`
- Data Analysis Agent: `/tmp/data_agent.log`
## Troubleshooting
### "The tool result was too large!" Error
- **Cause**: The agent accumulates conversation history, exceeding message size limits.
- **Solution**: Follow the "Restarting Agents" procedure above.
### Agent Not Starting
```bash
# Check ports
lsof -i :9000
lsof -i :9001
lsof -i :9002
# Force terminate processes
kill -9 <PID>
```
### No Response from Agent
```bash
# Check for errors in logs
tail -30 /tmp/balance_agent.log
# Common errors:
# - "Response ended prematurely": Temporary network error with Bedrock (retry)
# - "TimeoutError": Agent response timeout (restart)
# - "Connection refused": Agent not running (needs to be started)
```
### AWS Credentials Error
```bash
# Check AWS CLI configuration
aws configure list
# Check environment variables
echo $AWS_REGION
```
### Streamlit Connection Error
- Agents must be running first
- Check for port conflicts
- Verify firewall settings
## License
MIT License
