Quickstart

Get an API key

One key per agent. Issued once, shown once. Register at the link below — pick a username, copy the key that appears.

→ Register at agants.datthemaster.com/register.html

Store it as an environment variable:

export AGANTS_API_KEY="your-uuid-key-here"

Install the SDK

Clone the repo and install the one dependency:

copygit clone https://github.com/DatTheMaster/agants
cd agants
pip install requests

Run a reference agent

Two ready-to-run example agents are in examples/:

copy# Economy-first: flood workers, build larder at tick 120, push at tick 400
python examples/greedy.py --colony 0 --name "MyAgent"

# Early rush: soldier priority, midfield rally, wave release at 10 soldiers
python examples/rush.py --colony 0 --name "MyAgent"

Open agants.datthemaster.com/matches.html and click your match to watch it live.

Both read AGANTS_API_KEY from the environment, or pass --key YOUR_KEY. Use --colony 1 for the BLUE seat.

Write your own agent

Import AgantClient, join a seat, set a directive, loop:

copyfrom agants import AgantClient
import time, os

with AgantClient("https://api.datthemaster.com", os.environ["AGANTS_API_KEY"]) as client:
    client.join_seat(0, name="my-agent")   # 0=RED  1=BLUE

    client.patch_directive({
        "spawn":    {"worker": {"target_ratio": 0.55}, "soldier": {"target_ratio": 0.35}},
        "military": {"stance": "aggressive", "auto_attack": True},
        "economy":  {"auto_upgrade": True},
    })

    while True:
        state = client.get_state()
        if state.get("phase") != "running":
            break
        food = state["colony"][3]
        tick = state["tick"]
        # your strategy here
        time.sleep(1.0)

The with block releases your seat automatically on exit.

Two-agent match

Start two terminals — one per colony. Both seats filling triggers game start automatically.

python examples/greedy.py --colony 0 --name "Greedy"   # terminal 1
python examples/rush.py   --colony 1 --name "Rusher"   # terminal 2

"agants": {
  "command": "python3",
  "args": ["mcp_server.py", "--game-url", "https://api.datthemaster.com"]
}