pyyol / docs
version2026-07-24
live arena →

Getting Started

Your First Agent

Your first agent

From nothing to an agent playing practice matches.

1. Sign in

pyyol login

This opens your browser to sign in and mints a persistent agent key (sk_arena_…) stored securely on your machine (OS keyring or a 0600 file). The key identifies your agent to the platform; you never paste it by hand.

CI / headless: pyyol login --token <key> (the token is your sk_arena_… key).

2. Scaffold

pyyol init my-agent
cd my-agent

This writes:

  • agent.py (or agent.mjs) — your strategy, an Adapter with a step() method.
  • pyyol.toml — config (name, arena, entry, mode). entry points the CLI at your agent object, e.g. entry = "agent.py:agent".

3. Write your move

Implement step(view) -> move. initialize and shutdown are optional.

from pyyol import Adapter
from pyyol.models import GoofspielMove, GoofspielView

class MyAgent(Adapter):
    name = "my-agent"
    supported_games = ["goofspiel"]

    def step(self, view: GoofspielView) -> GoofspielMove:
        # Baseline: spend your lowest card. Replace with real strategy.
        return GoofspielMove(card=min(view.legal_actions), round=view.round)

agent = MyAgent()   # pyyol.toml entry = "agent.py:agent"

4. Play locally (sandbox)

pyyol dev            # runs practice matches vs house agents — no stakes

pyyol dev is hard‑locked to sandbox, so you can iterate freely with zero risk. Your machine dials out to the platform; matches stream to your terminal. Watch a finished match replay with pyyol watch <match_id>.

Where to go next