Repository navigation
llm bot system design
Version: 2.0 Date: 2026-01-13 Status: Design Proposal
This document presents a comprehensive design for integrating Large Language Model (LLM) powered bots into the MakaMek BattleTech game system. The solution leverages Microsoft Agent Framework for intelligent decision-making and Model Context Protocol (MCP) for seamless game integration, while maintaining compatibility with the existing bot infrastructure.
- Advanced Tactical Reasoning: LLM agents can analyze complex tactical situations with human-like strategic thinking
- Adaptive Gameplay: Agents learn and adapt strategies based on game context
- Explainable Decisions: LLM agents can provide reasoning for their tactical choices
- Scalable Architecture: Support for multiple concurrent LLM bot players
- Graceful Degradation: Fallback to rule-based engines ensures reliability
- Extensible Design: Easy to add new capabilities and improve agent performance
- Containerized Deployment: Docker-based deployment for easy orchestration and scaling
The system consists of two containerized applications:
- LLM Agent Container - ASP.NET Core Web API application using Microsoft Agent Framework with 4 specialized agents: Deployment, Movement, Weapon Attack, and End-Phase
- Integration Bot Container - ASP.NET Core application hosting both the MCP Server and Integration Bot logic, connecting to MakaMek ServerGame
- Current Architecture Analysis
- LLM Bot System Design
- Component Specifications
- MCP API Specification
- Agent Design
- Integration Patterns
- Deployment Architecture
- Implementation Roadmap
- Technical Specifications
- Operational Considerations
- Appendices
MakaMek uses a distributed architecture with clear separation between authoritative server and client game instances:
-
Location:
src/MakaMek.Core/Models/Game/ServerGame.cs -
Responsibilities:
- Maintains authoritative game state
- Validates and processes client commands
- Manages phase transitions via
IPhaseManager - Broadcasts state changes to all clients
- Handles dice rolling and random events
- Enforces game rules
-
Location:
src/MakaMek.Core/Models/Game/ClientGame.cs -
Responsibilities:
- Maintains local replica of game state
- Sends player commands to server
- Receives and applies server updates
- Provides reactive observables for state changes
- Manages command acknowledgment and idempotency
- Supports multiple local players (including bots)
Client → IClientCommand → CommandPublisher → Transport → Server
Server → Validation → Processing → IGameCommand → Broadcast → All Clients
Key Insight: One ClientGame instance serves one or more local players (human and bot).
-
Bot Class:
src/MakaMek.Bots/Models/Bot.cs- Observes ClientGame via reactive subscriptions
- Monitors
PhaseChanges,PhaseStepChanges, andCommandsobservables - Triggers decision-making when bot becomes active player
- Delegates decisions to phase-specific engines
-
Interface:
IBotDecisionEngine-src/MakaMek.Bots/Models/DecisionEngines/IBotDecisionEngine.cs -
Implementations:
-
DeploymentEngine- Selects deployment hexes and facing -
MovementEngine- Evaluates movement paths using tactical scoring -
WeaponsEngine- Selects targets and weapon configurations -
EndPhaseEngine- Manages heat, shutdown, and startup decisions
-
-
Location:
src/MakaMek.Bots/Models/DecisionEngines/TacticalEvaluator.cs -
Capabilities:
- Evaluates movement paths with offensive/defensive scoring
- Calculates hit probabilities using
ToHitCalculator - Scores weapon configurations and target priorities
- Considers terrain, line of sight, and range
- Caches evaluations for performance (internal to TacticalEvaluator)
MakaMek implements the following game phases (from PhaseNames.cs):
- Start - Lobby and player joining
- Deployment - Unit placement on map (requires LLM decision)
- Initiative - Turn order determination
- Movement - Unit movement and positioning (requires LLM decision)
- WeaponsAttack - Weapon target declaration (requires LLM decision)
- WeaponAttackResolution - Attack resolution and damage
- PhysicalAttack - Melee combat (not yet implemented)
- Heat - Heat management and effects
- End - Turn cleanup and phase cycling (requires LLM decision)
Phase transitions are managed by BattleTechPhaseManager which implements the standard BattleTech turn sequence.
Note: Only 4 phases (Deployment, Movement, WeaponsAttack, End) require bot decision-making at this time.
-
IClientCommand - Commands from clients to server
- Include
IdempotencyKeyfor duplicate detection (handled internally by ClientGame) - Examples:
DeployUnitCommand,MoveUnitCommand,WeaponAttackDeclarationCommand
- Include
-
IGameCommand - Server broadcast commands
- Examples:
ChangePhaseCommand,TurnIncrementedCommand,SetBattleMapCommand
- Examples:
- CommandPublisher - Pub/sub pattern for command distribution
- CommandTransportAdapter - Serialization and transport abstraction
- ITransportPublisher - Network transport interface (supports local and network)
The LLM bot system introduces two containerized applications that integrate with the existing MakaMek architecture:
┌─────────────────────────────────────────────────────────────┐
│ MakaMek ServerGame │
│ (Authoritative State) │
└───────────────────────┬─────────────────────────────────────┘
│ Commands & State Updates
│ (via Transport)
┌───────────────┼───────────────┬─────────────────┐
│ │ │ │
┌───────▼────────┐ ┌────▼───────┐ ┌─────▼──────┐ ┌──────▼─────┐
│ Integration │ │Integration │ │Integration │ │Integration │
│ Bot Container 1│ │Bot Cont. 2 │ │Bot Cont. 3 │...│Bot Cont. N │
│ │ │ │ │ │ │ │
│ ┌────────────┐ │ │ │ │ │ │ │
│ │ClientGame │ │ │Each container hosts: │ │ │
│ │ (Player 1) │ │ │- ClientGame instance │ │ │
│ └─────┬──────┘ │ │- MCP Server │ │ │
│ │ │ │- Integration Bot Logic │ │ │
│ ┌─────▼──────┐ │ │ │ │ │
│ │Integration │ │ │ │ │ │ │ │
│ │Bot Logic │ │ │ │ │ │ │ │
│ └─────┬──────┘ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ ┌─────▼──────┐ │ │ │ │ │ │ │
│ │MCP Server │ │ │ │ │ │ │ │
│ │HTTP/SSE │ │ │ │ │ │ │ │
│ └─────┬──────┘ │ │ │ │ │ │ │
└───────┼────────┘ └───┬────────┘ └───┬────────┘ └───┬────────┘
│ │ │ │
│ HTTP Requests│ │ │
└──────────────┴─┬────────────┴────────────────┘
│
│
┌──────────▼───────────┐
│ LLM Agent Container │
│ (Shared Instance) │
│ │
│ ┌──────────────────┐ │
│ │ ASP.NET Core │ │
│ │ Web API │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌────────▼─────────┐ │
│ │ Orchestrator │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ ▼ ▼ ▼ │
│ ┌───┐ ┌───┐ ┌───┐ │
│ │Dep│ │Mov│ │Wpn│ │
│ │Agt│ │Agt│ │Agt│ │
│ └─┬─┘ └─┬─┘ └─┬─┘ │
│ └─────┼─────┘ │
│ │ │
│ MCP Client │
└──────────┼───────────┘
│
│ HTTP/SSE
│ (calls back to
│ bot's MCP Server)
▼
┌──────────────────────┐
│ LLM Provider │
│ (OpenAI/Anthropic) │
└──────────────────────┘
Key Architectural Points:
- Multiple Bot Instances: Each LLM bot runs in its own Integration Bot container with its own ClientGame instance
- Shared Agent Service: All bots make stateless HTTP requests to a single shared LLM Agent container
- Embedded MCP Server: Each Integration Bot container hosts its own MCP Server endpoint
- Stateless Communication: Agent requests are stateless; no context preserved between turns or phases
Type: ASP.NET Core Web API (.NET 10) Technology: Microsoft Agent Framework + LLM SDKs Port: 5000 (configurable)
Responsibilities:
- Host 4 specialized agents: Deployment, Movement, Weapon Attack, and End-Phase
- Expose REST API for decision requests
- Orchestrate agent selection based on game phase
- Communicate with LLM providers (OpenAI, Anthropic, Azure OpenAI, etc.)
- Use MCP client to query bot's MCP Server for game state
- Generate tactical decisions with reasoning
- Return structured decision responses
Key Features:
- Multi-agent architecture with phase-specific specialization
- Chain-of-thought reasoning for complex decisions
- Structured output generation for reliable parsing
- Configurable LLM provider and model selection
- Health check endpoint for monitoring
- Stateless request handling (no session state)
API Endpoints:
-
POST /api/decision- Request tactical decision -
GET /api/health- Health check
Type: ASP.NET Core Application (.NET 10) Technology: MCP SDK + MakaMek.Core + Reactive Extensions Port: 5001 (configurable, one per bot instance)
Responsibilities:
- Host MCP Server (HTTP/SSE endpoint)
- Host Integration Bot background service
- Maintain ClientGame instance connection to ServerGame
- Observe game state changes via ClientGame observables
- Trigger LLM agent requests based on phase and context
- Translate LLM responses to game commands
- Execute commands via ClientGame
- Provide fallback to rule-based decision engines
- Expose game state and tactical analysis via MCP tools
Key Features:
- Embedded MCP Server for game state queries
- Comprehensive tool catalog for tactical analysis
- Seamless integration with existing bot infrastructure
- Mandatory fallback to rule-based engines on error
- Real-time game state synchronization
- Structured error responses
Endpoints:
- MCP Server:
/mcp(HTTP/SSE) - Health check:
/health
sequenceDiagram
participant SG as ServerGame
participant CG as ClientGame
participant IB as Integration Bot
participant MCP as MCP Server
participant Agent as LLM Agent API
participant LLM as LLM Provider
SG->>CG: Phase Change / Active Player
CG->>IB: Observable Event
IB->>Agent: POST /api/decision
Note over IB,Agent: Includes: playerId,<br/>phase, mcpServerUrl
Agent->>MCP: HTTP: get_game_state()
MCP->>CG: Query State
CG-->>MCP: Game State
MCP-->>Agent: State Data
Agent->>MCP: HTTP: evaluate_movement_options()
MCP->>CG: Calculate Paths
CG-->>MCP: Scored Paths
MCP-->>Agent: Tactical Analysis
Agent->>LLM: Generate Decision
Note over Agent,LLM: Chain-of-Thought<br/>Reasoning
LLM-->>Agent: Decision + Reasoning
Agent-->>IB: IClientCommand
alt Success Response
IB->>IB: Validate received Command
IB->>CG: Execute Command
CG->>SG: Send Command
else Error Response
IB->>IB: Activate Fallback
Note over IB: Use rule-based engine
IB->>CG: Execute Fallback Command
CG->>SG: Send Command
end
SG->>CG: Broadcast Update
CG->>IB: State Updated
Flow Steps:
-
Game State Change
- ServerGame broadcasts phase change or active player change
- ClientGame receives update and publishes to observables
-
Trigger Detection
- Integration Bot detects relevant change via subscription
- Determines if LLM decision is needed based on phase and player
-
Decision Request
- Integration Bot sends HTTP POST to Agent API
- Request includes: playerId, phase, mcpServerUrl (for callback)
- Request is stateless - no preserved context
-
Agent Processing
- Agent Orchestrator selects appropriate specialized agent
- Agent makes MCP tool calls to bot's MCP Server as needed
- Agent generates decision with reasoning using LLM
- Agent returns corresponding IClientCommand
-
Response Handling
- Integration Bot validates decision against game rules
- If valid: executes IClientCommand directly
- If error: activates mandatory fallback engine
-
Command Execution
- Integration Bot sends command via ClientGame
- ServerGame validates, processes, and broadcasts
- All clients receive updated game state
- Framework: .NET 10
- Web Framework: ASP.NET Core Web API
- Agent Framework: Microsoft Agent Framework
-
LLM SDKs:
- OpenAI .NET SDK
- Anthropic .NET SDK
- Azure.AI.OpenAI
- MCP Client: ModelContextProtocol.SDK
- Configuration: Microsoft.Extensions.Configuration
- Logging: Microsoft.Extensions.Logging
- Dependency Injection: Microsoft.Extensions.DependencyInjection
- Framework: .NET 10
- Web Framework: ASP.NET Core (for MCP Server hosting)
- Dependencies: MakaMek.Core, MakaMek.Bots
- MCP SDK: ModelContextProtocol.SDK (C# implementation)
- Reactive: System.Reactive
- HTTP Client: System.Net.Http (for Agent API calls)
- Serialization: System.Text.Json
- Caching: Microsoft.Extensions.Caching.Memory
- Background Services: Microsoft.Extensions.Hosting
MakaMek.LlmAgent/
├── Program.cs # Application entry point
├── Controllers/
│ └── DecisionController.cs # REST API endpoints
├── Configuration/
│ ├── AgentConfiguration.cs # Agent settings
│ └── LlmProviderConfiguration.cs # LLM provider settings
├── Orchestration/
│ └── AgentOrchestrator.cs # Agent selection and coordination
├── Agents/
│ ├── BaseAgent.cs # Base class for all agents
│ ├── DeploymentAgent.cs # Deployment phase decisions
│ ├── MovementAgent.cs # Movement phase decisions
│ ├── WeaponsAttackAgent.cs # Weapons attack phase decisions
│ └── EndPhaseAgent.cs # End phase decisions (Heat)
├── Prompts/
│ ├── SystemPrompts.cs # System prompts for each agent
│ ├── DeploymentPrompts.cs # Deployment-specific prompts
│ ├── MovementPrompts.cs # Movement-specific prompts
│ ├── WeaponsAttackPrompts.cs # Weapons attack prompts
│ └── EndPhasePrompts.cs # End phase prompts
├── Services/
│ ├── ILlmProvider.cs # LLM provider abstraction
│ ├── OpenAIProvider.cs # OpenAI implementation
│ ├── AnthropicProvider.cs # Anthropic implementation
│ └── McpClientService.cs # MCP client for tool calls
└── Models/
├── DecisionRequest.cs # Request from Integration Bot
├── DecisionResponse.cs # Response to Integration Bot
└── GameContext.cs # Game state context
Decision Request:
{
"playerId": "guid",
"phase": "Movement",
"mcpServerUrl": "http://bot-container:5001/mcp",
"timeout": 30000
}Agent Response (Success - MoveUnitCommand):
{
"success": true,
"commandType": "<type>",
"command": {
...
},
"reasoning": "Walking to hex (12,6) provides optimal firing position while maintaining cover..."
}Agent Response (Error):
{
"success": false,
"errorType": "AGENT_CANNOT_DECIDE" | "LLM_TIMEOUT" | "INVALID_GAME_STATE",
"errorMessage": "Detailed error description",
"fallbackRequired": true
}Supported IClientCommand Types:
-
DeployUnitCommand- Unit deployment with position and facing -
MoveUnitCommand- Unit movement with path and movement type -
WeaponAttackDeclarationCommand- Weapon target declaration -
WeaponConfigurationCommand- to rotate torso -
Startup/ShutdownUnitCcommand- to manage unit state during end phase -
EndPhaseCommand- End phase actions (shutdown, startup, none)
Purpose: Select optimal deployment position and facing for units
System Prompt Template:
You are a BattleTech tactical AI specializing in unit deployment. Your goal is to
select deployment positions that maximize tactical advantage while considering:
- Distance to enemy units
- Terrain cover and elevation
- Line of sight to objectives
- Support from friendly units
- Escape routes and maneuverability
Analyze the available deployment zones and select the best position and facing.
Available MCP Tools:
-
get_deployment_zones- Get valid deployment hexes -
get_map_info- Analyze terrain -
get_game_state- See enemy positions
Decision Output Fields:
-
action: "deploy" -
unitId: string (GUID) -
hexCoordinates: {q, r} -
facing: string (Top/TopRight/BottomRight/Bottom/BottomLeft/TopLeft) -
reasoning: string
Purpose: Evaluate movement options and select optimal path
System Prompt Template:
You are a BattleTech tactical AI specializing in mech movement. Your goal is to
position units for maximum tactical advantage while minimizing risk. Consider:
- Offensive positioning (weapon range, line of sight to enemies)
- Defensive positioning (cover, minimizing rear arc exposure)
- Heat management (walking vs running vs jumping)
- Terrain effects (elevation, woods, water)
- Piloting skill roll requirements
Use the tactical evaluation tools to score movement options and select the best path.
Available MCP Tools:
-
evaluate_movement_options- Get scored movement paths -
get_game_state- Current tactical situation -
get_unit_details- Unit capabilities
Decision Output Fields:
-
action: "move" -
unitId: string (GUID) -
movementPath: array of {q, r} -
movementType: "Walk" | "Run" | "Jump" -
reasoning: string
Purpose: Select targets and weapon configurations for maximum damage
System Prompt Template:
You are a BattleTech tactical AI specializing in weapons targeting. Your goal is to
maximize damage output while managing heat and ammunition. Consider:
- Target priority (damaged units, high-value targets)
- Hit probability vs potential damage
- Heat generation and shutdown risk
- Ammunition conservation
- Weapon configurations (torso twist, aimed shots)
Analyze available targets and select the optimal weapon configuration.
Available MCP Tools:
-
evaluate_weapon_targets- Get scored target options -
calculate_hit_probability- Estimate hit chance -
get_unit_details- Analyze target damage state
Decision Output Fields:
-
action: "attack" -
attackerUnitId: string (GUID) -
targetUnitId: string (GUID) -
weaponIds: array of string (GUIDs) -
configuration: object (optional, e.g., {type: "TorsoRotation", value: 1}) -
reasoning: string
Purpose: Manage shutdown and startup decisions, end turn
System Prompt Template:
You are a BattleTech tactical AI specializing in end phase decisions. Your goal is to
keep units operational while avoiding catastrophic heat effects. Consider:
- Current heat level and dissipation rate
- Ammo explosion risk at high heat
- Shutdown vs continued operation trade-offs
- Restart probability for shutdown units
- Next turn tactical requirements
Make decisions about shutting down overheated units or restarting shutdown units.
Available MCP Tools:
-
get_unit_details- Heat and shutdown status -
get_game_state- Tactical situation
Decision Output Fields:
-
action: "shutdown" | "startup" | "none" -
unitId: string (GUID) -
reasoning: string
{
"LlmProvider": {
"Type": "OpenAI",
"Model": "gpt-4o",
"Temperature": 0.7,
"MaxTokens": 2000,
"Timeout": 30000,
"ApiKey": "${OPENAI_API_KEY}"
},
"Agent": {
"EnableChainOfThought": true,
"MaxMcpToolCalls": 10
}
}Supported Providers:
- OpenAI: gpt-4o, gpt-4-turbo, gpt-4, gpt-3.5-turbo
- Anthropic: claude-3-5-sonnet-20241022, claude-3-opus-20240229
- Azure OpenAI: Any deployed model
MakaMek.Bots.Llm/
├── Program.cs # ASP.NET Core entry point
├── Controllers/
│ └── HealthController.cs # Health check endpoint
├── Services/
│ ├── IntegrationBotService.cs # Background service (IHostedService)
│ ├── LlmAgentClient.cs # HTTP client for Agent API
│ └── FallbackDecisionEngine.cs # Rule-based fallback (mandatory)
├── Mcp/
│ ├── McpServer.cs # MCP server implementation
│ ├── McpController.cs # MCP HTTP/SSE endpoint
│ ├── Tools/
│ │ ├── GameStateTools.cs # Game state query tools
│ │ ├── TacticalAnalysisTools.cs # Tactical evaluation tools
│ │ └── ToolRegistry.cs # Tool registration
│ ├── Resources/
│ │ ├── GameStateResource.cs # Current game state
│ │ ├── UnitResource.cs # Unit details
│ │ └── MapResource.cs # Map information
│ └── Models/
│ ├── ToolDefinition.cs # Tool metadata
│ ├── ToolRequest.cs # Tool invocation request
│ └── ToolResponse.cs # Tool invocation response
├── DecisionEngines/
│ ├── LlmDeploymentEngine.cs # Implements IBotDecisionEngine
│ ├── LlmMovementEngine.cs # Implements IBotDecisionEngine
│ ├── LlmWeaponsAttackEngine.cs # Implements IBotDecisionEngine
│ └── LlmEndPhaseEngine.cs # Implements IBotDecisionEngine
├── Models/
│ ├── LlmBot.cs # Extends Bot class
│ └── BotConfiguration.cs # Bot configuration
└── Configuration/
└── appsettings.json # Application settings
public class IntegrationBotService : BackgroundService
{
private readonly IClientGame _clientGame;
private readonly LlmAgentClient _agentClient;
private readonly FallbackDecisionEngine _fallbackEngine;
private readonly ILogger<IntegrationBotService> _logger;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
// Subscribe to game observables
_clientGame.PhaseChanges.Subscribe(OnPhaseChanged);
_clientGame.PhaseStepChanges.Subscribe(OnPhaseStepChanged);
// Keep service running
await Task.Delay(Timeout.Infinite, stoppingToken);
}
private async void OnPhaseStepChanged(PhaseStep phaseStep)
{
if (phaseStep?.ActivePlayer.Id == _botPlayerId)
{
await MakeDecision(phaseStep);
}
}
private async Task MakeDecision(PhaseStep phaseStep)
{
try
{
var response = await _agentClient.RequestDecision(
_botPlayerId,
phaseStep.Phase,
GetMcpServerUrl() //self host url basically, including port
);
if (response.Success)
{
await ExecuteDecision(response);
}
else
{
_logger.LogWarning("Agent error: {Error}", response.ErrorMessage);
await UseFallback(phaseStep);
}
}
catch (Exception ex)
{
_logger.LogError(ex, "Decision request failed");
await UseFallback(phaseStep);
}
}
}Tool Catalog:
- get_game_state - Returns current game state
- get_unit_details - Returns detailed unit information
- get_map_info - Returns battle map and terrain
- get_deployment_zones - Returns valid deployment hexes
- evaluate_movement_options - Returns scored movement paths
- evaluate_weapon_targets - Returns scored weapon targets
- calculate_hit_probability - Calculates weapon hit chance
- get_tactical_situation - Returns comprehensive tactical analysis
Tool Response Format:
{
"success": true,
"data": { /* tool-specific data */ },
"error": null
}Error Response Format:
{
"success": false,
"data": null,
"error": {
"code": "INVALID_UNIT_ID",
"message": "Unit with ID 'xyz' not found"
}
}Error Validation Strategy:
- Basic parameter validation (null checks, type checks)
- Game state validation (unit exists, valid hex coordinates)
- Clear error messages for debugging
- No complex JSON schema validation (kept simple for POC)
Every LlmEngine should accept fallback engine in its constructor
Fallback Activation Triggers:
- Agent returns error response
- HTTP request to Agent fails or times out
- Invalid decision response from Agent
- Any unhandled exception in LLM pipeline
Transport: HTTP/SSE (Server-Sent Events)
Endpoint: /mcp
Content-Type: application/json
Request Format:
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_game_state",
"arguments": {}
},
"id": 1
}Response Format:
{
"jsonrpc": "2.0",
"result": {
"content": [
{
"type": "text",
"text": "{\"gameId\": \"...\", \"turn\": 3, ...}"
}
]
},
"id": 1
}{
"name": "get_game_state",
"description": "Returns current game state including phase, turn, players, and units",
"inputSchema": {
"type": "object",
"properties": {},
"required": []
}
}Response:
{
"gameId": "guid",
"turn": 3,
"phase": "Movement",
"activePlayer": {
"id": "guid",
"name": "Bot Player 1",
"unitsToPlay": 2
},
"players": [...],
"units": [...]
}{
"name": "get_unit_details",
"description": "Returns detailed information about a specific unit",
"inputSchema": {
"type": "object",
"properties": {
"unitId": {"type": "string", "description": "GUID of the unit"}
},
"required": ["unitId"]
}
}Response:
{
"unitId": "guid",
"name": "Atlas AS7-D",
"position": {"q": 10, "r": 5, "facing": "North"},
"armor": {...},
"structure": {...},
"weapons": [...],
"heat": {"current": 12, "capacity": 30},
"movement": {"walking": 3, "running": 5, "jumping": 0},
"status": {"isProne": false, "isShutdown": false}
}{
"name": "evaluate_movement_options",
"description": "Evaluates all possible movement options for a unit and returns scored paths",
"inputSchema": {
"type": "object",
"properties": {
"unitId": {"type": "string", "description": "GUID of the unit"},
"maxPaths": {"type": "integer", "description": "Maximum paths to return", "default": 10}
},
"required": ["unitId"]
}
}Response:
{
"paths": [
{
"destination": {"q": 12, "r": 8, "facing": "North"},
"movementType": "Walk",
"offensiveScore": 45.2,
"defensiveScore": 12.3,
"enemiesInRearArc": 0,
"hexesTraveled": 3
}
]
}{
"name": "evaluate_weapon_targets",
"description": "Evaluates potential weapon targets and returns scored options",
"inputSchema": {
"type": "object",
"properties": {
"attackerUnitId": {"type": "string"},
"maxTargets": {"type": "integer", "default": 5}
},
"required": ["attackerUnitId"]
}
}Response:
{
"targets": [
{
"targetId": "guid",
"configurations": [
{
"type": "TorsoRotation",
"value": 1,
"score": 38.5,
"weapons": [
{
"weaponId": "guid",
"name": "PPC",
"hitProbability": 0.72,
"damage": 10
}
]
}
]
}
]
}The Agent Orchestrator selects the appropriate specialized agent based on the game phase:
public class AgentOrchestrator
{
private readonly Dictionary<string, IAgent> _agents;
public async Task<AgentResponse> ProcessDecision(DecisionRequest request)
{
var agent = request.Phase switch
{
"Deployment" => _agents["deployment"],
"Movement" => _agents["movement"],
"WeaponsAttack" => _agents["weapons"],
"End" => _agents["endphase"],
_ => throw new NotSupportedException($"Phase {request.Phase} not supported")
};
return await agent.MakeDecision(request);
}
}Each agent follows this execution pattern:
- Initialize MCP Client with bot's MCP Server URL
- Query Game State using appropriate MCP tools
- Generate Prompt with game context and tactical considerations
- Call LLM with structured output requirements
- Parse Response and validate decision
- Return DecisionResponse with success/error indication
Key Principle: Each decision request is completely stateless.
- No conversation history preserved between requests
- No context carried over between turns or phases
- Agent queries all needed information via MCP tools
- Fresh LLM context for each decision
Rationale: Simplifies architecture, avoids context window limits, ensures each decision is based on current game state only.
For a game with 4 LLM bots:
ServerGame (1 instance)
↓
Integration Bot Container × 4 (one per bot)
- Bot 1: Port 5001, ClientGame instance, MCP Server
- Bot 2: Port 5002, ClientGame instance, MCP Server
- Bot 3: Port 5003, ClientGame instance, MCP Server
- Bot 4: Port 5004, ClientGame instance, MCP Server
↓
LLM Agent Container (1 shared instance)
- Port 5000
- Handles concurrent stateless requests from all bots
Configuration Per Bot:
{
"Bot": {
"PlayerId": "bot-1-guid",
"PlayerName": "LLM Bot 1",
"McpServerPort": 5001
},
"Agent": {
"ApiUrl": "http://llm-agent:5000"
},
"ServerGame": {
"Url": "http://server:8080"
}
}Optionally should contain list of units to use
Decision responses are translated to game commands: As all commands are simple records, the Agent returns a corresponding IClientCommand structure directly to simplify/eliminate mappings
private async Task HandleDecisionError(DecisionResponse response, PhaseStep phaseStep)
{
_logger.LogWarning(
"LLM decision failed: {ErrorType} - {Message}",
response.ErrorType,
response.ErrorMessage
);
// Record metrics
_metrics.RecordFailure(response.ErrorType);
// Activate mandatory fallback
await _fallbackEngine.MakeDecision(_player, phaseStep.Phase);
}version: '3.8'
services:
# LLM Agent Container (Shared)
llm-agent:
build:
context: ./MakaMek.LlmAgent
dockerfile: Dockerfile
image: makamek/llm-agent:latest
container_name: makamek-llm-agent
ports:
- "5000:5000"
environment:
- ASPNETCORE_ENVIRONMENT=Production
- ASPNETCORE_URLS=http://+:5000
- LlmProvider__Type=OpenAI
- LlmProvider__Model=gpt-4o
- LlmProvider__ApiKey=${OPENAI_API_KEY}
- LlmProvider__Temperature=0.7
- LlmProvider__MaxTokens=2000
- LlmProvider__Timeout=30000
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
interval: 30s
timeout: 10s
retries: 3
restart: unless-stopped
networks:
- makamek-network
# Integration Bot 1
integration-bot-1:
build:
context: ./MakaMek.Bots.Llm
dockerfile: Dockerfile
image: makamek/integration-bot:latest
container_name: makamek-bot-1
ports:
- "5001:5001"
environment:
- ASPNETCORE_ENVIRONMENT=Production
- ASPNETCORE_URLS=http://+:5001
- Bot__PlayerId=${BOT_1_PLAYER_ID}
- Bot__PlayerName=LLM Bot 1
- Bot__McpServerPort=5001
- Agent__ApiUrl=http://llm-agent:5000
- ServerGame__Url=${SERVER_GAME_URL}
depends_on:
- llm-agent
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:5001/health"]
interval: 30s
timeout: 10s
retries: 3
restart: unless-stopped
networks:
- makamek-network
# Integration Bot 2
# add as many as needed based on the pattern
networks:
makamek-network:
driver: bridge# LLM Provider Configuration
OPENAI_API_KEY=sk-your-api-key-hereLLM Agent Dockerfile:
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 5000
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MakaMek.LlmAgent/MakaMek.LlmAgent.csproj", "MakaMek.LlmAgent/"]
RUN dotnet restore "MakaMek.LlmAgent/MakaMek.LlmAgent.csproj"
COPY . .
WORKDIR "/src/MakaMek.LlmAgent"
RUN dotnet build "MakaMek.LlmAgent.csproj" -c Release -o /app/build
FROM build AS publish
RUN dotnet publish "MakaMek.LlmAgent.csproj" -c Release -o /app/publish
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MakaMek.LlmAgent.dll"]Integration Bot Dockerfile:
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 5001
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MakaMek.Bots.Llm/MakaMek.Bots.Llm.csproj", "MakaMek.Bots.Llm/"]
COPY ["MakaMek.Core/MakaMek.Core.csproj", "MakaMek.Core/"]
COPY ["MakaMek.Bots/MakaMek.Bots.csproj", "MakaMek.Bots/"]
RUN dotnet restore "MakaMek.Bots.Llm/MakaMek.Bots.Llm.csproj"
COPY . .
WORKDIR "/src/MakaMek.Bots.Llm"
RUN dotnet build "MakaMek.Bots.Llm.csproj" -c Release -o /app/build
FROM build AS publish
RUN dotnet publish "MakaMek.Bots.Llm.csproj" -c Release -o /app/publish
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MakaMek.Bots.Llm.dll"]# Build images
docker-compose build
# Start all containers
docker-compose up -d
# View logs
docker-compose logs -f llm-agent
docker-compose logs -f integration-bot-1
# Stop all containers
docker-compose down
# Rebuild and restart
docker-compose up -d --build- Set up project structure for both containers
- Implement basic ASP.NET Core applications
- Create MCP Server with minimal tool set
- Implement Agent API with one agent (Movement)
- Basic docker-compose configuration
- End-to-end test with one bot
- Implement all 4 specialized agents
- Complete MCP tool catalog
- Implement mandatory fallback engines
- Error handling and structured responses
- Multi-bot testing (2-4 bots)
- Logging and telemetry
- Health checks and monitoring
- Performance optimization
- Documentation and deployment guides
- Demo scenarios and testing
Agent Decision API:
- Endpoint:
POST /api/decision - Content-Type:
application/json - Timeout: 30 seconds
- Max Request Size: 10 MB
MCP Server API:
- Endpoint:
/mcp - Protocol: JSON-RPC 2.0 over HTTP/SSE
- Timeout: 15 seconds per tool call
- Max Tool Calls: 10 per decision request
- Decision Latency: < 30 seconds (acceptable for POC)
- MCP Tool Call Latency: < 2 seconds per call
- Agent Concurrent Requests: Support 4 simultaneous bots
- Memory Usage: < 2 GB per container
- Uptime: No specific requirement (POC only)
API Keys:
- Stored in environment variables
- Never committed to source control
- Rotated periodically
Network Security:
- Container-to-container communication via private network
- No direct external access to API of both services
Input Validation:
- Basic parameter validation in MCP tools
- Command validation in Integration Bot
- LLM response validation before execution
Log Levels:
- Info: Decision requests, successful executions
- Warning: Fallback activations, retry attempts
- Error: LLM failures, network errors, invalid responses
Key Metrics:
- Decision success rate
- Average decision latency
- Fallback activation rate
- LLM token usage
- MCP tool call frequency
Logging Format:
{
"timestamp": "2026-01-13T10:30:45Z",
"level": "Info",
"message": "Decision completed successfully",
"context": {
"botId": "bot-1",
"phase": "Movement",
"latency": 8500,
"mcpCalls": 3,
"tokensUsed": 2400
}
}Common Issues:
-
Agent Not Responding
- Check Agent container health:
docker ps - Check Agent logs:
docker logs makamek-llm-agent - Verify API key configuration
- Check Agent container health:
-
MCP Tools Failing
- Check ClientGame connection status
- Verify game state is valid
- Review MCP Server logs
-
Fallback Always Activating
- Check LLM provider status
- Verify network connectivity
- Review error responses in logs
-
Bot Not Making Decisions
- Verify phase subscription is working
- Check active player ID matches bot ID
- Review Integration Bot logs
LLM API Costs (not a concern for POC, but for future reference):
- Estimated tokens per decision: 3,000-10,000
- Estimated decisions per game: 40-100
- Estimated cost per game (GPT-4): $0.30-$1.50
- Cost optimization strategies:
- Use cheaper models for simple phases
- Cache common tactical evaluations
- Reduce context size where possible
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. It enables:
- Tools: Functions that LLMs can call to perform actions
- Resources: Data sources that LLMs can read
- Prompts: Reusable prompt templates
- Sampling: LLM completion requests
Key Benefits:
- Standardized interface for LLM-application integration
- Language-agnostic protocol (JSON-RPC over HTTP/SSE)
- Built-in support for streaming and real-time updates
- Growing ecosystem of MCP servers and clients
References:
- MCP Specification: MCP Specification
- MCP C# SDK: C# SDK
Microsoft Agent Framework provides building blocks for creating AI agents. It is the evolution of Semantic Kernel with integrated AutoGen features.
- Agent Orchestration: Coordinate multiple specialized agents
- Skills: Reusable capabilities that agents can use
- Memory: Conversation history and context management
- Planning: Multi-step reasoning and task decomposition
- Tool Use: Integration with external tools and APIs
Key Features:
- Support for multiple LLM providers
- Structured output generation
- Chain-of-thought reasoning
- Function calling and tool use
- Multi-agent collaboration
References:
- GitHub: GitHub
Description: Integrate LLM calls directly into existing bot engines without MCP.
Pros:
- Simpler architecture
- Fewer components to maintain
- Lower latency
Cons:
- Tight coupling between game logic and LLM
- Harder to swap LLM providers
- No standardized tool interface
- Difficult to test and debug
Decision: Rejected due to tight coupling and lack of flexibility.
Description: Use one general-purpose agent for all game phases instead of specialized agents.
Pros:
- Simpler agent management
- Single system prompt
- Easier to maintain
Cons:
- Lower decision quality due to lack of specialization
- Larger context windows required
- Harder to optimize prompts per phase
- More expensive LLM calls
Decision: Rejected in favor of specialized agents for better decision quality.
Description: Host both Agent and Integration Bot in one container.
Pros:
- Simpler deployment
- No network calls between Agent and Bot
- Lower latency
Cons:
- Cannot scale Agent independently
- Tight coupling of components
- Harder to debug and monitor
- Multiple bots require duplicate Agent instances
Decision: Rejected in favor of 2-container architecture for better separation and resource sharing.
Key Tactical Concepts for LLM Prompts:
- Range Brackets: Weapons have optimal ranges (short/medium/long)
- Heat Management: Balance damage output with heat dissipation
- Armor Facing: Protect damaged armor by not exposing damaged arcs
- Terrain Usage: Use woods for cover, elevation for advantage
- Target Priority: Focus fire on damaged units
- Movement Types: Walking (low heat) vs Running (high heat) vs Jumping (highest heat)
- Piloting Skill Rolls: Avoid situations requiring PSRs
- Ammunition Conservation: Don't waste limited ammo on low-probability shots
- Shutdown Risk: Avoid overheating that causes shutdown
- Rear Arc Vulnerability: Minimize exposure of rear armor
Example Tactical Scenario:
Situation: Atlas (heavy mech) at heat 18/30, facing damaged Jenner (light mech)
Options:
1. Walk forward, fire all weapons (heat +12, high hit probability)
2. Run forward, fire half weapons (heat +8, medium hit probability)
3. Stay put, fire all weapons (heat +10, medium hit probability)
Best Choice: Option 1 - Walking provides stable platform for high hit probability,
heat is manageable, and Jenner is priority target due to existing damage.
Agent Error Types:
-
AGENT_CANNOT_DECIDE- Agent unable to generate valid decision -
LLM_TIMEOUT- LLM provider request exceeded timeout -
INVALID_GAME_STATE- Game state is invalid or inconsistent
MCP Tool Error Codes:
-
INVALID_UNIT_ID- Unit ID not found in game state -
INVALID_HEX_COORDINATES- Hex coordinates out of map bounds -
UNIT_NOT_ACTIVE- Requested unit is not the active player's unit -
INVALID_PHASE- Tool not applicable for current phase -
INTERNAL_ERROR- Unexpected internal error
- End-to-End: Full decision flow from game state to command execution
- MCP Protocol: Test tool calls and resource access
- Multi-Bot: Test concurrent bot operations
- Fallback: Test graceful degradation when LLM unavailable
- Deployment: Verify optimal positioning selection
- Movement: Verify tactical path scoring
- Weapons: Verify target prioritization
- Heat: Verify shutdown decisions
This design provides a comprehensive proof-of-concept architecture for integrating LLM-powered bots into MakaMek, demonstrating the viability of the two-container pattern while deferring production concerns such as cost optimization, rate limiting, and operational hardening.
- Flexibility: Easy to swap LLM providers and models
- Reliability: Mandatory fallback to rule-based engines ensures game continuity
- Scalability: Support for multiple concurrent bot players via separate container instances
- Maintainability: Clear separation of concerns and standardized interfaces
- Extensibility: Easy to add new capabilities and improve decision quality
- Resource Efficiency: Shared Agent container reduces LLM API costs
The deployment architecture using Docker containers provides:
- Easy orchestration with docker-compose
- Clear separation between shared (Agent) and per-bot (Integration Bot) resources
- Straightforward scaling for multiple bots
- Standard monitoring and health checks
Key Design Decisions Confirmed:
- ✅ 2 Docker containers with ASP.NET Core hosting
- ✅ Stateless agent requests with MCP for state queries
- ✅ Separate Integration Bot container per bot player
- ✅ Shared LLM Agent container for all bots
- ✅ Mandatory fallback engines for reliability
- ✅ Structured error responses (not HTTP error codes)
- ✅ Basic error validation (not complex schema validation)
- ✅ Read-only MCP Server (no command execution tools)
Next Steps:
- ✅ Review and approve this design document v2.0
- Set up development environment and project structure
- Begin Phase 1 implementation (Foundation)
- Create initial docker-compose configuration
- Implement first end-to-end test with one bot
- Iterate based on feedback and performance data
Document Version History:
- v2.0 (2026-01-13): Major revision based on clarifications - confirmed 2-container architecture, stateless design, multi-bot deployment pattern, mandatory fallback, structured errors, docker-compose specification
- v1.1 (2026-01-12): Updated to .NET 10, clarified 4 specialized agents, embedded Mermaid diagrams
- v1.0 (2026-01-12): Initial comprehensive design document
Contributors:
- Architecture Design: AI Assistant
- Technical Review: User (2026-01-13)
- Approval: Pending
POC Scope Clarifications:
- No cost optimization required (demo/testing only)
- No unit tests required (integration testing only)
- No latency optimization required
- Basic error validation sufficient
- Prompt templates can be improved later
- Focus on proving the architecture works end-to-end
graph TB
subgraph "Integration Bot (Component 2)"
LBM[LlmBotManager]
LDEP[LlmDecisionEngineProvider]
subgraph "LLM Decision Engines"
LDE[LlmDeploymentEngine]
LME[LlmMovementEngine]
LWE[LlmWeaponsEngine]
LEE[LlmEndPhaseEngine]
end
subgraph "Fallback Engines"
DE[DeploymentEngine]
ME[MovementEngine]
WE[WeaponsEngine]
EE[EndPhaseEngine]
end
BAC[BotAgentClient]
CG[ClientGame]
end
subgraph "BotAgent API (Component 1)"
API[POST /api/decision]
LLM[LLM Agent]
end
subgraph "Configuration"
CFG[appsettings.json]
BACFG[BotAgentConfiguration]
end
LBM -->|creates| LDEP
LDEP -->|provides| LDE
LDEP -->|provides| LME
LDEP -->|provides| LWE
LDEP -->|provides| LEE
LDE -->|wraps| DE
LME -->|wraps| ME
LWE -->|wraps| WE
LEE -->|wraps| EE
LDE -->|uses| BAC
LME -->|uses| BAC
LWE -->|uses| BAC
LEE -->|uses| BAC
LDE -->|executes on| CG
LME -->|executes on| CG
LWE -->|executes on| CG
LEE -->|executes on| CG
BAC -->|HTTP POST| API
API -->|delegates to| LLM
LLM -->|DecisionResponse| API
API -->|returns| BAC
CFG -->|loads| BACFG
BACFG -->|configures| BAC
BAC -.->|on error| LDE
LDE -.->|fallback| DE
style LDE fill:#4a90e2,color:#fff
style LME fill:#4a90e2,color:#fff
style LWE fill:#4a90e2,color:#fff
style LEE fill:#4a90e2,color:#fff
style BAC fill:#e24a4a,color:#fff
style API fill:#50c878,color:#fff
style LLM fill:#50c878,color:#fff