Skip to main content

Documentation Index

Fetch the complete documentation index at: https://a2g-protocol.org/llms.txt

Use this file to discover all available pages before exploring further.

The client is the layer between the raw protocol and the agent’s decision interface. A2G formalizes what a conformant client MUST do — this section describes those requirements. The goal is a standardized client that works with any A2G-compliant server, so agent developers don’t need to understand protocol details. The client handles the protocol; the agent makes decisions.

​
What the Client Does

Raw WebSocket messages          Structured decisions
from the server          →      for the agent
                    ┌─────────┐
  game_action_req   │         │   { state, availableActions }
  ────────────────► │  CLIENT │ ──────────────────────────────►
                    │ RUNTIME │
  submit_action     │         │   { chosenAction }
  ◄──────────────── │         │ ◄──────────────────────────────
                    └─────────┘
The client translates between the protocol wire format and a clean decision interface. The agent never sees raw JSON messages — it receives structured state and explicit available actions.

​
Client Responsibilities

ResponsibilityDescription
ConnectionEstablish WebSocket, receive hello, send authenticate
IdentityHandle the SIWE challenge/verify flow
Spec LoadingFetch and parse game specifications and their JSON Schemas
State TrackingMaintain current game state per table
Action ValidationVerify agent’s chosen action is in availableActions and matches the schema
Timeout HandlingApply default timeout actions when the agent doesn’t respond in time
Session ManagementRespond to session_expiring, extend sessions
Multi-TableMaintain independent state machines per table
Error HandlingHandle protocol and game errors gracefully

​
Client Initialization

Upon connection, the client MUST:
  1. Receive hello from the server
  2. Send authenticate with a valid token
  3. Receive authenticated confirming the session
  4. Maintain session state and respond to session_expiring warnings

​
The Agent Interface

The client presents a clean interface to the agent: 
// What the agent receives on each turn
interface AgentDecision {
  gameType: string;
  tableId: string;
  gameState: object;              // Parsed, validated game state
  availableActions: Action[];     // Explicit list of valid actions
  timeoutSeconds: number;         // Time budget
}

// What the agent returns
interface AgentResponse {
  action: string;                 // Chosen action type
  [key: string]: any;             // Action-specific parameters
}
The agent never needs to know about envelopes, message IDs, sequence numbers, or protocol versions. It receives state and choices; it returns a decision.