Worlds

@withgateway/sdk/worlds is how a Node process names a world and runs against it. A world resolves to one pinned version, that version has a task list, and a run of it comes back graded. Every function on this page takes an optional WorldsClientOptions object ({ host, publicKey, secretKey }) as its last argument. Omit it and the three environment variables are used.

Resolve a world to a pinned version

openWorld(slugRef, options?) takes a slug or a slug@ref, where the ref is a branch, tag, semantic version or content hash. It returns a WorldSet without downloading the bundle, because the task list comes from the version’s file manifest.

import { openWorld } from "@withgateway/sdk/worlds";

const world = await openWorld("acme-billing@main");

console.log(world.slug);                      // "acme-billing"
console.log(world.ref);                       // "main"
console.log(world.version.versionId);         // the pinned version
console.log(world.version.semanticVersion);   // "1.4.0" or null
console.log(world.version.contentHash);       // what the version is, exactly
console.log(world.tasks.map((t) => t.name));  // every scenario in it

world.version is a ResolvedWorldVersion: versionId, semanticVersion, contentHash and state. Pin runs to versionId whenever a suite must not split across two versions mid-flight.

Find one scenario

world.tasks holds a WorldTask per scenario, each with a name and a variant parsed from the name. world.task(variant) returns the first task whose variant matches, or whose name contains the string, and throws with the known names when nothing matches.

const task = world.task("mara");
console.log(task.name, task.variant);

A WorldSet is identity and data only. To execute anything, either open a live session (world.open, see World sessions) or dispatch a hosted run (world.dispatch, below).

Run configs name what a run executes

A run config is a saved selection: which models to run, how much parallelism, and which scenarios or stored tasks to work through. Continuous integration resolves a config by name and dispatches it by id.

import { listRunConfigs, upsertRunConfig } from "@withgateway/sdk/worlds";

const configs = await listRunConfigs();
for (const config of configs) {
  console.log(config.id, config.name, config.models, config.parallelism);
}

upsertRunConfig(input, options?) creates a config, or updates the one named by input.id.

const config = await upsertRunConfig({
  name: "pr-gate",
  models: ["claude-sonnet-4-5"],
  parallelism: 4,
  taskNames: ["refund-double-charge", "close-stale-invoice"],
  autoRunOnPush: false,
});

Field	Type	What it selects
`name`	`string`	The stable handle CI configures, required
`models`	`string[]`	One run is filed per model
`parallelism`	`number`	Containers the runner works through at once
`numExamples`, `rolloutsPerExample`	`number`	How many scenarios, and how many attempts each
`timeoutMinutes`	`number`	Budget for the whole run
`agent`	`string`	The agent the platform runs inside the container
`taskNames`	`string[]`	Scenarios from the world’s own bundle
`taskSetDatasetId`	`string \| null`	A scenario set instead of bundled names
`worldTasks`	`WorldTaskIdRef[]`	Stored tasks, for API worlds
`autoRunOnPush`	`boolean`	Run this config automatically on every push

A config runs either the bundle’s own scenarios or the project’s stored tasks, never both. parseWorldTaskRefs(spec) turns id or id@version items, comma-separated or as an array, into the worldTasks shape. A ref without a version runs the task’s current version at dispatch time.

import { parseWorldTaskRefs } from "@withgateway/sdk/worlds";

const refs = parseWorldTaskRefs("wt_abc,wt_def@2");
// [{ id: "wt_abc" }, { id: "wt_def", version: 2 }]

Dispatch a hosted run

world.dispatch(runConfigId, opts?) starts the run on the platform. The platform executes the world in parallel containers and files one graded run per model.

const { versionLabel, runs } = await world.dispatch(config.id);

for (const run of runs) {
  console.log(run.model, run.runId, run.ok, run.error);
}

opts accepts containerId, versionId to pin a version other than the world’s own, and provenance to override what was detected.

Provenance is detected, not configured

Every dispatch carries the branch, commit, repository and actor it came from. detectProvenance() reads the GitHub Actions environment first, then falls back to the local git checkout.

import { detectProvenance } from "@withgateway/sdk/worlds";

console.log(detectProvenance());
// { branch: "fix/refunds", commit: "9f3c...", repoUrl: "...", actor: { ... } }

Outside git and outside CI the object comes back empty and the dispatch still goes through.

Read the verdict

getRun(runId, options?) returns a RunReport in one request. waitForRun(runId, opts?) polls until the run is terminal.

import { waitForRun } from "@withgateway/sdk/worlds";

const report = await waitForRun(runs[0].runId, {
  timeoutMinutes: 45,
  intervalSeconds: 20,
  onTick: (run) => console.log(run.status, run.shardsCompleted, "/", run.parallelism),
});

console.log(report.status, report.score, report.url);

waitForRun polls every 20 seconds for up to 45 minutes by default, and throws when the run is still running past the deadline.

The RunReport shape

Field	Type	What it is
`id`	`string`	The run id
`status`	`string`	`COMPLETED`, `FAILED`, and the states before them
`terminal`	`boolean`	Whether the run has stopped moving
`score`	`number \| null`	The run’s score, or null when it was not scored
`summary`	`string \| null`	The platform’s one-line summary
`model`	`string \| null`	The model this run used
`versionLabel`	`string \| null`	The world version that ran
`parallelism`	`number`	Containers used
`shardsCompleted`	`number \| null`	Progress while the run is live
`url`	`string \| null`	The run’s page, which is what a pull request comment should link
`evaluations`	`{ id, status, avgReward, url }[]`	One entry per shard
`samples`	`{ task, reward, rewards, sessionId }[]`	Per-scenario rewards

A score of null means the run was not scored. Treat it as a failure of a score gate rather than as a zero, which is what validateWorld does.

Set a world’s secrets

A world that calls a real service holds its credentials on the platform, never in the bundle. The three helpers are write-only: no endpoint returns a secret’s value.

import {
  setEnvSecret,
  listEnvSecretKeys,
  deleteEnvSecret,
} from "@withgateway/sdk/worlds";

await setEnvSecret("acme-billing", "STRIPE_API_KEY", process.env.STRIPE_API_KEY!);

for (const secret of await listEnvSecretKeys("acme-billing")) {
  console.log(secret.key, secret.updatedAt);
}

await deleteEnvSecret("acme-billing", "STRIPE_API_KEY");

Call any public endpoint

apiRequest(options, method, path, body?) is the authenticated request the worlds helpers are built on. Use it to call any REST API route directly.

import { apiRequest } from "@withgateway/sdk/worlds";

const projects = await apiRequest<{ data: { id: string; name: string }[] }>(
  {},
  "GET",
  "/api/public/projects",
);

The first argument is the same { host, publicKey, secretKey } object every other function takes. Pass {} to use the environment. Describe a world covers reading what a world holds and finding a redacted row from the plaintext you know.

Where to go next

World sessions to drive one task interactively instead of dispatching a run.
Run a task suite to run every scenario against your own agent.
Gate a pull request to push, dispatch and gate in one call.
What a world is for what versions and refs mean.

CLI

Python SDK

TypeScript SDK

SDK Reference

REST API

MCP Server

Resolve a world to a pinned version

Find one scenario

Run configs name what a run executes

Dispatch a hosted run

Provenance is detected, not configured

Read the verdict

The RunReport shape

Set a world’s secrets

Call any public endpoint

Where to go next

​Resolve a world to a pinned version

​Find one scenario

​Run configs name what a run executes

​Dispatch a hosted run

​Provenance is detected, not configured

​Read the verdict

​The RunReport shape

​Set a world’s secrets

​Call any public endpoint

​Where to go next

Resolve a world to a pinned version

Find one scenario

Run configs name what a run executes

Dispatch a hosted run

Provenance is detected, not configured

Read the verdict

The RunReport shape

Set a world’s secrets

Call any public endpoint

Where to go next