Agent Game SDK

Embeddable agent game views and runtime clients.

For the full integration guide, see USAGE.md.

Office View

Framework-neutral mount API:

import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
import { mountAgentGameOffice } from "@agent-os-lab/agent-game-sdk/office";

const client = new AgentGameRuntimeBrowserClient({
  baseUrl: "",
  accessToken: async () => getScopedToken(),
});

const view = await mountAgentGameOffice(container, {
  renderer: "three",
  office: {
    rooms: [
      { type: "office" },
      { type: "auditorium", capacity: 40 },
      { type: "gym" },
    ],
  },
  source: {
    type: "runtime",
    client,
  },
});

view.focusAgent("agent-1");
view.refreshAgents();
view.destroy();

React wrapper:

import { useState } from "react";
import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
import type { AgentGameOfficeController } from "@agent-os-lab/agent-game-sdk/office";
import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";

const client = new AgentGameRuntimeBrowserClient({
  baseUrl: "",
});

export function Office() {
  const [view, setView] = useState<AgentGameOfficeController | null>(null);

  return (
    <>
      <button type="button" onClick={() => view?.refreshAgents()}>
        Refresh agents
      </button>
      <AgentGameOfficeView
        renderer="three"
        office={{
          rooms: [
            { type: "office" },
            { type: "auditorium" },
            { type: "gym" },
          ],
        }}
        source={{ type: "runtime", client }}
        style={{ height: 640 }}
        onReady={setView}
        onDestroy={() => setView(null)}
      />
    </>
  );
}

agent-game-sdk/office is renderer and framework neutral. agent-game-sdk/office/react is the React-only entrypoint.

Runtime Agent List

Use subscribeAgentPresenceList when an app needs the live Agent roster and status outside the 3D office view:

import {
  AgentGameRuntimeBrowserClient,
  formatAgentPresenceStatus,
  subscribeAgentPresenceList,
} from "@agent-os-lab/agent-game-sdk";

const client = new AgentGameRuntimeBrowserClient({
  baseUrl: "",
});

const subscription = await subscribeAgentPresenceList(client, {
  onAgentsChange: (agents) => {
    renderAgentList(agents.map((agent) => ({
      id: agent.agentId,
      name: agent.displayName,
      status: formatAgentPresenceStatus(agent.status),
      activity: agent.activity?.summary,
    })));
  },
});

const currentAgents = subscription.getAgents();
subscription.close();

The helper applies runtime snapshot messages as the full roster and patch messages as incremental updates, so consumers always receive a complete sorted Agent list.

The built-in 3D renderer supports semantic room configuration. If office is omitted, the SDK renders the default office + auditorium + gym layout. To choose visible rooms, pass office.rooms in the order you want them assembled:

office: {
  rooms: [
    { type: "office" },
    { type: "gym" },
  ],
}

Built-in room types are office, auditorium, and gym. capacity is optional and affects generated agent placement anchors; desks, walls, meeting rooms, gym equipment, windows, and raw coordinates stay internal to the SDK.

Runtime statuses stay unchanged. The SDK locally distributes idle and resting agents across ambient areas such as lounge, pantry, gym, and reading/bookcase anchors so inactive agents do not all gather at the sofa.

Browser clients should call an application BFF endpoint. By default the browser client requests /api/agent-game-runtime-token on the same origin. Configure tokenPath only if your application exposes that BFF route at a different path.

Keep the AgentOS service API key on the server; the SDK server client forwards it to Agent Game Runtime. The runtime token endpoint path is SDK-managed and defaults to Agent Game Runtime's /api/v1/game-runtime-token, so application code only needs baseUrl and apiKey:

import { AgentGameRuntimeServerClient } from "@agent-os-lab/agent-game-sdk";

const client = new AgentGameRuntimeServerClient({
  baseUrl: process.env.AGENT_GAME_RUNTIME_BASE_URL!,
  apiKey: process.env.AGENTOS_API_KEY!,
});

export async function GET() {
  return Response.json(await client.createRuntimeToken());
}

Local Demo

Run the SDK office view demo:

AGENT_GAME_RUNTIME_BASE_URL=http://localhost:3107 AGENTOS_API_KEY=... bun run demo

Open http://localhost:7357. Set PORT=7358 or another value to change the port.

Publish

Publishing is controlled from this SDK package directory. The script bumps the package version, builds the package, runs npm pack --dry-run, and then publishes to npm:

bun run sdk:publish

The default release is patch. Use --minor or --major when needed:

bun run sdk:publish -- --minor

Use --dry-run to validate the next version and package contents without publishing. The script restores the previous version after a dry run.

If npm requires two-factor authentication, pass the one-time password with --otp:

bun run sdk:publish -- --otp 123456