gatewaysdk Python package is the client for 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.
TypeScript users should start with the TypeScript SDK. The pages in
this section document the Python package.
Install the package
Install the base package from PyPI.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.Keep the secret key in environment variables or a secrets manager. Never
hardcode it in source files, examples, or agent prompts.
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 fromgatewaysdk.
The CLI is the TypeScript one
Use the
gateway command from the @withgateway/sdk npm package, which
covers worlds, connectors, sessions, data and versions. See
The gateway CLI.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. A captured session is the seed a world is built from, and a run against a world is traced like any other agent execution.Each feature works on its own. Open a world session without touching tracing,
or track a run without pushing a world.