> ## 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.

# Python SDK

> What the gatewaysdk Python package gives you — a client for worlds, their sessions and their versions, plus runs and scoring — and which module to import for each task.

The `gatewaysdk` Python package is the client for [worlds](/worlds) and the runs made against them. Use it to open a live session and drive it from an agent, push and pin a world's versions, read a world's scenarios and rollouts, and record what a run scored.

<Info>
  TypeScript users should start with the [TypeScript SDK](/sdk-ts). The pages in
  this section document the Python package.
</Info>

## Install the package

Install the base package from PyPI.

```bash theme={null}
pip install gatewaysdk
```

The world clients need nothing extra. Auto-instrumentation of AI libraries lives in an optional extra, because it pulls in the libraries it instruments.

```bash theme={null}
pip install 'gatewaysdk[tracing]'   # auto-instrument OpenAI, Anthropic, LiteLLM, ...
```

For the full install walkthrough and credential setup, see [Quick Install](/get-started/installation).

## Connect to Surface Area

Every client reads the same three environment variables. Generate the key pair in your project settings, then export them before running your agent.

```bash theme={null}
export GATEWAY_HOST="https://withgateway.ai"
export GATEWAY_PUBLIC_KEY="pk-lf-..."
export GATEWAY_SECRET_KEY="sk-lf-..."
```

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

Clients that support environment configuration expose a `from_env()` classmethod that reads those variables. Module-level helpers such as `open_session()` fall back to them automatically, and take `host`, `public_key` and `secret_key` arguments to override one.

## Pick a module

Import the parts you need directly from `gatewaysdk`.

| Import | What it provides | Page |
| - | - | - |
| `gatewaysdk.world_sessions` | Open a live session against one task of a world, call its tools and surfaces, seed it, grade it, close it | [Worlds client](/sdk/environments) |
| `gatewaysdk.world_tasks` | Create, version, validate and delete stored tasks a session can open by id | [Worlds client](/sdk/environments) |
| `gatewaysdk.world_data` | Stream rows into a world as a validated data batch | [Worlds client](/sdk/environments) |
| `gatewaysdk.environments` | Read a world's scenarios, per-task performance and rollouts; create tasks | [Worlds client](/sdk/environments) |
| `gatewaysdk.benchmark_hub` | Push, version, fork and evaluate worlds as content-hashed bundles | [Worlds hub](/sdk/benchmark-hub) |
| `gatewaysdk.run`, `gatewaysdk.experiment`, `gatewaysdk.episode` | Track runs, log metrics, and post scores | [Runs & Experiments](/sdk/run-decorator) |
| `gatewaysdk.sessions`, `gatewaysdk.replay` | Load sessions from the platform, dump them as fixtures, and replay them | [Sessions & Replay](/sdk/sessions-replay) |

## The CLI is the TypeScript one

<Info>
  Use the `gateway` command from the `@withgateway/sdk` npm package, which
  covers worlds, connectors, sessions, data and versions. See
  [The gateway CLI](/cli).
</Info>

This Python package also installs a `gateway` console script, so installing both puts two commands called `gateway` on your `PATH`. Install the npm package globally and keep `gatewaysdk` inside a virtual environment, so the npm one wins.

## Tracing has its own section

Tracing captures every LLM call, tool call and nested step as an OpenTelemetry trace. One function call initializes it, and installed AI libraries instrument themselves. See [Tracing](/tracing).

A captured session is the seed a world is built from, and a run against a world is traced like any other agent execution.

<Info>
  Each feature works on its own. Open a world session without touching tracing,
  or track a run without pushing a world.
</Info>


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