The sample repository

Gateway-Innovations/connector-worlds is a demo of the whole loop from the customer’s side: an example agent, with the platform doing everything simulation-related for it. Relay is an ops agent with a chat UI that works across a customer’s Slack, Google Drive, Jira and CRM. The repository takes what Relay’s users actually did, turns each user’s traffic into hosted worlds seeded with that user’s data, and runs Relay against those worlds before a change ships. The repository holds the agent and three small commands. The schemas, the worlds, the sessions and the graders are the platform’s.

Nothing in the repository is a world. There is no connector.toml, no schema/, no bundle and no CI that runs worlds. Every world is created on the platform from a shipped connector template, and every simulation runs in a hosted session.

What it shows

Relay (the agent)                         Surface Area (the platform)
user → chat UI → agent → connectors  ───► tracing: one trace per run, a tool span per
                                           connector call, the user's id on every trace
npm run traffic:pull -- --user <id>  ◄──── public API: that user's sessions with full IO
npm run world:from-traffic -- --user <id> ► worlds create --from slack | google-drive | jira | salesforce
                                           data extract → rows through each world's contract
                                           data import  → a data-only version per world
npm run simulate -- --user <id>      ───► hosted sessions of relay-<id>-{slack,google-drive,jira,crm}
                                           inline tasks, assertion graders, per-session results

The five-minute path

Everything runs from relay/ on Node 22.9 or later.

Run Relay offline

No keys: the connectors are in-memory fixtures and a deterministic scripted model drives the agent.

cd relay && npm ci
npm run dev        # chat UI at http://localhost:3939
npm run evals      # local end-state evals of the demo scenarios

Run it traced

Put a project’s keys in .env (GATEWAY_HOST, GATEWAY_PUBLIC_KEY, GATEWAY_SECRET_KEY, GATEWAY_PROJECT_ID). Every run is then a trace on the platform with the user’s id and a tool span per connector call. Those traces are the production traffic the next step pulls.

DEMO_USER_ID=demo-user npm run agent -- "Upgrade Initech to the Enterprise tier."

Pull a user's traffic

The user’s sessions, read back from the public API as a session-export JSONL, the shape gateway worlds session export prints. Without keys the command reads a bundled, invented recording so the rest of the path can be tried first.

npm run traffic:pull -- --user demo-user

Build the user's worlds

One hosted world per connector the traffic touched, from the platform’s shipped templates, seeded with rows extracted from the traffic through each world’s own contract. Per connector the command runs:

gateway worlds create relay-demo-user-slack --from slack --json
gateway worlds data extract relay-demo-user-slack slack_messages.calls.jsonl --shape session-export --entity slack_messages --out rows.jsonl
gateway worlds data import relay-demo-user-slack rows.json

A 409 on create means the world exists; the import still lands a new data version. --dry-run prints the rows per entity without touching the platform.

Simulate

Relay runs against the user’s worlds: one hosted session per world a scenario touches, Relay’s tools pointed at the sessions’ tools, the platform’s assertion graders on the final state, results and links printed.

npm run simulate -- --user demo-user --parallel 3 --scripted   # deterministic model, a transport smoke test
npm run simulate -- --user demo-user                            # a real model, gated by FAIL_UNDER
RELAY_USER=demo-user RELAY_MODE=gateway npm run dev             # the chat UI on the user's hosted worlds

Which platform surface does what

Step	Surface	Where it shows
Tracing the agent	the SDK’s `tracing.observe`, `observeOpenAI`, scores	Traces, Scores
Reading traffic back	`GET /api/public/traces`, `GET /api/public/sessions/{id}?includeIO=true`	—
A world per connector	`gateway worlds create <slug> --from <template>`	Worlds
Rows through a contract	`gateway worlds data extract … --shape session-export`, `gateway worlds data import`	the world’s Data tab
Hosted, isolated sessions	the SDK’s `openSession(slug, { task })` with an inline task and an assertion grader	the world’s Overview, `/world/sessions`
Grading	`session.grade()` over the final rows	the session

Relay keeps its own tools; the worlds serve the template tools (list_messages, share_file, search_issues, query_records, …). One adapter file maps one onto the other, so the agent and its schemas are exactly what runs in production.

Copy the pattern

Trace your agent with the user’s id on every run (Metadata & identity).
Pull a user’s sessions and project the tool calls into rows for the connector templates your agent touches (Put data in a world).
Create one world per connector per user with gateway worlds create --from <template> and import the rows (Simulations for your users).
Open hosted sessions in parallel and grade (Run many sessions at once).
Put the simulate step in your own CI (Run API worlds in CI). The sample repository ships none, so nothing runs against the platform without your keys.

The repository’s README carries the same five steps with the exact commands.

Start here

Get Started

Use cases

Worlds

Evaluation & Replay

Tracing

Hooks

What it shows

The five-minute path

Which platform surface does what

Copy the pattern

​What it shows

​The five-minute path

​Which platform surface does what

​Copy the pattern

What it shows

The five-minute path

Which platform surface does what

Copy the pattern