Repository navigation
llm deployment agent design
Version: 1.1
Date: 2026-01-19
Status: Design Specification
Related: docs/architecture/llm-bot-system-design.md
This document provides a comprehensive design for implementing complete LLM decision-making functionality for the Deployment phase in the MakaMek bot system. The design addresses identified gaps in the current DeploymentAgent implementation and provides detailed specifications for:
- Enhanced game state communication via
DecisionRequest - MCP tools for deployment zone queries
- Structured output using Microsoft Agent Framework
- Enhanced system prompts with BattleTech tactical knowledge
- Complete integration flow with error handling
Goal: Enable the DeploymentAgent to make informed, tactical deployment decisions using LLM reasoning while maintaining seamless integration with the existing LlmDeploymentEngine and fallback mechanisms.
Key Change in v1.1: Adoption of Microsoft Agent Framework's structured output feature (RunAsync<T>) to eliminate custom JSON parsing and improve reliability.
Three-step workflow:
- SelectingUnit: Player selects which unit to deploy
- SelectingHex: Player selects deployment position (edge hex, unoccupied)
- SelectingDirection: Player selects facing direction (0-5, representing Top, TopRight, BottomRight, Bottom, BottomLeft, TopLeft)
Command Structure:
DeployUnitCommand {
UnitId: Guid,
Position: HexCoordinateData { Q: int, R: int },
Direction: int (0-5),
GameOriginId: Guid,
PlayerId: Guid,
IdempotencyKey: Guid?
}Validation:
- Hex must not be occupied by another unit
- Position must be in deployment zone
- Direction must be 0-5
Decision Logic:
- Find first undeployed unit from player's units
- Get occupied hexes (all deployed units across all players)
- Get deployment area using
BattleMap.GetEdgeHexCoordinates() - Filter valid hexes:
deploymentArea - occupiedHexes - Randomly select a valid hex
- Calculate strategic facing:
- If enemies deployed: face toward nearest enemy
- If no enemies: face toward map center
- Use
HexCoordinates.LineTo()to get direction
- Create and send
DeployUnitCommand
Key Methods:
-
GetDeploymentArea(): Returns edge hexes asHashSet<HexCoordinates> -
GetValidDeploymentHexes(): Filters unoccupied hexes -
GetDeploymentDirection(): Calculates facing based on target
Two-Container Architecture:
- Component 1 (BotAgent): ASP.NET Core Web API hosting specialized agents
- Component 2 (BotContainer): Integration Bot with MCP Server and ClientGame
Current DecisionRequest:
public record DecisionRequest(
Guid PlayerId,
string Phase,
string McpServerUrl,
int Timeout = 30000
);Current DecisionResponse:
public record DecisionResponse(
bool Success,
IGameCommand? Command,
string? Reasoning,
string? ErrorType,
string? ErrorMessage,
bool FallbackRequired
);Current DeploymentAgent Issues:
-
ParseDecision()returns dummy command withGuid.Emptyvalues - No actual JSON parsing implementation
- No MCP tool integration
- Generic system prompt without tactical guidance
- No game state information in request
-
Insufficient Game State in DecisionRequest
- No unit information (controlled units, enemy units)
- No deployment zone information
- No map context
- Agent cannot make informed decisions without this data
-
Missing MCP Tools
-
McpClientServicehas placeholder methods - No actual MCP protocol implementation
- No tools registered with
ChatClientAgent
-
-
No Structured Output Implementation
-
ParseDecision()is a stub - Not using MAF's structured output capabilities
- No validation of LLM output
-
-
Generic System Prompt
- Lacks BattleTech tactical knowledge
- No output format specification
- No guidance on decision criteria
-
No Validation Layer
- No checks for valid unit IDs
- No position validation
- No direction range validation
The agent needs access to:
- Controlled Units: List of bot's units with deployment status
- Enemy Units: List of enemy units with positions (if deployed)
- Valid Deployment Zones: Edge hexes that are unoccupied
- Unit Selection: Which unit to deploy (or let agent choose)
Approach: Implement a core MCP tool for deployment decisions
Tool: get_deployment_zones
{
"name": "get_deployment_zones",
"description": "Get valid deployment hexes (unoccupied edge hexes)",
"inputSchema": {
"type": "object",
"properties": {},
"required": []
}
}Response:
{
"validHexes": [
{"q": 1, "r": 1},
{"q": 1, "r": 2},
...
],
"mapWidth": 10,
"mapHeight": 10,
"mapCenter": {"q": 5, "r": 5}
}Implementation:
- Call
BattleMap.GetEdgeHexCoordinates() - Return list of valid positions with map metadata
Tool Registration:
Tools should be registered with ChatClientAgent in DeploymentAgent constructor:
Agent = new ChatClientAgent(
chatClient: llmProvider.GetChatClient(),
instructions: SystemPrompt,
tools: new[] {
GetDeploymentZonesTool() // next phase, no tools in initial implementation
}
);Approach: Use Microsoft Agent Framework's RunAsync<T> for type-safe structured output
Key Advantages:
- ✅ Eliminates custom JSON parsing code
- ✅ Type-safe at compile time
- ✅ Built-in validation by MAF
- ✅ Handles JSON extraction automatically
- ✅ More reliable than regex-based parsing
Output Record Definition:
/// <summary>
/// Structured output from DeploymentAgent LLM decision.
/// This record is used with ChatClientAgent.RunAsync<T> for type-safe structured output.
/// </summary>
public record DeploymentAgentOutput
{
/// <summary>
/// GUID of the unit to deploy (as string for LLM output).
/// </summary>
public required string UnitId { get; init; }
/// <summary>
/// Hex position for deployment.
/// </summary>
public required HexCoordinateData Position { get; init; }
/// <summary>
/// Facing direction (0-5).
/// 0 = Top, 1 = TopRight, 2 = BottomRight, 3 = Bottom, 4 = BottomLeft, 5 = TopLeft
/// </summary>
public required int Direction { get; init; }
/// <summary>
/// Tactical reasoning for the deployment decision.
/// </summary>
public required string Reasoning { get; init; }
}Agent Implementation:
public async Task<DecisionResponse> MakeDecisionAsync(
DecisionRequest request,
CancellationToken cancellationToken = default)
{
try
{
Logger.LogInformation("{AgentName} making decision for player {PlayerId}", Name, request.PlayerId);
// Build user prompt with game context from DecisionRequest
var userPrompt = BuildUserPrompt(request);
// Run agent with structured output
var structuredResponse = await Agent.RunAsync<DeploymentAgentOutput>(
userPrompt,
cancellationToken: cancellationToken);
// Map structured output to DecisionResponse
return MapToDecisionResponse(structuredResponse, request);
}
catch (Exception ex)
{
Logger.LogError(ex, "Error in {AgentName} decision making", Name);
return CreateErrorResponse("AGENT_ERROR", ex.Message);
}
}
private DecisionResponse MapToDecisionResponse(
DeploymentAgentOutput output,
DecisionRequest request)
{
// Validate GUID
if (!Guid.TryParse(output.UnitId, out var unitId))
{
Logger.LogError("Invalid unitId in LLM output: {UnitId}", output.UnitId);
throw new InvalidOperationException("INVALID_UNIT_ID");
}
// Validate direction range
if (output.Direction < 0 || output.Direction > 5)
{
Logger.LogError("Invalid direction in LLM output: {Direction}", output.Direction);
throw new InvalidOperationException("INVALID_DIRECTION");
}
// Create command
var command = new DeployUnitCommand
{
PlayerId = request.PlayerId,
UnitId = unitId,
GameOriginId = Guid.Empty, // Will be set by ClientGame
Position = output.Position,
Direction = output.Direction,
IdempotencyKey = null // Will be set by ClientGame
};
return new DecisionResponse(
Success: true,
Command: command,
Reasoning: output.Reasoning,
ErrorType: null,
ErrorMessage: null,
FallbackRequired: false
);
}Approach: Comprehensive prompt with tactical guidance and output specification
Enhanced SystemPrompt:
protected override string SystemPrompt => """
You are a BattleTech tactical AI specializing in unit deployment. Your role is to select
optimal deployment positions and facing directions for your units. You make a decision for only one unit a time.
TACTICAL PRINCIPLES:
- Deploy in valid deployment zones
- Face toward enemies if deployed, otherwise toward map center
- Consider unit role:
* Heavy mechs (70-100 tons): Deploy forward for frontline combat
* Medium mechs (40-55 tons): Deploy for tactical flexibility
* Light mechs (20-35 tons): Deploy for flanking and mobility
- Avoid clustering - spread units for tactical flexibility
- Use terrain for advantage when available (cover, elevation)
- Maintain line of sight to expected engagement areas
AVAILABLE INFORMATION:
- Controlled units: Your units with deployment status
- Enemy units: Enemy units with positions (if deployed)
- Valid deployment zones: use get_deployment_zones tool // add once implemented
DECISION PROCESS:
1. Identify which unit to deploy (first undeployed unit if not specified)
2. Analyze valid deployment positions
3. Consider enemy positions and map center
4. Select position that maximizes tactical advantage
5. Calculate optimal facing direction
OUTPUT FORMAT:
You must respond with a structured JSON object containing:
{
"unitId": "guid-string",
"position": {"q": int, "r": int},
"direction": int (0-5),
"reasoning": "brief tactical explanation"
}
Direction (facing) values:
0 = Top, 1 = TopRight, 2 = BottomRight, 3 = Bottom, 4 = BottomLeft, 5 = TopLeft
IMPORTANT: Ensure:
- unitId is a valid GUID string from the provided unit list (a unit we are going to deploy)
- position Q and R are integers within map bounds
- direction is an integer between 0 and 5 (inclusive)
- reasoning clearly explains the tactical rationale
""";Key Elements:
- Role Definition: Clear statement of agent's purpose
- Tactical Principles: BattleTech-specific deployment strategies
- Available Information: What data the agent has access to
- Decision Process: Step-by-step guidance
- Output Format: Exact JSON structure (for MAF structured output)
- Direction Mapping: Clear explanation of direction values
- Validation Notes: Emphasize structured output requirements
File: src/MakaMek.Tools/BotAgent.Models/DecisionRequest.cs
Changes:
using Sanet.MakaMek.Core.Data.Units;
namespace BotAgent.Models;
/// <summary>
/// Request from Integration Bot to LLM Agent for tactical decision.
/// </summary>
/// <param name="PlayerId">The ID of the player (bot) requesting the decision.</param>
/// <param name="Phase">The current game phase (Deployment, Movement, WeaponsAttack, End).</param>
/// <param name="McpServerUrl">The URL of the Integration Bot's MCP Server for game state queries.</param>
/// <param name="Timeout">Request timeout in milliseconds (default: 30000).</param>
/// <param name="ControlledUnits">Bot's units with full state.</param>
/// <param name="EnemyUnits">Enemy units with positions.</param>
/// <param name="UnitToAct">Specific unit to deploy (optional, if null agent chooses).</param>
public record DecisionRequest(
Guid PlayerId,
string Phase,
string McpServerUrl,
int Timeout = 30000,
List<UnitData> ControlledUnits,
List<UnitData> EnemyUnits,
Guid? UnitToAct = null
);File: src/MakaMek.Tools/BotAgent.Models/DeploymentAgentOutput.cs
using Sanet.MakaMek.Core.Data.Map;
namespace BotAgent.Models;
/// <summary>
/// Structured output from DeploymentAgent LLM decision.
/// This record is used with ChatClientAgent.RunAsync<T> for type-safe structured output.
/// </summary>
public record DeploymentAgentOutput
{
/// <summary>
/// GUID of the unit to deploy (as string for LLM output).
/// </summary>
public required string UnitId { get; init; }
/// <summary>
/// Hex position for deployment.
/// </summary>
public required HexCoordinateData Position { get; init; }
/// <summary>
/// Facing direction (0-5).
/// 0 = Top, 1 = TopRight, 2 = BottomRight, 3 = Bottom, 4 = BottomLeft, 5 = TopLeft
/// </summary>
public required int Direction { get; init; }
/// <summary>
/// Tactical reasoning for the deployment decision.
/// </summary>
public required string Reasoning { get; init; }
}File: src/MakaMek.Tools/BotAgent/Agents/DeploymentAgent.cs
Complete Implementation with Structured Output:
using BotAgent.Models;
using BotAgent.Services;
using Microsoft.Extensions.AI;
using Sanet.MakaMek.Core.Data.Game.Commands.Client;
namespace BotAgent.Agents;
/// <summary>
/// Deployment phase agent - selects optimal deployment position and facing for units.
/// Uses Microsoft Agent Framework's structured output (RunAsync<T>) for type-safe decisions.
/// </summary>
public class DeploymentAgent : BaseAgent
{
public override string Name => "DeploymentAgent";
public override string Description => "Specialist in unit deployment and initial positioning";
protected override string SystemPrompt => """
// Enhanced system prompt from section 3.4 above
""";
public DeploymentAgent(
ILlmProvider llmProvider,
McpClientService mcpClient,
ILogger<DeploymentAgent> logger)
: base(llmProvider, mcpClient, logger)
{
}
public override async Task<DecisionResponse> MakeDecisionAsync(
DecisionRequest request,
CancellationToken cancellationToken = default)
{
try
{
Logger.LogInformation("{AgentName} making decision for player {PlayerId}", Name, request.PlayerId);
// Build user prompt with game context from DecisionRequest
var userPrompt = BuildUserPrompt(request);
// Run agent with structured output using MAF
var structuredResponse = await ((ChatClientAgent)Agent).RunAsync<DeploymentAgentOutput>(
userPrompt,
cancellationToken: cancellationToken);
Logger.LogInformation(
"{AgentName} received structured output - Unit: {UnitId}, Position: ({Q},{R}), Direction: {Direction}",
Name,
structuredResponse.UnitId,
structuredResponse.Position.Q,
structuredResponse.Position.R,
structuredResponse.Direction);
// Map structured output to DecisionResponse
return MapToDecisionResponse(structuredResponse, request);
}
catch (InvalidOperationException ex) when (ex.Message.StartsWith("INVALID_"))
{
Logger.LogError(ex, "{AgentName} validation error", Name);
return CreateErrorResponse(ex.Message, ex.InnerException?.Message ?? ex.Message);
}
catch (Exception ex)
{
Logger.LogError(ex, "Error in {AgentName} decision making", Name);
return CreateErrorResponse("AGENT_ERROR", ex.Message);
}
}
/// <summary>
/// Maps the structured LLM output to DecisionResponse with validation.
/// </summary>
private DecisionResponse MapToDecisionResponse(
DeploymentAgentOutput output,
DecisionRequest request)
{
// Validate GUID
if (!Guid.TryParse(output.UnitId, out var unitId))
{
Logger.LogError("Invalid unitId in LLM output: {UnitId}", output.UnitId);
throw new InvalidOperationException("INVALID_UNIT_ID");
}
// Validate direction range
if (output.Direction < 0 || output.Direction > 5)
{
Logger.LogError("Invalid direction in LLM output: {Direction}", output.Direction);
throw new InvalidOperationException("INVALID_DIRECTION");
}
// Create command
var command = new DeployUnitCommand
{
PlayerId = request.PlayerId,
UnitId = unitId,
GameOriginId = Guid.Empty, // Will be set by ClientGame
Position = output.Position,
Direction = output.Direction,
IdempotencyKey = null // Will be set by ClientGame
};
Logger.LogInformation(
"{AgentName} created DeployUnitCommand - PlayerId: {PlayerId}, UnitId: {UnitId}",
Name,
command.PlayerId,
command.UnitId);
return new DecisionResponse(
Success: true,
Command: command,
Reasoning: output.Reasoning,
ErrorType: null,
ErrorMessage: null,
FallbackRequired: false
);
}
}File: src/MakaMek.Tools/BotContainer/Models/DecisionEngines/LlmDeploymentEngine.cs
Changes to populate DecisionRequest:
Modify the base class LlmDecisionEngine<T> to include controlled and enemy units (from _clientGame) and unit to act (from turnState). This is the same for all the phases.
File: src/MakaMek.Tools/BotAgent/Agents/BaseAgent.cs
Changes to ensure ChatClientAgent type and BuildUserPrompt:
using Microsoft.Extensions.AI;
namespace BotAgent.Agents;
public abstract class BaseAgent
{
protected ChatClientAgent Agent { get; init; }
protected ILogger Logger { get; init; }
protected McpClientService McpClient { get; init; }
public abstract string Name { get; }
public abstract string Description { get; }
protected abstract string SystemPrompt { get; }
protected BaseAgent(
ILlmProvider llmProvider,
McpClientService mcpClient,
ILogger logger)
{
McpClient = mcpClient;
Logger = logger;
// CRITICAL: Must be ChatClientAgent for structured output support
Agent = new ChatClientAgent(
chatClient: llmProvider.GetChatClient(),
instructions: SystemPrompt
);
}
/// <summary>
/// Make a decision using the agent. Can be overridden by specialized agents
/// that use structured output.
/// </summary>
public virtual async Task<DecisionResponse> MakeDecisionAsync(
DecisionRequest request,
CancellationToken cancellationToken = default)
{
try
{
Logger.LogInformation("{AgentName} making decision for player {PlayerId}", Name, request.PlayerId);
// Build user prompt with game context from DecisionRequest
var userPrompt = BuildUserPrompt(request);
// Run agent (basic RunAsync, not structured)
var response = await Agent.RunAsync(userPrompt, cancellationToken: cancellationToken);
var responseText = response.ToString();
Logger.LogInformation("{AgentName} received response", Name);
return new DecisionResponse(
Success: true,
Command: null, // Will be set by specialized agents
Reasoning: responseText,
ErrorType: null,
ErrorMessage: null,
FallbackRequired: false
);
}
catch (Exception ex)
{
Logger.LogError(ex, "Error in {AgentName} decision making", Name);
return CreateErrorResponse("AGENT_ERROR", ex.Message);
}
}
/// <summary>
/// Build user prompt with game context. Can be overridden by specialized agents.
/// </summary>
protected virtual string BuildUserPrompt(DecisionRequest request)
{
var sb = new StringBuilder();
sb.AppendLine($"Make a tactical decision for player {request.PlayerId} in phase {request.Phase}.");
sb.AppendLine();
// Add controlled units information
if (request.ControlledUnits != null && request.ControlledUnits.Count > 0)
{
sb.AppendLine("YOUR UNITS:");
foreach (var unit in request.ControlledUnits)
{
var deployStatus = unit.Position != null ? "DEPLOYED" : "UNDEPLOYED";
sb.AppendLine($"- {unit.Model} ({unit.Mass} tons) - {deployStatus}");
if (unit.Id.HasValue)
sb.AppendLine($" ID: {unit.Id.Value}");
}
sb.AppendLine();
}
// Add enemy units information
if (request.EnemyUnits != null && request.EnemyUnits.Count > 0)
{
sb.AppendLine("ENEMY UNITS:");
foreach (var enemy in request.EnemyUnits)
{
sb.AppendLine($"- {enemy.Model} ({enemy.Mass} tons)");
if (enemy.Position != null)
sb.AppendLine($" Position: Q={enemy.Position.Q}, R={enemy.Position.R}");
}
sb.AppendLine();
}
// Add specific unit to deploy if specified
if (request.UnitToAct.HasValue)
{
sb.AppendLine($"DEPLOY UNIT: {request.UnitToAct.Value}");
sb.AppendLine();
}
sb.AppendLine("Use the get_deployment_zones tool to query valid deployment positions.");// this is only when MCP is implemented
sb.AppendLine("Select the best deployment position and facing direction based on tactical principles.");
return sb.ToString();
}
protected DecisionResponse CreateErrorResponse(string errorType, string errorMessage)
{
return new DecisionResponse(
Success: false,
Command: null,
Reasoning: null,
ErrorType: errorType,
ErrorMessage: errorMessage,
FallbackRequired: true
);
}
}sequenceDiagram
participant BM as BotManager
participant LDE as LlmDeploymentEngine
participant BAC as BotAgentClient
participant API as BotAgent API
participant AO as AgentOrchestrator
participant DA as DeploymentAgent
participant LLM as LLM Provider
participant MAF as MS Agent Framework
participant CG as ClientGame
BM->>LDE: MakeDecision(player, turnState)
LDE->>LDE: CreateDecisionRequest(playerId, mcpServerUrl)
Note over LDE: Populate ControlledUnits,<br/>EnemyUnits, UnitToAct
LDE->>BAC: RequestDecisionAsync(request)
BAC->>API: POST /api/decision
API->>AO: ProcessDecisionAsync(request)
AO->>DA: MakeDecisionAsync(request)
DA->>DA: BuildUserPrompt(request)
DA->>MAF: RunAsync<DeploymentAgentOutput>(userPrompt)
MAF->>LLM: Generate structured output
LLM-->>MAF: JSON response
MAF->>MAF: Parse to DeploymentAgentOutput
MAF-->>DA: DeploymentAgentOutput (type-safe)
DA->>DA: MapToDecisionResponse(output)
DA->>DA: Validate (unitId, direction)
DA-->>AO: DecisionResponse(success, command, reasoning)
AO-->>API: DecisionResponse
API-->>BAC: HTTP 200 + DecisionResponse
BAC-->>LDE: DecisionResponse
LDE->>LDE: ExecuteCommandAsync(command)
LDE->>CG: DeployUnit(deployCommand)
alt Validation error
DA->>DA: Validation fails
DA-->>AO: DecisionResponse(error, INVALID_*)
AO-->>API: DecisionResponse
API-->>BAC: HTTP 200 + DecisionResponse
BAC-->>LDE: DecisionResponse
LDE->>FallbackEngine: MakeDecision(player)
end
alt MAF parsing error
MAF->>MAF: Failed to parse
MAF-->>DA: Exception
DA-->>AO: DecisionResponse(error, AGENT_ERROR)
AO-->>API: DecisionResponse
API-->>BAC: HTTP 200 + DecisionResponse
BAC-->>LDE: DecisionResponse
LDE->>FallbackEngine: MakeDecision(player)
end
-
LlmDeploymentEngine.CreateDecisionRequest()
- Queries
ClientGame.Playersfor controlled and enemy units - Converts units to
UnitDatausingunit.ToData() - Constructs
DecisionRequestwith game state
- Queries
-
DeploymentAgent.BuildUserPrompt()
- Formats game state from
DecisionRequestinto natural language - Includes unit lists with deployment status
- Provides clear instructions for LLM
- Formats game state from
-
Microsoft Agent Framework RunAsync()
- NEW: Automatically handles structured output generation
-
NEW: Parses LLM response to
DeploymentAgentOutput - NEW: Provides type-safe output (no manual JSON parsing)
- NEW: Built-in validation of output structure
-
DeploymentAgent.MapToDecisionResponse()
- NEW: Simple mapping from structured output to command
- NEW: Minimal validation (GUID format, direction range)
-
NEW: Creates
DeployUnitCommandfrom validated output -
NEW: Returns
DecisionResponsewith command and reasoning
-
LlmDeploymentEngine.ExecuteCommandAsync()
- Receives command from BotAgentClient
- Validates command type
- Sends to
ClientGame.DeployUnit() - Falls back to
DeploymentEngineon error
| Error Type | Cause | Fallback Required | Handling |
|---|---|---|---|
INVALID_UNIT_ID |
Unit ID not valid GUID format | Yes | Log error, use fallback engine |
INVALID_DIRECTION |
Direction not in range 0-5 | Yes | Log error, use fallback engine |
MCP_ERROR |
MCP tool call failure | Yes | Log error, use fallback engine |
LLM_TIMEOUT |
LLM request timeout | Yes | Log error, use fallback engine |
AGENT_ERROR |
Unexpected agent error | Yes | Log error, use fallback engine |
In DeploymentAgent.MapToDecisionResponse():
// Validate GUID
if (!Guid.TryParse(output.UnitId, out var unitId))
{
Logger.LogError("Invalid unitId in LLM output: {UnitId}", output.UnitId);
throw new InvalidOperationException("INVALID_UNIT_ID");
}
// Validate direction range
if (output.Direction < 0 || output.Direction > 5)
{
Logger.LogError("Invalid direction in LLM output: {Direction}", output.Direction);
throw new InvalidOperationException("INVALID_DIRECTION");
}In DeploymentAgent.MakeDecisionAsync():
catch (InvalidOperationException ex) when (ex.Message.StartsWith("INVALID_"))
{
Logger.LogError(ex, "{AgentName} validation error", Name);
return CreateErrorResponse(ex.Message, ex.InnerException?.Message ?? ex.Message);
}
catch (Exception ex) // Catches MAF parsing errors and other exceptions
{
Logger.LogError(ex, "Error in {AgentName} decision making", Name);
return CreateErrorResponse("AGENT_ERROR", ex.Message);
}In LlmDeploymentEngine.MakeDecision():
catch (Exception ex)
{
Logger.LogError(
ex,
"{EngineType}: Error making decision for player {PlayerName}. Using fallback engine.",
GetType().Name,
player.Name);
await FallbackEngine.MakeDecision(player, turnState);
}Before creating DeployUnitCommand, validate:
- ✅ Unit ID is valid GUID format
- ✅ Direction is 0-5
- Deploy first unit with no enemies → faces map center
- Deploy second unit with enemy deployed → faces enemy
- Deploy heavy mech → selects forward position
- Deploy light mech → selects flanking position
- MAF structured output parsing works correctly
- Invalid unit ID → validation error → fallback
- Invalid direction → validation error → fallback
- LLM timeout → falls back to rule-based engine
- Multiple bots deploying → no conflicts
-
Full MCP Tool Integration
- Implement actual MCP protocol calls
- Register tools with ChatClientAgent
- LLM calls tools directly instead of manual prompt building
This design document provides a complete specification for implementing LLM-based deployment decisions in the MakaMek bot system using Microsoft Agent Framework's structured output feature. Key achievements:
✅ Enhanced DecisionRequest with game state (ControlledUnits, EnemyUnits, UnitToAct)
✅ MCP Tools Design for deployment zones, unit info, and enemy positions
✅ Structured Output Strategy using MAF's RunAsync<T> (eliminates custom JSON parsing)
✅ DeploymentAgentOutput Record for type-safe LLM output
✅ Enhanced SystemPrompt with BattleTech tactical knowledge
✅ Complete Integration Flow from LlmDeploymentEngine to ClientGame
✅ Comprehensive Error Handling with fallback to rule-based engine
✅ Testing Strategy for unit, integration, and manual testing
- Update
DecisionRequest.cswith additional fields - Create
DeploymentAgentOutput.csrecord - Update
DeploymentAgent.csto useRunAsync<DeploymentAgentOutput>() - Implement
DeploymentAgent.MapToDecisionResponse()method - Update
DeploymentAgent.SystemPromptwith enhanced prompt - Update
BaseAgent.csto ensureChatClientAgenttype - Implement
BaseAgent.BuildUserPrompt()virtual method - Update
LlmDeploymentEngine.CreateDecisionRequest()to populate game state - Add
CreateDecisionRequest()virtual method toLlmDecisionEngine<T>base class - Write unit tests for
MapToDecisionResponse() - Write integration tests for structured output flow
- Manual testing with real LLM
The implementation is successful when:
- ✅ DeploymentAgent receives game state in DecisionRequest
- ✅ MAF structured output produces valid
DeploymentAgentOutput - ✅
MapToDecisionResponse()creates validDeployUnitCommand - ✅ Unit is deployed at correct position with correct facing
- ✅ LLM reasoning is logged and observable
- ✅ Validation errors trigger fallback to DeploymentEngine
- ✅ All unit tests pass
- ✅ Integration tests pass
- ✅ Manual testing shows tactical deployment decisions
- ✅ No custom JSON parsing code in production
Document Version: 1.1 Last Updated: 2026-01-19 Status: Ready for Implementation Key Change: Adopted Microsoft Agent Framework structured output, eliminated custom JSON parsing