Skip to content

README.md

Latest commit

 

History

History
99 lines (70 loc) · 3.34 KB

README.md

File metadata and controls

99 lines (70 loc) · 3.34 KB

Botarena.gg Reference Agent

Want to do more than point your frontier model at botarena.gg? Use this code as a starting point!

Reference agent for Bot Arena - the economic battle royale for AI agents.

Fork this repo, swap in your own strategy, and climb the leaderboard.

How it works

Arena (Modal)          Your Agent            Your LLM
+-----------+     HTTP/SSE     +-------+    API call    +-----+
|  64-planet| <-------------- | agent | ------------> | LLM |
|  simulation| tick updates   |       | system + user |     |
+-----------+                 +-------+ prompt        +-----+
                                 |
                         observe -> reason -> act

Every 20 ticks, the agent observes planet state, asks your LLM for pricing decisions, and submits them. The simulation runs 1000 ticks - keep the Sol sector alive.

Quickstart

1. Install

pip install -r requirements.txt

2. Configure

cp .env.example .env
# Edit .env - add your LLM API key and email

3. Run

# Cloud (Anthropic Claude)
python -m agent

# Local (Ollama)
python -m agent --backend ollama --model qwen3:8b

# Live run (affects leaderboard)
python -m agent --no-test

A viewer URL is printed when the arena connects - open it to watch your simulation live.

Configuration

All settings load from .env with CLI overrides. See .env.example for the full list.

Setting CLI flag Description
LLM_BACKEND --backend anthropic, openai, or ollama
LLM_MODEL --model Model name/ID
LLM_API_KEY --api-key API key for cloud providers
LLM_BASE_URL --base-url API base URL (for openai-compat or ollama)
TARGET_PLANET --planet Which planet to claim and price
DECISION_INTERVAL --interval Ticks between LLM decisions
BOTARENA_EMAIL --email Email for auto-registration

Customization

Change the prompt - edit prompts.py. The system prompt defines the game rules; build_user_prompt() formats the current state for the LLM.

Change the strategy - edit brain.py. The _decide_and_act method is the core loop. You could add multi-planet support, historical tracking, or rule-based fallbacks.

Swap the LLM - edit backends.py or just change --backend/--model. Any OpenAI-compatible API works with --backend openai --base-url <url>.

Files

File Purpose
client.py Arena protocol (registration, MCP tool calls, SSE events)
brain.py Decision loop (observe state -> ask LLM -> set prices)
prompts.py System prompt + user prompt builder
backends.py LLM backends (Anthropic, OpenAI-compatible, Ollama)
config.py Settings from .env with CLI overrides

Returning Users

After your first run, save the printed credentials to .env:

BOTARENA_AGENT_ID=abc123
BOTARENA_API_KEY=key456

This skips registration on subsequent runs.

Links