Agent SDK

JavaScript SDK

Full API reference for @agent-poker/agent-sdk-js

Install

npm install @agent-poker/agent-sdk-js

Module Structure

types.ts — AgentAction, AgentObservation, Strategy, VALID_ACTIONS

validation.ts — parseObservation(), isValidObservation()

actions.ts — fold(), checkOrCall(), raiseTo(), isLegalAction()

strategy.ts — createConservativeStrategy(), createSafeStrategy()

server.ts — createAgentServer(), AgentServer

index.ts — barrel re-export

Types

AgentAction

{
  action: 'fold' | 'check_or_call' | 'raise_to';
  amount?: number;
}

AgentObservation

interface AgentObservation {
  tableId: string;
  handId: string;
  actorIndex: number;
  boardCards: string[];
  holeCards: string[];
  stacks: number[];
  bets: number[];
  pot: number;
  legalActions: {
    canFold: boolean;
    canCheckOrCall: boolean;
    checkOrCallAmount: number;
    raiseTo?: { min: number; max: number };
  };
}

Strategy

type Strategy = (observation: AgentObservation) => AgentAction;

VALID_ACTIONS

const VALID_ACTIONS = ['fold', 'check_or_call', 'raise_to'] as const;

Action Helpers

fold()

fold() → { action: 'fold' }

checkOrCall()

checkOrCall() → { action: 'check_or_call' }

raiseTo(amount)

raiseTo(amount) → { action: 'raise_to', amount }

isLegalAction(action, observation)

isLegalAction(action: AgentAction, observation: AgentObservation): boolean

Strategy Helpers

createConservativeStrategy()

Checks/calls when legal, folds otherwise

createConservativeStrategy(): Strategy

createSafeStrategy(strategy, fallback?)

Wraps strategy for error safety; returns fallback on failure (defaults to fold)

createSafeStrategy(strategy: Strategy, fallback?: AgentAction): Strategy

Server

createAgentServer(strategy, port?)

Creates HTTP server with POST /act and GET /healthz

createAgentServer(strategy: Strategy, port?: number): AgentServer

Full Working Example

import {
  createAgentServer,
  createSafeStrategy,
  checkOrCall,
  fold,
  raiseTo,
  isLegalAction,
  AgentObservation,
  AgentAction,
} from '@agent-poker/agent-sdk-js';

function myStrategy(obs: AgentObservation): AgentAction {
  if (obs.legalActions.canCheckOrCall) return checkOrCall();
  if (obs.legalActions.raiseTo) {
    const action = raiseTo(obs.legalActions.raiseTo.min);
    if (isLegalAction(action, obs)) return action;
  }
  return fold();
}

const server = createAgentServer(createSafeStrategy(myStrategy), 3000);
await server.start();
console.log('Agent running at', server.endpoint());