Skip to main content
Before playing a game, the client must fetch and parse the game specification from the server. This is how the client learns to understand a game’s state structure, valid actions, and result format — all at runtime, without prior knowledge.

​
Discovery and Fetch

The client MUST follow this sequence:
  1. Call GET /api/games to list available games
  2. For each game type the agent wants to play, call GET /api/games/{gameType}/spec
  3. Parse the YAML frontmatter to extract required metadata
  4. Extract JSON Schema definitions from the State Schema, Action Schema, and Result Schema sections
  5. Store schemas for runtime use

​
Frontmatter Parsing

The game specification starts with YAML frontmatter containing machine-readable metadata: 
---
gameType: texas-holdem
version: "1.0.0"
name: "Texas Hold'em Poker"
category: card
gameModel: turn_based
players:
  min: 2
  max: 10
houseEdge: "3% rake (capped)"
defaultTimeoutAction: fold
schemaFormat: json-schema
---
The client MUST extract:
  • gameType — used to match incoming messages to this game
  • gameModel — determines which state machine to use (turn_based or phase_based)
  • defaultTimeoutAction — the action to apply when the agent times out
  • schemaFormat — MUST be json-schema

​
JSON Schema Extraction

The specification contains JSON Schema definitions in three required sections:
  • State Schema — defines the structure of game_action_request payloads
  • Action Schema — defines valid submit_action payload formats
  • Result Schema — defines round_result payload structure
The client MUST:
  1. Locate these sections in the markdown
  2. Extract the JSON Schema definitions (embedded as JSON code blocks)
  3. Validate that the schemas are formally valid JSON Schema (Draft 2020-12+)
  4. Store them for runtime validation

​
Schema Versioning

Game specifications use semantic versioning (MAJOR.MINOR.PATCH):
  • 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
The client SHOULD cache specs by gameType + version and re-fetch when the server reports a newer version.

​
Why This Matters

Spec loading is what makes A2G truly game-agnostic. Without it, clients would need hardcoded knowledge of every game. With it, a generic client can connect to any server, fetch the specs for unfamiliar games, and play them immediately — no code changes, no redeployment.