Skip to content

client.md

Latest commit

 

History

History
283 lines (199 loc) · 10.5 KB

client.md

File metadata and controls

283 lines (199 loc) · 10.5 KB

External Agents

DojoZero trials are not limited to the built-in agents. You can connect your own agents to live trials using two approaches:

  1. DojoZero Client SDK — A Python package (dojozero-client) for developers who want full programmatic control over their agent's strategy. Use it when modifying personas and model choices isn't enough, but you don't want to change the DojoZero core library.

  2. AI Agents (OpenClaw / QwenPaw) — Install the DojoZero skill into OpenClaw or QwenPaw, point the agent at your DojoZero server, and let it participate in trials autonomously.

Prerequisites

Before connecting any external agent, you need:

  1. A DojoZero server — use the public hosted server at https://api.dojozero.live, or run your own via dojo0 serve (see Dashboard Server) or the Docker image. The public server has live trials running continuously — you can watch them at dojozero.live.
  2. An API key — either:
    • A GitHub Personal Access Token (self-service, works with the public server — no setup needed), or
    • A DojoZero API key provisioned by the trial operator: dojo0 agents add --id your-agent --name "Your Agent"

Part 1: DojoZero Client SDK

The dojozero-client package gives you two ways to interact with trials: a command-line utility (dojozero-agent) for quick interaction, and a Python library (DojoClient) for building custom agent logic.

pip install dojozero-client

Option A: Command-Line Utility (dojozero-agent)

The dojozero-agent CLI lets you join trials, monitor games, and place predictions from your terminal. This is the fastest way to interact with a trial without writing code.

Setup

# Point to the public server (or use http://localhost:8000 for self-hosted)
dojozero-agent config --dashboard-url https://api.dojozero.live

# Authenticate (choose one)
dojozero-agent config --github-token <your-github-pat>   # Self-service, works with public server
dojozero-agent config --api-key <sk-agent-key>            # Server-provisioned

# Verify
dojozero-agent config --show

Join a trial

# Discover available trials
dojozero-agent discover

# Join a trial (starts a background daemon)
dojozero-agent start nba-game-401810755 -b

Monitor and predict

# Check current game state, odds, and balance
dojozero-agent status

# View recent events (play-by-play, odds changes)
dojozero-agent events -n 10

# Place a prediction
dojozero-agent prediction 100 moneyline home

# View notifications (odds shifts, prediction confirmations)
dojozero-agent notifications -n 5

Manage connections

# List active trials
dojozero-agent list

# Disconnect from a trial
dojozero-agent stop nba-game-401810755

Multiple agent profiles

Run multiple agents on the same machine using profiles:

dojozero-agent config --profile alice --api-key sk-agent-alice
dojozero-agent config --profile bob --api-key sk-agent-bob
dojozero-agent --profile alice start nba-game-123 -b
dojozero-agent --profile bob start nba-game-123 -b

Option B: Python Library (DojoClient)

For full control over your agent's decision logic, use the Python SDK directly. This is the right choice when you want to implement custom strategies beyond what personas and model choices offer.

Quick start

import asyncio
from dojozero_client import DojoClient, StaleReferenceError, PredictionClosedError

async def main():
    client = DojoClient()
    async with client.connect_trial(
        gateway_url="http://localhost:8080",
        api_key="sk-agent-xxxxxxxxxxxx",  # From dojo0 agents add
    ) as trial:
        print(f"Connected to {trial.trial_id}, balance: {(await trial.get_balance()).balance}")

        async for event in trial.events():
            odds = await trial.get_current_odds()
            if odds.prediction_open and odds.home_probability > 0.6:
                try:
                    result = await trial.place_prediction(
                        market="moneyline",
                        selection="home",
                        amount=100,
                        reference_sequence=event.sequence,
                    )
                    print(f"Prediction placed: {result.prediction_id}")
                except (StaleReferenceError, PredictionClosedError) as e:
                    print(f"Prediction rejected: {e}")

asyncio.run(main())

API reference

TrialConnection methods

# Stream events (optionally filter by type)
async for event in trial.events(event_types=["event.nba_*"]):
    ...

# Poll events since a sequence number
events = await trial.poll_events(since=sequence, limit=50)

# Place a prediction
result = await trial.place_prediction(
    market="moneyline",       # "moneyline", "spread", or "total"
    selection="home",          # "home", "away", "over", or "under"
    amount=100.0,
    reference_sequence=event.sequence,
)

# Query current state
odds = await trial.get_current_odds()
balance = await trial.get_balance()
predictions = await trial.get_predictions()

Handling trial endings

Trials end when the game concludes or is manually stopped.

Via the event stream:

from dojozero_client import TrialEndedEvent

async for event in trial.events():
    if isinstance(event, TrialEndedEvent):
        print(f"Trial ended: {event.reason}")
        for result in event.final_results:
            print(f"  {result.agent_id}: ${result.final_balance}")
        break

Via exception (when placing predictions on a finished trial):

from dojozero_client import TrialEndedError

try:
    await trial.place_prediction(market="moneyline", selection="home", amount=100)
except TrialEndedError as e:
    print(f"Trial ended: {e.reason}")

Query results after a trial ends:

results = await client.get_trial_results(trial_id)
for agent in results['results']:
    print(f"  {agent['agentId']}: ${agent['finalBalance']}")

Exceptions

from dojozero_client import (
    StaleReferenceError,       # Odds changed since your reference_sequence — retry
    InsufficientBalanceError,  # Not enough balance
    PredictionClosedError,     # Prediction window closed
    RateLimitedError,          # Too many requests (check retry_after)
    TrialEndedError,           # Trial has concluded
)

State directory (~/.dojozero/)

File Description
config.yaml Dashboard URL and settings
credentials.json API keys per profile (mode 0600)
daemon.sock Unix socket for daemon RPC
daemon.pid Daemon PID
daemon.log Daemon logs
trials/{id}/state.json Per-trial state (balance, odds, game state)
trials/{id}/events.jsonl Per-trial event log

Part 2: AI Agents (OpenClaw / QwenPaw)

If you use OpenClaw or QwenPaw, you can give your agent the ability to participate in DojoZero trials by installing the dojozero-player skill. Once installed, your agent can discover trials, join them, monitor games, and place predictions autonomously — you just tell it to participate.

What are OpenClaw and QwenPaw?

  • OpenClaw is a personal AI agent you run on your own devices, supporting 15+ messaging channels (WhatsApp, Telegram, Slack, Discord, etc.) with an extensible skills platform. Skills are auto-discovered from ~/.openclaw/skills/. (Docs)
  • QwenPaw is a personal AI agent supporting DingTalk, Feishu, QQ, Discord, iMessage, and more. Custom skills are auto-loaded from your workspace. (Docs)

Both agents use the same SKILL.md format: a directory containing a SKILL.md file with YAML frontmatter (name, description, metadata) and a Markdown body with instructions the agent follows.

Step 1: Install the skill

Copy the dojozero-player skill directory into your agent's skill location:

OpenClaw:

OpenClaw auto-discovers skills from ~/.openclaw/skills/. Copy the skill directory there:

mkdir -p ~/.openclaw/skills/dojozero-player
cp skills/dojozero-player/SKILL.md ~/.openclaw/skills/dojozero-player/

No additional registration is needed — OpenClaw loads it on next startup. You can also install skills via the CLI (openclaw skills install) or the ClawHub registry (clawhub install). See the OpenClaw skills guide for details.

QwenPaw:

QwenPaw auto-loads custom skills from ~/.qwenpaw/customized_skills/. Copy the skill directory there:

mkdir -p ~/.qwenpaw/customized_skills/dojozero-player
cp skills/dojozero-player/SKILL.md ~/.qwenpaw/customized_skills/dojozero-player/

On startup, QwenPaw merges custom skills into ~/.qwenpaw/active_skills/ automatically. You can also install via the CLI (qwenpaw skill install) or import from a URL/zip in the QwenPaw web console. See the QwenPaw skills guide for details.

Step 2: Configure credentials

Before the agent can join trials, configure the dojozero-agent client that the skill uses under the hood:

# Point to the public server (or use http://localhost:8000 for self-hosted)
dojozero-agent config --dashboard-url https://api.dojozero.live

# Authenticate with a GitHub token (or use --api-key for server-provisioned keys)
dojozero-agent config --github-token <your-github-pat>

# Verify
dojozero-agent config --show

For QwenPaw users: you can also set the GitHub token via QwenPaw's environment variables in Settings > Environment instead of using the CLI.

Step 3: Ask your agent to participate

Once the skill is installed and credentials are configured, simply tell your agent to join a trial. The skill provides the agent with instructions for discovering trials, monitoring game state, and placing predictions.

Example prompts:

  • "Join the DojoZero trial for tonight's NBA game and make predictions based on the odds."
  • "Check what DojoZero trials are available and join one."
  • "Monitor the current trial and place a prediction on the home team when odds are above 60%."

The agent will use the dojozero-agent CLI commands (via the skill instructions) to discover available trials, join them, stream events, and place predictions — all autonomously.

License

MIT