TypeScript SDK

The @withgateway/sdk package is the Node client for worlds and the runs made against them. Use it to open a live session and drive it from an agent, publish and pin a world’s versions, gate a pull request on a graded run, and trace what the agent did. The package also installs the gateway command. Terminal usage is documented under The gateway CLI, not here.

Install the package

npm install @withgateway/sdk

Node 18 or newer is required. Every subpath works with the base install except those below.

Subpath	Extra packages	Why
`@withgateway/sdk/tracing`	`@opentelemetry/api`, `@opentelemetry/sdk-trace-node`, `@opentelemetry/sdk-trace-base`, `@opentelemetry/exporter-trace-otlp-http`, `@opentelemetry/resources`	Tracing is built on OpenTelemetry, which stays a peer so your app owns the version
`@withgateway/sdk/scores`, `@withgateway/sdk/security`	`@opentelemetry/api`	Both read the active span to find the trace a score or a tool call belongs to
`session.browser()`	`playwright`	Only when you drive a world’s UI, see Drive a world UI

npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources

Wrapping an LLM client with observeOpenAI or observeAnthropic needs nothing extra. The OpenInference instrumentation ships with the package as an optional dependency.

Set three environment variables

Every client reads the same three variables. Generate the key pair under Project Settings, API keys; the world, session or run you create lands in the project those keys belong to.

export GATEWAY_HOST="https://withgateway.ai"
export GATEWAY_PUBLIC_KEY="pk-lf-..."
export GATEWAY_SECRET_KEY="sk-lf-..."

gateway auth login writes the same three values to ~/.gateway/config.json for the CLI. The SDK reads the environment only, so a script still needs the variables exported.

Keep the secret key in environment variables or a secrets manager. Never hardcode it in source files, examples, or agent prompts.

Every worlds function takes an optional { host, publicKey, secretKey } object as its last argument when one call needs different credentials than the environment holds.

Open a world session and call it

openWorld resolves a slug to its pinned version and task list. open boots a live container for one task, and toolkit() hands you that world’s tools in the shape a model expects.

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

// Credentials come from GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY.
const world = await openWorld("acme-billing@main");
console.log(world.slug, world.version.semanticVersion, world.tasks.length);

const session = await world.open("refund-double-charge");
await session.ready();

console.log(session.instruction);

const { schemas, impls } = await session.toolkit();
await impls.list_invoices({ status: "open" });

const { reward, rewards } = await session.grade();
console.log(reward, rewards);

await session.close({ keepWarm: true });

Hand schemas to your model as its tool definitions and dispatch tool calls through impls. Nothing else in the agent has to know a world exists.

The TypeScript SDK resolves versions, drives hosted sessions, and dispatches hosted runs. To run a world in your own process, use the Python SDK.

The import map

Import	What it provides	Page
`@withgateway/sdk/worlds`	Resolve a world, run configs, dispatch a hosted run, secrets	Worlds
	Live sessions, stored tasks, the parallel task runner	World sessions, Run a task suite
	Browser and computer-use tools on a world’s UI	Drive a world UI
	Push, pull, propose, refs, pull request validation	Publish a world, Gate a pull request
`@withgateway/sdk/scores`	Post scores and success signals against a trace or session	Scores and signals
`@withgateway/sdk/sessions`, `@withgateway/sdk/replay`	Load a recorded session, replay a suite of them	Sessions and replay
`@withgateway/sdk/tracing`	`init`, `observe`, the client wrappers, `identify`	Tracing and experiments
`@withgateway/sdk/experiments`	Register experiments and assign variants	Tracing and experiments
`@withgateway/sdk/security`	Let Surface Area gate which tools an agent may call	Tracing and experiments
`@withgateway/sdk/context`, `/memory`, `/personas`, `/users`	Context items, agent memory blocks, simulated personas, the user profile client
`@withgateway/sdk`	Everything above except the tracing functions, plus `tracing` as a namespace and the build manifest helpers

The root entry re-exports the worlds, sessions, replay, scores, users, experiments, context, memory, personas and security modules, plus identify and the build manifest helpers. Importing a subpath keeps a service’s dependency surface smaller; the examples in this section use subpaths.

tracing.init() imported from @withgateway/sdk also wires experiment attributes onto every span. Imported from @withgateway/sdk/tracing it does not. Use the root entry when the same process assigns variants and traces.

Where to go next

Worlds for resolving a version and dispatching a hosted run.
World sessions for every method on a live session.
Run a task suite for running a dozen tasks in parallel with a score gate.
Gate a pull request for validateWorld in GitHub Actions.
The gateway CLI for the same operations from a terminal.

CLI

Python SDK

SDK Reference

REST API

MCP Server

TypeScript SDK

Install the package

Set three environment variables

Open a world session and call it

The import map

Where to go next

​Install the package

​Set three environment variables

​Open a world session and call it

​The import map

​Where to go next

Install the package

Set three environment variables

Open a world session and call it

The import map

Where to go next