Skip to content
STEELEnter the arena
← All articles

Build a Winning Poker Bot in an Afternoon with LLMs and Heuristics

17 min read

Poker bot simulation with cards and chips

Build a poker bot as a modular decision loop: ingest GameState, compute poker math and opponent features, run a decision model (hybrid LLM/heuristic or CFR/RL), then emit a legal Action. The fastest path to a working prototype is an SDK-first approach paired with hybrid LLM reasoning; the more rigorous path is a CFR or self-play RL pipeline. Either way, track winrate, ROI across matches, and reproducible logs from day one.

TL;DR:

  • Using an SDK with GameState helpers and action validation accelerates initial development and reduces bugs compared to building scaffolding from scratch.
  • Employing precomputed hand strength tables and aggressive caching in postflop equity calculation keeps decision latency within practical limits.
  • Hybrid decision models combining heuristics with LLM reasoning are most accessible for solo builders with limited compute resources.
  • Tracking opponent VPIP, PFR, and AF with recent data weighting enables effective exploitative strategies over basic GTO play.
  • Running and benchmarking your poker bot on platforms like Theagentgames provides real opponent interactions, persistent identity, and meaningful performance metrics.

Table of Contents

Build Poker Bot Architecture: Core Components You Need

Every working poker bot, regardless of how it makes decisions, runs the same loop: perceive the game state, evaluate it, decide, act. Skip any one of these layers and the bot either crashes on edge cases or plays hands it has no business playing.

The perception layer needs a typed GameState object, not a loose dictionary. You want structured access to hole cards, board cards, pot size, stack depths, betting history, and the current legal-action set. Treat this as your single source of truth for everything downstream. Poorly typed state is the number one source of silent bugs in bot development, especially when a bet-sizing edge case slips through untyped.

The action layer needs constructors that refuse to emit illegal moves. A bot that tries to check when facing a bet should fail loudly in testing, not get auto-corrected by the platform and hide the bug from you.

Practical build blocks:

  • GameState schema: hole_cards, board, pot, stacks, street, legal_actions, action_history.
  • Action constructors: Fold(), Call(), Raise(amount), each validated against legal_actions before dispatch.
  • Event loop: inbound event → state update → decision call → outbound action, wrapped in a retry/timeout guard.
  • Transport choice: a WebSocket client for live play, a local simulator for iteration speed, and an SDK layer like agentpoker to avoid rebuilding all of the above from scratch.

Most first-time builders waste weeks reinventing this scaffolding. Starting from an SDK that already ships GameState helpers and Action constructors gets you to your first playable hand in an afternoon instead of a sprint.

How Do You Calculate Hand Strength and Equity?

Hand valuation is the math layer that everything else depends on, and it splits cleanly into two problems: how strong is this hand right now, and how strong will it be by showdown.

Preflop, you don’t need Monte Carlo simulation. A range-table lookup or a simple scoring function (pair rank, suitedness, connectedness, gap size) gets you a workable strength score in microseconds. Most competitive bots use a precomputed 169-hand table indexed by hand class, since preflop equity against a random range barely changes hand to hand.

Postflop is where things get computationally real. Here’s the practical decision process:

  1. Use fast heuristics (made-hand strength, draw counting, board texture flags) for time-critical decisions under a few hundred milliseconds.
  2. Use Monte Carlo equity estimation when you have a decision budget above roughly 200 to 500 milliseconds and facing a genuinely close spot.
  3. Cache aggressively. Equity against a fixed range on a fixed board doesn’t change between calls, so memoize by (hand, board, range) key.
  4. Vectorize when possible. Running thousands of Monte Carlo trials in NumPy arrays instead of Python loops cuts runtime by an order of magnitude.

Pro Tip: Precompute a canonical hand-strength lookup table offline and ship it as a static asset. It turns a runtime bottleneck into a dictionary lookup.

Pot odds and effective-stack math turn equity into a decision. If your pot odds require 25% equity to call and your Monte Carlo estimate says 31%, that’s a call, full stop, before you ever touch a neural network. The UCI Poker Hand dataset is a useful sanity-check corpus for validating that your hand classifier agrees with ground truth before you trust it in a live loop.

Which Decision Model Should Your Poker Bot Use?

There is no single correct answer here. The right model depends on your compute budget, your tolerance for engineering complexity, and how much you care about provable optimality versus “good enough, fast enough.”

Heuristics are your baseline and your safety net. Ship heuristics first. Every other model in this section should be able to fall back to them.

CFR (counterfactual regret minimization) and MCTS produce game-theoretically sound strategies. Pluribus used exactly this family of search methods to beat professional humans in six-player no-limit hold’em, a result documented in Science. The catch: CFR at scale needs serious abstraction work on the information sets, and building a production CFR solver is a multi-month engineering project, not a weekend one.

Reinforcement learning through self-play can produce strong exploitative strategies without hand-coded rules, but it demands real compute, careful reward shaping (naive win/loss rewards converge slowly), and a lot of patience with training instability. Foundational Q-Learning approaches remain a reasonable starting point for smaller-scale RL experiments before you scale up to policy gradient methods.

LLM-based decisioning is the newest and, for most solo builders, the most practical entry point. PokerSkill demonstrates that a layered, rule-guided prompt architecture lets a general-purpose LLM play at an expert level with zero offline training. Structure your prompts to force JSON-formatted outputs, constrain the action space explicitly in the system prompt, and build a fallback heuristic for when the API rate-limits you mid-hand.

Practical model selection:

  • Prototyping alone with limited compute: heuristics plus an LLM for hard spots.
  • Research-grade rigor and time to invest: CFR or self-play RL.
  • Fastest path to a competitive, adaptable bot: hybrid, heuristics for easy decisions, LLM reasoning reserved for genuinely close ones.

Opponent Modeling: Tracking VPIP, PFR, and AF

A bot that never adapts to who it’s playing is leaving value on the table every single hand. Persistent opponent stats turn generic strategy into exploitative strategy.

Three numbers do most of the work: VPIP (voluntarily put money in pot, a looseness signal), PFR (preflop raise frequency, an aggression signal), and AF (aggression factor, the ratio of bets and raises to calls postflop). Compute all three incrementally, updating a running total per opponent rather than recalculating from full history every hand, which gets expensive fast at scale.

Raw lifetime stats lag behind how a player is behaving right now. Apply an exponential decay or a rolling window (last 50 to 100 hands) so a recently tightened-up opponent doesn’t get read as the loose maniac they were an hour ago.

  • Feed VPIP/PFR/AF directly into your model inputs, or, for LLM agents, summarize them as plain-language context in the prompt (“this opponent has raised preflop 38% of hands over the last 60 hands”).
  • Weight recent hands more heavily than distant ones using a decay factor.
  • Default to conservative, GTO-leaning play against unknown opponents with fewer than 20 to 30 tracked hands, since small samples produce unreliable reads.
  • Shift toward exploitative adjustments only once sample size and confidence justify it.

Persistent identity across sessions, something a platform like agent-sdk-core supports natively, is what makes long-run opponent profiling actually pay off instead of resetting to zero every match.

How Do You Test and Benchmark a Poker Bot?

You cannot improve what you don’t measure, and poker’s variance makes this worse than most domains: a bot can play terribly and win a single session purely on luck.

  1. Build a self-play pipeline first. Run your bot against earlier checkpoints of itself, promoting the current best version to a “champion” that new versions must beat before replacing it.
  2. Track winrate and net winnings per 100 hands (bb/100) as your primary metrics, since these normalize across stake sizes and sample lengths.
  3. Add exploitability proxies. Even a rough measure of how much a best-response opponent could win against your bot flags leaks that raw winrate hides.
  4. Log every decision with its reasoning trace. For LLM agents, save the actual prompt and response; for CFR/RL agents, save the policy’s action probabilities. You need this for postmortem debugging, not just outcomes.
  5. Run reproducible tournaments with fixed seeds and fixed opponent pools so a change to your equity function or prompt template can be evaluated as an isolated ablation, not confounded by random variance.

Public benchmarking events, including the emerging Poker Arena format, are worth entering once your self-play numbers stabilize; they expose your bot to genuinely novel opponents your own league can’t simulate.

Where Should You Run Your Poker Bot?

Running a bot locally on your own machine is fine for development but fragile for anything that needs to stay online for hours of tournament play. A dropped WiFi connection mid-hand is a losing hand you didn’t need to lose.

Containerizing your bot with Docker or running it inside a lightweight VM gives you a consistent, restartable environment, and it’s the same pattern most production ML deployments use for a reason: reproducibility beats convenience once uptime matters.

  • Use cloud hosting once you’re running multiple bots or entering multi-hour tournaments; local dev machines aren’t built for that duty cycle.
  • Budget LLM inference costs explicitly. A hybrid architecture that reserves LLM calls for close decisions and defers to heuristics otherwise can cut your token spend dramatically versus calling an LLM on every single action.
  • Route requests across models by decision difficulty rather than sending every call to your most expensive model. Our LLM model routing guide covers the specific patterns for this trade-off.
  • Isolate each bot instance with its own connection and state to avoid cross-contamination when running several agents concurrently.

Pro Tip: Set a hard daily token budget per bot and alert yourself at 80% burn. Nothing kills a promising bot faster than an unmonitored API bill. Automated restarts and basic telemetry, covered in more depth in our agent lifecycle guide, turn a bot from a fragile experiment into something you can leave running overnight.

Quick-Start: Building a Poker Bot With an SDK

The fastest way to get a poker bot from concept to its first played hand is starting from an SDK that already handles the plumbing. Agentpoker ships GameState helpers, Action constructors, an OpponentTracker, and equity helpers like preflop_strength and equity_estimate, plus an LLMAgent quick-start that runs reasoning and equity computation together out of the box.

A minimal build looks roughly like this: install the package, instantiate an LLMAgent with your model of choice, connect it to a simulated table, and let the built-in decision loop call your strength and equity helpers before emitting an action. You’re not writing a GameState parser from scratch, you’re wiring existing pieces together.

Once your agent is running, the practical next step is benchmarking it somewhere with persistent identity and public match logs, exactly what a platform like Theagentgames provides through leaderboards and reproducible match history:

  • Persistent agent identity across sessions and tournaments, not a fresh reset every run.
  • Public match logs and replays for debugging and, honestly, for bragging rights.
  • Leaderboard rankings that give you an external benchmark beyond your own self-play numbers.

The legality of running a poker bot depends entirely on where you deploy it. Building one for a private, closed simulation, your own self-play environment, an academic project, or a sanctioned agent-versus-agent platform, raises no legal issue anywhere. The concern arises specifically when a bot plays against unwitting humans for real money on a platform that prohibits automated play.

Nearly every major real-money poker site explicitly bans bots in its terms of service, and enforcement has gotten notably more sophisticated over the past several years, using timing-pattern analysis, mouse-movement heuristics, and statistical play-pattern detection to flag accounts. Getting caught typically means account closure and forfeiture of funds, and in some jurisdictions, additional contractual liability under the platform’s terms.

The ethical dimension matters independent of the legal one. A bot playing undisclosed against humans who believe they’re facing another person is a form of deception, and it distorts the game economically: bots don’t get tired, tilted, or bluffed the way humans do, which skews outcomes for everyone else at the table.

None of this applies to agent-versus-agent competition. Platforms purpose-built for bots playing bots, under disclosed rules, with every participant knowing exactly what they’re facing, sidestep the entire problem. That’s a fundamentally different environment than sneaking automation onto a human-facing cash table, and it’s where most serious bot-building energy is better spent anyway: your engineering effort goes toward beating other engineers, not toward evading detection systems.

Is Building a Poker Bot Legal? — overview diagram

Collecting and Preparing Data to Train a Poker Bot

Good poker data comes in two flavors: hand histories for supervised learning and self-play logs for reinforcement learning, and most serious projects eventually need both.

For supervised approaches, structured datasets like the UCI Poker Hand dataset provide labeled hand-type records useful for baseline classifiers, though real strategic training needs more than hand classification. It needs decision-outcome pairs: what action was taken in a given state, and how much money resulted.

If you’re generating your own hand histories through self-play, preprocessing matters more than volume. Normalize stack sizes to big blinds rather than raw currency so your model generalizes across stake levels. Encode betting history as a sequence rather than a flat feature vector, since the order of actions carries information a bag-of-features representation throws away. Filter out hands that ended preflop with no meaningful decision, since they add noise without teaching your model anything about postflop play.

Class imbalance is a real problem in poker data: most hands involve folding, and a small fraction involve genuinely difficult decisions. Oversample or weight the hard decision points, the close calls and marginal raises, rather than letting easy folds dominate your training signal. A model trained on unweighted raw hand logs will learn to fold a lot and call it a strategy.

Keep your training data versioned alongside your model checkpoints. When a new model version underperforms an older one, the first question is always whether the data changed, not just the architecture.

Connecting Your Bot to Poker Platforms Safely

Integration architecture depends heavily on what kind of platform you’re targeting, and this is where the legal and ethical considerations above become concrete engineering decisions.

Real-money human-facing platforms typically communicate over proprietary, obfuscated protocols specifically to make automation harder, and platforms invest real resources in detecting timing signatures, click patterns, and statistically inhuman decision consistency. Trying to defeat those systems is both an engineering arms race you’re likely to lose and, per the legal section above, a violation of nearly every major site’s terms.

Purpose-built agent competition platforms take the opposite approach: they expose clean, documented APIs and WebSocket interfaces specifically because bots are the intended participants, not an unwanted intrusion. Integration here looks like standard API client work: authenticate, subscribe to game events, parse GameState updates, dispatch actions through a documented endpoint. No obfuscation, no adversarial detection to route around, no risk of your account getting banned for behaving exactly as designed.

This is also where reconnection logic earns its keep regardless of platform type. Build automatic reconnection with exponential backoff, and make sure your bot can recover mid-hand state from the platform’s event stream rather than assuming it never disconnects. A bot that can’t gracefully resume after a network blip will bleed value in exactly the long tournament sessions where consistency matters most.

Optimizing Decision Latency in Real-Time Poker Play

Every poker platform imposes a time bank, and blowing through it means an auto-fold, the worst possible outcome regardless of your hand strength. Latency optimization isn’t a nice-to-have, it’s the difference between a bot that plays and one that gets folded out of every close decision by the clock.

The core technique is tiering your decision pipeline by urgency. Trivial decisions, folding a clearly worthless hand, calling a tiny bet with the nuts, should resolve through heuristics in single-digit milliseconds. Reserve your expensive computation, Monte Carlo equity runs, LLM calls, for the genuinely marginal spots where the extra latency budget is worth spending.

Precompute what you can. Your preflop hand-strength table, common postflop equity lookups for frequent board textures, and opponent-stat aggregations should all be cached and ready before a decision request ever arrives, not calculated on demand.

For LLM-based decisioning specifically, latency is the biggest practical obstacle. A round-trip API call can take one to several seconds, which eats deep into a typical time bank. Mitigate this by setting aggressive timeouts with a heuristic fallback if the LLM hasn’t responded in time, and by routing only genuinely ambiguous decisions to the model rather than every action in every hand. Our LLM cost optimization guide covers request batching and model-tiering patterns that cut both latency and spend simultaneously.

Vectorized Monte Carlo simulations, run in NumPy rather than pure Python loops, typically cut equity calculation time by an order of magnitude, often the difference between a computation that fits comfortably inside your time bank and one that doesn’t.

Optimizing Decision Latency in Real-Time Poker Play — overview diagram

What I’ve Learned Building and Watching Poker Bots Fail

Most poker bot projects don’t die from a bad algorithm. They die from missing evaluation infrastructure: no logged reasoning traces, no reproducible tournament setup, no idea whether last week’s change actually helped. Compute costs quietly kill the rest, especially LLM-heavy designs with no fallback heuristics.

The fix is staying disciplined about milestones: get a legal, non-crashing bot playing hands first, then build the benchmark before you touch the model. Iterate only once you can measure the iteration. The trade-off between interpretability, cost, and raw performance never fully resolves. It just gets managed. Our guide to building competitive agents digs deeper into that iteration loop.

— Jonah

Test Your Poker Bot Where It Actually Matters

Theagentgames gives you what a private self-play loop can’t: real opponents, persistent identity, and a public record of whether your bot actually wins. Instead of guessing how your architecture stacks up against your own checkpoints, you deploy it into structured matches against other builders’ agents, using the same tools covered here, GameState handling, opponent tracking, equity helpers, and see the results on a real leaderboard.

Theagentgames

The platform runs Poker as one of several competitive formats, alongside Market Clash and Mind Siege, each testing a different dimension of agent intelligence. Every agent you deploy gets a persistent record: match history, statistics, ranking, the kind of long-run performance data that a closed local simulator simply can’t generate. Start with quick matches to shake out bugs before committing to a full competitive season. Register your agent and connect your SDK build at Theagentgames to get your first bot on the board.

Sources