Agent Game SDK

Embeddable agent game views, avatars, and Game-owned Office contracts. The package is independently installable:

bun add @agent-os-lab/agent-game-sdk

Game owns AgentGameOfficeConfig, AgentGameAgentInput, and AgentGameAgentSource. The application owns persistence and explicitly supplies Office configuration and agent data. Game root exports only Game APIs; Runtime clients, messages, Presence types, and list helpers must be imported from the Runtime package.

Compose Runtime with Game

import {
  AgentGameRuntimeBrowserClient,
  subscribeAgentPresenceList,
  type AgentPresence,
} from "@agent-os-lab/agent-game-runtime-sdk";
import {
  mountAgentGameOffice,
  type AgentGameAgentInput,
  type AgentGameAgentSource,
  type AgentGameOfficeConfig,
} from "@agent-os-lab/agent-game-sdk/office";

function mapPresence(agent: AgentPresence): AgentGameAgentInput {
  return {
    id: agent.agentId,
    name: agent.displayName,
    status: agent.status,
    role: agent.scene ?? null,
    activity: agent.activity,
    interaction: agent.interaction,
    updatedAt: agent.updatedAt,
  };
}

function createAgentSource(client: AgentGameRuntimeBrowserClient): AgentGameAgentSource {
  let subscription: Awaited<ReturnType<typeof subscribeAgentPresenceList>> | undefined;
  return {
    subscribe(listener) {
      let active = true;
      void subscribeAgentPresenceList(client, {
        onAgentsChange: (agents) => listener(agents.map(mapPresence)),
      }).then((value) => {
        if (!active) {
          value.close();
          return;
        }
        subscription = value;
      });
      return () => {
        active = false;
        subscription?.close();
        subscription = undefined;
      };
    },
    refresh: () => subscription?.refresh(),
  };
}

const office: AgentGameOfficeConfig = {
  building: {
    floors: [{ id: "floor-1", name: "Main", rooms: [{ type: "office" }] }],
    connectors: [],
  },
};

const client = new AgentGameRuntimeBrowserClient({ baseUrl: "" });
const source = createAgentSource(client);
const view = await mountAgentGameOffice(container, {
  renderer: "three",
  office,
  source: { type: "agents", source },
});

view.selectAgent("agent-1");
view.resetCamera();

The mapper is intentionally application-owned. It is where transport meaning becomes game meaning; AgentPresence is not accepted directly as AgentGameAgentInput.

Office configuration and persistence

AgentGameOfficeConfig describes Game-owned floors, rooms, connectors, and layout. The application owns persistence: load it explicitly through an application BFF or trusted AgentOS client, validate it, then pass it to Game. Save editor changes explicitly through the same application boundary. Runtime has no Office configuration API.

If office is omitted, Game uses its built-in default configuration. It does not load persisted configuration automatically.

AgentOS persistence may return source: "none" with config: null when neither a tenant override nor a stored platform default exists. Applications that want this local Game default should omit office or select DEFAULT_OFFICE_CONFIG explicitly; the server no longer returns Game's code-built default.

OfficeBuildingCanvas, mountOfficeBuildingCanvas, and getOfficeFloors provide building-only rendering and floor metadata. Controllers support a Reset view action through view.resetCamera().

Avatar views

import {
  mountAgentAvatarCanvas,
  mountAgentAvatar3D,
  renderAgentAvatar3DThumbnailBatch,
} from "@agent-os-lab/agent-game-sdk/avatar";

const avatar = mountAgentAvatar3D(container, {
  agentId: "agent-1",
  backgroundColor: "#f8fafc",
  framing: "upperBody",
  viewAngle: "front",
});

Use mountAgentAvatarCanvas for pixel sprites and renderAgentAvatar3DThumbnailBatch for efficient lists.

Breaking changes

• Game root no longer re-exports Runtime APIs; import them from @agent-os-lab/agent-game-runtime-sdk.
• Runtime client source was removed; use { type: "agents", source } with an AgentGameAgentSource.
• Runtime AgentPresence must be explicitly mapped to AgentGameAgentInput.
• Office configuration is no longer loaded automatically. Applications explicitly load, pass, and persist AgentGameOfficeConfig.
• 0.2.0: AgentOS empty persistence is distinct from Game's local default; handle source: "none" instead of assuming a server configuration always exists.

See USAGE.md for source variants, React, avatars, and persistence composition.