> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Install @withgateway/sdk, set credentials, and open a live world session from a Node agent. The import map for every subpath, and which extra packages each one needs.

The `@withgateway/sdk` package is the Node client for [worlds](/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](/cli), not here.

## Install the package

```bash theme={null}
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](/sdk-ts/browser) |

```bash theme={null}
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.

```bash theme={null}
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.

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

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.

```typescript theme={null}
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.

<Info>
  The TypeScript SDK resolves versions, drives hosted sessions, and dispatches hosted runs. To run a world in your own process, use the [Python SDK](/sdk/environments).
</Info>

## The import map

| Import | What it provides | Page |
| - | - | - |
| `@withgateway/sdk/worlds` | Resolve a world, run configs, dispatch a hosted run, secrets | [Worlds](/sdk-ts/worlds) |
| | Live sessions, stored tasks, the parallel task runner | [World sessions](/sdk-ts/sessions), [Run a task suite](/sdk-ts/run-sessions) |
| | Browser and computer-use tools on a world's UI | [Drive a world UI](/sdk-ts/browser) |
| | Push, pull, propose, refs, pull request validation | [Publish a world](/sdk-ts/hub), [Gate a pull request](/sdk-ts/ci) |
| `@withgateway/sdk/scores` | Post scores and success signals against a trace or session | [Scores and signals](/sdk-ts/scores) |
| `@withgateway/sdk/sessions`, `@withgateway/sdk/replay` | Load a recorded session, replay a suite of them | [Sessions and replay](/sdk-ts/replay) |
| `@withgateway/sdk/tracing` | `init`, `observe`, the client wrappers, `identify` | [Tracing and experiments](/sdk-ts/tracing) |
| `@withgateway/sdk/experiments` | Register experiments and assign variants | [Tracing and experiments](/sdk-ts/tracing#assign-an-a-b-variant) |
| `@withgateway/sdk/security` | Let Surface Area gate which tools an agent may call | [Tracing and experiments](/sdk-ts/tracing#let-surface-area-gate-an-agents-tools) |
| `@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.

<Info>
  `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.
</Info>

## Where to go next

* [Worlds](/sdk-ts/worlds) for resolving a version and dispatching a hosted run.
* [World sessions](/sdk-ts/sessions) for every method on a live session.
* [Run a task suite](/sdk-ts/run-sessions) for running a dozen tasks in parallel with a score gate.
* [Gate a pull request](/sdk-ts/ci) for `validateWorld` in GitHub Actions.
* [The gateway CLI](/cli) for the same operations from a terminal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.