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

# The sample repository

> connector-worlds is a public demo app - an example agent (Relay) plus three commands that turn a user's production traffic into hosted worlds on the platform and run the agent against them.

[`Gateway-Innovations/connector-worlds`](https://github.com/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.

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

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

<Steps>
  <Step title="Run Relay offline">
    No keys: the connectors are in-memory fixtures and a deterministic scripted model drives the agent.

    ```bash theme={null}
    cd relay && npm ci
    npm run dev        # chat UI at http://localhost:3939
    npm run evals      # local end-state evals of the demo scenarios
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    DEMO_USER_ID=demo-user npm run agent -- "Upgrade Initech to the Enterprise tier."
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    npm run traffic:pull -- --user demo-user
    ```
  </Step>

  <Step title="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:

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

  <Step title="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.

    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

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

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

<Info>
  The repository's README carries the same five steps with the exact commands.
</Info>


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