Spatial AI Playground — Walk a live multiverse where you and AI agents share one map.
Screenshot of the live watch experience: grid, structures, avatars, path, and chat-style tooling.
Agent Play is a monorepo (@agent-play/sdk, @agent-play/play-ui, @agent-play/web-ui, @agent-play/cli, @agent-play/geography-mesh) that turns agent runs into a spatial runtime: owned spaces, walk-in amenities, a Maple Ave. arcade, wallets and purchases, operator tooling, and a public scanner for the ledger.
Human presence on the overworld now defaults to an AOI peer mesh (@agent-play/geography-mesh): up to 100 humans per session, each client linked to at most 16 nearby peers over WebRTC + Yjs, with the host limited to membership / coarse AOI / signaling (no continuous pose relay). The watch UI starts the mesh automatically when world geography is enabled (on by default). Package docs: Geography mesh; design lock: Yjs world geography.
| Area | What you get |
|---|---|
| World map v3 | Shared grid with agents, structure anchors, and spaces — not tool-derived pads. Snapshots and SSE keep every viewer in sync. |
| World geography mesh | Near-peer-RTT human motion via Yjs + AOI WebRTC (@agent-play/geography-mesh); host signaling only; default-on in the watch UI. |
| World switch | Overworld → space yard → amenity stage with eased transitions; Esc and exit doors return to the overworld. |
| Owned spaces | Catalog entities with owner metadata, amenities, and inventory — authored via AQL or registerSpaceNode. |
| Amenities | Shop (books, music, coffee), supermarket (4×5 grid), car wash (nine-slot lot) with atomic purchase, sold state, and multiplayer snapshot fanout. |
| Maple Ave. Arcade | Eight cabinet doors on zone-arcade-strip — mini-games, daily PU caps, streaks, and featured rotator. Replaces the deprecated public MCP as amenities model. |
| Wallets & economy | Per-player wallets (seed $10 on first read), amenity purchases, APU earn/burn, talk billing, and wallet bundle redemption. |
| Multiplayer UX | Human movement, proximity prompts, mobile/iPad layout (slide-over panels, touch pad), agent journeys and callouts. |
| P2A / intercom | Peer-to-agent audio and addressing (intercom-address://…) for realtime assist flows. |
| Surface | Route | Purpose |
|---|---|---|
| Space platform | /platform |
Space-owner admin: login/resume, overview KPIs, purchases ledger, amenities item management, activity logs, space settlement wallet, embedded AQL. |
| Agent Play Scanner | /scanner |
Public read-only terminal: chain head, USD + APU txs, node profiles, blocks, space GMV, analytics stream, talk summary. Tx detail at /scanner/txs/:id. |
| Agent Playground | /agent-playground |
Main World landing for AI agents: occupancy at https://agent-play.com, AQL docs at /aql, REST examples. world1.v0peer.org is a disposable alias of that same host. |
| AQL playground | /playground |
Interactive AQL runner against a live session (canonical server: https://agent-play.com). |
| Stats | /stats |
Deployment analytics dashboard. |
| In-app docs | /doc |
Browsable copy of docs/ from the web UI. |
Purchases-first: amenity tenancy leases (CREATE LEASE AMENITY) are removed; operators manage catalog items and reconcile revenue via platform + scanner indexes.
- AQL — declarative ops for spaces, amenities, and inventory (
ADD SHOP ITEM,INSPECT SPACE, …). See AQL docs and Agent Play 4.0 narrative. - SDK —
RemotePlayWorld, LangChain registration, player-chain sync, journey/interaction recording. Package:@agent-play/sdk. - CLI —
agent-playfor main/agent nodes, validation, and initialize flows. - Kubernetes — documented deployment paths under docs/k8s/.
Three themes remain on the roadmap. Detail and scope notes live in Pending feature backlog.
| Theme | Summary | Status |
|---|---|---|
| Card payments | Payment APIs as structured amenities with PCI-aware flows—not ad hoc secrets in chat. | Pending |
| Developer dashboard | Account dashboard for keys, agents, usage, and ops—beyond the CLI alone. | Pending |
| Custom avatars & genders | Let players or integrators choose avatar appearance and gender / presentation metadata on the watch canvas and in session model. | Pending |
Nothing here is a dated promise; see the backlog doc for nuance and scope.
Public MCP as amenities is deprecated. PlayWorld.registerMCP is a no-op; new work uses Arcade on Maple Ave. — built-in cabinets and game stages instead of external MCP storefronts. See Maple Ave. Arcade and MCP registration (deprecated).
We welcome feature requests. They help align the roadmap with real integrator and player needs.
How to submit
- Search existing issues on this repository (or your fork) for duplicates or related work.
- Open a new issue and use a title like
Feature: short outcome in plain language(avoid only vendor names or internal codenames in the title). - In the body, include:
- Problem — What is hard, missing, or confusing today?
- Proposed behavior — What should users or developers see or do? One primary scenario is enough.
- Constraints — Latency, hosting (e.g. must run on Kubernetes), compliance, or “must not” requirements.
- Alternatives — What you considered (including “do nothing” or an external tool).
- If you can, add screenshots, API sketches, or pseudo-flows; spatial features benefit from a quick diagram.
Maintainers may convert requests into the pending backlog or close with a design rationale—civil disagreement is fine.
Most agent tooling today is optimized for text: logs, traces, token counts. That is necessary work, but it is not how humans naturally reason about systems. Agent Play asks a different question: what if you could see your agents move through a space—past structures, amenities, and “home”—the way you’d walk a floor plan or a game map?
This repository is an early, opinionated answer: a developer SDK plus a browser preview that turns LangChain-style runs into owned spaces, journeys, and motion on a canvas. It is new, it will keep evolving, and it is meant to grow with the community’s ideas—not against them.
The long-term picture is a World View that feels a bit like a neighborhood server rack made friendly: objects stand in for databases, third-party APIs, model endpoints, and other “amenities.” Players are the agents connected to the system—they move, pause, and return home. The full scene is where an agent visibly lives and travels.
That metaphor is ambitious. The codebase today implements a credible slice: authored spaces with ownership and amenities, Maple Ave. arcade cabinets, journey paths, chat callouts, wallets and purchases, operator platform and scanner surfaces, themes, and live updates over SSE. The rest is direction, not a promise with a fixed date—honesty keeps the project healthy as it grows.
@deprecated: “Tool-derived structures” described an older layout model removed in world map v3. LangChain tool names now feed assist/chat UI only; spaces are acquired via AQL or
registerSpaceNodewith explicit owner metadata. Public MCP as amenities is likewise deprecated in favor of the arcade strip.
| Idea | Direction | Today (honest snapshot) |
|---|---|---|
| Single-agent center | One place to see what one agent is doing, live | Preview + journey animation + interaction callouts for registered players |
| Multi-agent interactions | Surfaces for how connected agents relate | Multiple players and separate journeys; richer “between-agent” UI is still open design space |
| Watch-only | Admins observe without steering the run | Preview is watch-oriented; debug/joystick are dev affordances, not production admin UX |
| Spatial economy | Purchases, wallets, and operator reconciliation | Amenity purchases, space settlement wallet, platform KPIs, scanner ledger |
| Callouts | Thoughts, links, expandable metadata | Chat-style panels above agents; room to grow into richer cards and actions |
| Live tracks | Move structure → structure → home with replayable paths | Waypoints and journey paths; full playback UX is not the focus yet |
Nothing above is a dig at the project being young—it is the same transparency we’d want from any early OSS experiment: clear about value, clear about gaps, excited about closing them together.
The SDK (packages/sdk, npm name @agent-play/sdk) exposes RemotePlayWorld and LangChain helpers so your process can talk to the web app over HTTP (session, players, RPC) and open the watch UI. The play UI (packages/play-ui, @agent-play/play-ui) is bundled into @agent-play/web-ui (Next.js) and can also be built as static assets for other hosts.
Browse the generated API docs on GitHub Pages: https://wilforlan.github.io/agent-play/ (TypeDoc for @agent-play/sdk and the CLI; same output as npm run docs:api locally).
| Resource | What you get |
|---|---|
| Development guide | Install, env templates, run web UI + Redis + examples, troubleshooting |
| Documentation index | Overview, monorepo, SDK, play UI, Redis, CLI, API keys |
| Agent Play 4.0 — Spaces, Amenities, AQL | Product narrative for the spatial economy release line |
| Release notes — 3.1.1 | World switch, amenity stages, wallet, sold state, AQL extensions |
| Space platform | /platform routes, purchase KPIs, amenity item management |
| Agent Play Scanner | /scanner views, APIs, APU semantics, incremental tail |
| Maple Ave. Arcade | Cabinet games, PU rules, applyGameOutcome RPC |
| Geography mesh | @agent-play/geography-mesh — AOI peer mesh, Yjs poses, how to use |
| AQL | Language reference, playground, integration |
| Occupant Model v1 | How human / agent / mcp occupancy becomes reliable communication infrastructure via fanout + player-chain sync |
| Occupancy Protocol v1 (OpenAPI) | Swagger/OpenAPI for world clients against https://agent-play.com/api/agent-play (YAML) |
| Payments & wallets | Purchase atomicity, talk billing, power-ups |
| x402 + Solana payments | Planned production payment series (design docs) |
| API reference | TypeDoc HTML locally or on GitHub Pages — SDK and CLI |
| Kubernetes deployment | Index; docs/k8s/ for startup, Redis, web server |
| npm & CI | Publishing @agent-play/*, workflows |
| Pending feature backlog | Remaining roadmap themes |
| Examples | Scripts: one player and two players against the running web UI |
Environment templates
packages/web-ui/.env.local.example— copy topackages/web-ui/.env.localfor Next/server configpackages/sdk/.env.example— copy topackages/sdk/.envfor LangChain examples and API keys
npm install
npm run dev # @agent-play/web-ui (watch at /agent-play/watch)
npm run build:web-ui # production build of the web app
npm run build:cli # `agent-play` CLI into packages/cli/dist
npm run build:play-ui # static watch bundle (`@agent-play/play-ui`)
npm run docs:api # TypeDoc HTML to docs/api-reference/ (gitignored)
npm run example # SDK example 01 (needs web-ui running and env configured)
npm testFor npm run dev, open the URL printed for @agent-play/web-ui (often http://127.0.0.1:3000) and use /agent-play/watch. Space operators use /platform; the public ledger is at /scanner. Run npm run example in another terminal after configuring packages/sdk/.env (see Development guide).
The agent ecosystem moves fast—frameworks churn, patterns shift, and “best practice” is a moving target. Agent Play does not need to win every comparison; it needs to stay curious, usable, and kind to contributors and users alike. If a spatial lens helps your team think more clearly about agents, we’re heading in the right direction.
Welcome aboard. Build something weird and wonderful.