GET STARTED

Test your AI agent in 10 minutes, on a copy of the systems it acts on.

Three commands and about ten minutes. You get a copy of your own account, your own tickets as test cases, and a report of what your agent did to it. The same three commands work for every world.

YOU NEED

NODE 24

Or newer. Every command runs the runtime straight from the registry. Nothing is installed into your project.

A READ ONLY KEY

For the account to copy onto your machine. It is used once and never written to disk. Live keys are refused. Without one, the first command starts on a bundled sample account.

A HELP DESK EXPORT

CSV or JSON, if you have one. The customers it names are copied into the world and its tickets become your first test cases. Without one, you get fifteen tickets from the starter library, each with a known correct answer.

YOUR AGENT AS A COMMAND

Whatever runs it on one ticket. If you do not have one, three lines make one.

Copy your account and connect your agent

npx -p sparta_worlds@0.6.0 worlds init --agent "<your agent command>"

Prompts for your key and your help desk export, then writes a worlds folder into your repo: a pseudonymized copy of your account that is safe to commit, your first test cases, your rules for the grader in plain English, and a test plus a CI workflow with your agent's command already in place.

Import more tickets

npx -p sparta_worlds@0.6.0 worlds tasks import tickets.csv --into worlds/tasks.yaml

Add tickets whenever you like: a help desk export, or the spreadsheet someone on the team keeps. Columns are matched by name, one task per row. Where you know the right outcome, add one line, for example expected: refund $243.00 on duplicate.

Run the crash test

npx -p sparta_worlds@0.6.0 worlds passk --server auto --tasks worlds/tasks.yaml --runs 3 --report worlds-report.html -- <your agent command>

Runs your agent three times on fresh copies of your account. The report shows dollars wrong per run, a verdict and reason for every task, and a replay of the worst run. This same line is the test and the CI step the first command wrote.

Every file the first command writes, the five policy questions, how the import matches columns, the flags and the judge are in THE DOCS.

CONNECT YOUR AGENT

Three lines. The task arrives as JSON on stdin and in WORLDS_TASK_JSON. Print the reply you would send the customer. No Worlds dependency in your agent.

const task = JSON.parse(process.env.WORLDS_TASK_JSON);
const reply = await handleTicket(task); // your agent, as it is
process.stdout.write(reply);

import json, os, sys
task = json.loads(os.environ["WORLDS_TASK_JSON"])
sys.stdout.write(handle_ticket(task))  # your agent, as it is

A stock SDK in your agent is pointed at the world automatically by the environment these commands set. A client that sets its own host is left alone.

If your agent is bundled, uses another SDK, or polls a help desk queue, see THE DOCS.

OR HAND IT TO YOUR CODING AGENT

Paste this prompt into Claude Code, Cursor or Codex from inside your agent's repository. It runs the three steps above, asks you for the key at the prompt, and creates no account. It reads llms.txt for the details.

Set up the Worlds crash test for the agent in this repository. Read https://twinlab-site.vercel.app/llms.txt first; it is the whole path. Then:

1. Run: npx -p sparta_worlds@0.6.0 worlds init --agent "<your agent command>"
   Replace <your agent command> with the command that runs my agent once on a ticket: the task arrives as JSON on stdin and in WORLDS_TASK_JSON, and the agent prints the reply. The command asks for a restricted read only key for the account to copy at its prompt: stop and ask me for it there. Never put a key in a file, on a command line or in a commit.

2. Run: npx -p sparta_worlds@0.6.0 worlds try --server auto -- <your agent command>
   Read what it printed. If it says the agent never reached the world, run: npx -p sparta_worlds@0.6.0 worlds doctor --server auto -- <your agent command>
   and fix how my agent's SDK is pointed at the world before going on. A stock SDK needs no change; a bundled one reads WORLDS_BASE_URL and WORLDS_API_KEY.

3. Run: npx -p sparta_worlds@0.6.0 worlds passk --server auto --tasks worlds/tasks.yaml --runs 3 --report worlds-report.html -- <your agent command>
   Open worlds-report.html and tell me what it says: dollars wrong per run, each task's verdict, the worst task.

Commit the worlds folder and the workflow the first command wrote. Never commit worlds/my-account.identities.json. Do not install the runtime into the project and do not create an account; there is none.

MORE COMMANDS

Runs your agent on one built in ticket, with no key and no files. The world reports what it did.

npx -p sparta_worlds@0.6.0 worlds try --server auto -- <your agent command>

When try reports that your agent never reached the world. Shows the environment the agent was given, the world's request log, and how its SDK connected.

npx -p sparta_worlds@0.6.0 worlds doctor --server auto -- <your agent command>

Checks the tasks file and names every problem by task id before anything runs.

npx -p sparta_worlds@0.6.0 worlds tasks validate worlds/tasks.yaml

Checks the grader itself: five known agents, five expected verdicts, none of your code involved.

npx -p sparta_worlds@0.6.0 worlds selftest --server auto

A long running server for manual work, at http://127.0.0.1:4242.

npx -p sparta_worlds@0.6.0 worlds serve

Imports a larger sample of your account, or takes other flags. A read only key is enough.

npx -p sparta_worlds@0.6.0 worlds seed import --from-stripe --key rk_live_… --name my-account --limit 500 --out worlds/seeds/my-account.json --manifest worlds/my-account.manifest.json --identity-map worlds/my-account.identities.json

The whole starter library, no key needed: 88 tickets across 33 failure classes, each with a known correct answer.

npx -p sparta_worlds@0.6.0 worlds init --agent "<your agent command>" --pack all

A sixty second demo with our toy agent: a planted double refund, caught by the world diff.

npx -p sparta_worlds@0.6.0 worlds demo

Python client for writing tests. One file, vendor it.

curl -O https://twinlab-site.vercel.app/dl/worlds_client.py

JavaScript client for writing tests against the world's admin API.

npm i -D https://twinlab-site.vercel.app/dl/worlds-client-0.6.0.tgz

Every command runs the runtime straight from the registry, pinned to this version. Nothing is installed into your project. Licensed for evaluation use, not for redistribution, with no warranty. Full terms are in LICENSE.txt inside the tarball.

WANT US TO RUN IT WITH YOU?

Book an hour. Bring a read only key, a help desk export and your rules, and we run the three steps together. You keep the report. We delete the imported account afterwards unless you ask us to keep it.