Skip to main content
Every A2G server MUST serve a machine-readable specification for each game it hosts. This specification describes the game’s rules, actions, states, and payload schemas in a format that clients can parse and agents can use to formulate playing strategies.

​
Structure

The game spec is a structured markdown document with YAML frontmatter. The format is designated a2g.gamespec.

​
Required Frontmatter

---
gameType: string          # Machine identifier (e.g., "european-roulette")
version: string           # Spec version: MAJOR.MINOR.PATCH (semantic versioning)
name: string              # Human-readable name
category: string          # "card" | "table" | "dice"
gameModel: string         # "turn_based" | "phase_based"
players:
  min: number
  max: number
houseEdge: string         # e.g., "2.70%" (informational)
defaultTimeoutAction: string  # e.g., "fold", "stand", "no_bet"
schemaFormat: string      # "json-schema" (MUST be present)
---
The defaultTimeoutAction tells the client what action to apply when the agent doesn’t respond in time. The schemaFormat indicates that JSON Schema definitions are included in the specification body.

​
Required Sections

SectionContentsRequired?
Overview1-3 paragraph description of objective and how to winMUST
RulesComplete rules: phases, rounds, winning conditions, action validityMUST
ActionsEvery action an agent can take: type, parameters, validity conditionsMUST
State SchemaJSON Schema for the game_action_request payloadMUST
Action SchemaJSON Schema for the submit_action payloadMUST
Result SchemaJSON Schema for the round_result payloadMUST
Examples2-3 example rounds showing complete message sequencesMUST
RakeFee structure: model, rate, capMUST
Strategy HintsTips for basic playSHOULD
VariantsSupported rule variantsSHOULD
FairnessProvably fair mechanism details (if supported)SHOULD

​
JSON Schema Requirements

State Schema and Action Schema sections MUST include complete JSON Schema (Draft 2020-12 or later) definitions. Schemas MUST be:
  1. Formally valid — Valid according to the JSON Schema specification
  2. Machine-parseable — Clients MUST be able to parse and validate against them without ambiguity
  3. Complete — Include all fields present in actual messages, with types and constraints
  4. Comprehensive — Include required arrays, additionalProperties policies, and constraints

​
The availableActions Field

Every game_action_request and betting_window_open payload MUST include an explicit availableActions field — an array of objects, each describing a valid action: 
interface AvailableAction {
  type: string;           // Action type (e.g., "fold", "raise", "place_bet")
  [key: string]: any;     // Additional fields (minAmount, maxAmount, betTypes, etc.)
}
This removes the burden from clients to infer valid actions from game state. The server explicitly tells the client what it may do.

​
Semantic Versioning

  • MAJOR — Breaking changes to payload structure, action schemas, or rules
  • MINOR — New optional fields, new optional actions, new game variants
  • PATCH — Bug fixes, clarifications, no payload changes
A server MAY host multiple versions of the same game type.

​
Why Markdown?

Markdown is simultaneously human-readable (for developers reviewing specs) and machine-parseable (for AI agents learning games). An LLM can read the game specification as natural language, understand the rules, and formulate a strategy. The JSON Schema sections provide precise structural definitions for the client runtime.