# Add game bots to a lobby with an agent

> An AI agent can seat a game's bots in a DiceyTable lobby, set how hard they play, and check whether your device can host an AI bot before you press Start.

- Question: How does an agent add bots to a game lobby?
- Source: https://diceytable.com/docs/ai-agents/workflows/lobby-bots
- Last verified: 2026-10-09

An agent adds a bot by calling `lobby_bot_add` with one of the game's bots and a difficulty. The bot takes a player seat, and the agent can change its difficulty or remove it until the game starts.

A **game bot** is an opponent the game's author built into the game. Some bots follow a script. Others think with an AI model that runs on the host's device, and the host is the lobby owner. Players see what that's like on [Play board games against the computer](https://diceytable.com/features/play-against-bots).

## What you'll need

- A paired tab in a `/play` lobby, as [Set up a multiplayer lobby with an agent](https://diceytable.com/docs/ai-agents/workflows/lobby) shows.
- You must be the lobby owner. Only the owner adds, changes or removes bots.
- A game that offers bots. Not every game does.

## Step 1: See which bots the game offers

The agent calls `lobby_state`. The game's bots are listed under `game.bots`. Each one has a `kind`, either `scripted` or `ai`. An AI bot also has a `minTier`, the least the host's device must manage to run it:

- `cpu-basic`: any modern device.
- `cpu-fast`: a fast processor.
- `gpu`: a graphics card.

Some games have variants, and not every variant seats every bot. `game.variants` says which bots each variant seats, under `seatsBots`. If the lobby's variant can't seat a bot, adding it fails with `bot-variant-no-handler`. Pick a variant that seats it first with `lobby_set_variant`. Switching to a variant that can't seat a bot removes that bot.

## Can my computer run an AI bot?

`hardware_tier_get` says what tier this device measured as, and the facts behind it. It only reads the saved result. It never downloads or runs anything.

The lobby runs the test on its own when bots are involved. On the owner's device, that happens when the game offers bots. On everyone else's, it happens once a bot is seated. The first test downloads about 14 MB, or about 41 MB when the browser can use the graphics card.

To test again, the agent presses the lobby's **Re-test** button with `actions_invoke` and the id `lobby.bots.retest-device`. That counts as a write, because it runs a test on your machine.

A tier is advice from your own device. It decides whether the owner may press Start with an AI bot seated. It also helps choose who hosts next if the host leaves. It never stops anyone from joining.

## Step 2: Seat the bot

1. The agent calls [`lobby_bot_add`](https://diceytable.com/docs/ai-agents/reference/tools/lobby#lobbybotadd) with a `botId` from `game.bots`. It can add a `difficultyId`, or the bot's default is used.
2. Bots and players share the game's seats. A full table has no room for a bot.
3. `lobby_state` now lists the bot under `bots`, with its `peerId`. The next two tools take that id.

| Tool | What it does |
|---|---|
| `lobby_bot_set_difficulty` | Changes how hard a seated bot plays |
| `lobby_bot_set_deck` | Gives a seated bot one of the game's own decks, or hands the choice back to the game |
| `lobby_bot_remove` | Removes a seated bot. No person is removed, so it needs no confirmation |

### Choose the bot's deck

Some card games ship their own decks. In an unranked game, the owner can pick which one a bot plays. The agent lists them with `lobby_requirement_options` and `pool: "game"`, then calls `lobby_bot_set_deck` with the bot's `peerId` and a deck's `id`. Passing `deckId: null` lets the game choose again.

A game played side against side can forbid two decks on the same side. `lobby_state` shows that rule as `distinctBy` on the deck requirement. A deck that would clash is refused with `bot-deck-pairing`. In ranked play the game always chooses its bots' decks, so the tool is refused with `bot-deck-ranked`.

## Step 3: Start the game

When the owner's agent calls `lobby_start`, the bots can hold it up. Start then returns `botRefusal` with one of two reasons:

- `bot-tier-unmet`: your device is below what a seated AI bot needs.
- `bot-seats-exceed-players`: players plus bots are more than the seats.

`lobby_state` warns about both ahead of time, under `startBlockedBy`.

Once the game is running, the host's agent can still manage bots at the table. `table_bots_list` shows each bot's seat, difficulty, and whether it's playing or paused. `table_bots_set` adds or changes one, and `table_bots_remove` takes one out with `confirm: true`.

## Bots and hidden cards

> **⚠ A game's bots can see hidden cards.** The host's device holds the whole table, and the bots run there. So whenever a game can hide anything, its bots can see it. The lobby says so beside the bots. `lobby_state` also reports the game's own declaration as `game.botsCanSeeHiddenInformation`.

Your agent doesn't get the same view. It still sees only what your seat may see. [Hidden cards and AI agents](https://diceytable.com/docs/ai-agents/concepts/hidden-information) explains the difference.

## Next steps

- [Game bots for mod authors](https://diceytable.com/docs/mods/concepts/bots): how a game declares its bots and models.
- [Test multiplayer with two agents](https://diceytable.com/docs/ai-agents/workflows/multiplayer-testing): add a second human seat instead.
- [Train an AI to play your board game](https://diceytable.com/features/train-game-ai): build a bot of your own.