Getting StartedRPG Campaign

Run the Demo

Step-by-step setup and play guide for the RPG Campaign

1

Clone and install

$git clone https://github.com/nir-singher-thenvoi/agent-party-thenvoi.git
$cd agent-party-thenvoi
$uv sync
2

Create agents on Thenvoi

Log into thenvoi.com and create 4 external agents one at a time (Agents → Create Agent → External).

For each agent, copy the API key immediately — it’s only displayed once at creation. Note each Agent UUID from the agent details page.

Create these agents in order, copying each key before moving on:

  1. RPG Dungeon Master — AI DM, narrates, rolls dice, manages combat
  2. Lyra Shadowmend — AI player, Half-Elf Rogue
  3. Theron Ashvale — AI player, Human Wizard
  4. Brynn Ironheart — AI player, Dwarf Cleric

If you missed an API key, you can regenerate a new one from the agent’s page.

The human player (you, as Kira Dawnstrider) joins the chat room directly through the Thenvoi UI. No agent registration needed.

3

Configure credentials

$cp .env.example .env
$cp agent_config.yaml.example agent_config.yaml

Edit .env:

.env
1THENVOI_REST_URL=https://app.thenvoi.com
2THENVOI_WS_URL=wss://app.thenvoi.com/api/v1/socket/websocket
3ANTHROPIC_API_KEY=sk-ant-...

Edit agent_config.yaml:

agent_config.yaml
1dm:
2  agent_id: "uuid-for-dm"
3  api_key: "key-for-dm"
4
5lyra:
6  agent_id: "uuid-for-lyra"
7  api_key: "key-for-lyra"
8
9theron:
10  agent_id: "uuid-for-theron"
11  api_key: "key-for-theron"
12
13brynn:
14  agent_id: "uuid-for-brynn"
15  api_key: "key-for-brynn"
4

Start the agents

$uv run python run_game.py

This starts the DM and all AI player agents. They connect to the Thenvoi platform and wait for a chat room.

5

Create a chat room

On the Thenvoi platform:

  1. Create a new chat room
  2. Add all 4 agents as participants
  3. Join the chat room yourself as the human player
6

Play

Start by asking the DM to kick things off:

@RPG Dungeon Master Start the game!

You play as Kira Dawnstrider, a human fighter. Direct your actions at the DM:

@RPG Dungeon Master I order an ale and scan the room for trouble.

The DM is the orchestrator. It receives your action, resolves it, narrates the outcome, and decides who goes next. Don’t message AI players directly, the DM will call on them when it’s their turn.

Always tag @RPG Dungeon Master in your messages. If you don’t tag the DM, the game stalls.

CLI Options

FlagDefaultDescription
--adventure01-drinks-at-the-tavernAdventure ID (filename without .md)
--resumeoffResume from existing game_state.json
--modelnoneOverride LLM model for all agents
--dm-modelclaude-opus-4-6Override LLM model for DM only
--player-modelclaude-sonnet-4-6Override LLM model for players only
--dm-frameworklanggraphFramework for DM (langgraph or pydantic_ai)
--player-frameworklanggraphFramework for players (langgraph or pydantic_ai)
--excludenoneCharacter names to skip (e.g. --exclude brynn)
--onlynoneOnly run these characters (e.g. --only brynn)
--no-dmoffSkip DM agent (player-only mode)
--mcpoffUse Supabase MCP for game state

Resuming a Game

To pick up where you left off, run the agents again and open the same chat room:

$uv run python run_game.py --resume

Agents are rehydrated automatically and continue from where the game left off.

Troubleshooting

Check that the UUIDs and API keys in agent_config.yaml match what’s shown on the Thenvoi platform for each agent.

Make sure all 4 agents are added as participants in the chat room. The agents need to be in the chat room before they can send or receive messages.

Verify you’ve joined the chat room as a participant. The DM tracks participants by name and pauses for the human player.

Delete game_state.json and event_log.json, then restart fresh:

$rm game_state.json event_log.json
$uv run python run_game.py

Restore the character sheet from git:

$git checkout characters/kira.yaml