🏢 @main12/agent-office-plugin

Payload CMS plugin for AI agent virtual office visualization. Built with PixiJS, WebSocket, and the official Payload plugin architecture.

Overview

Renders a 2D/isometric virtual office where AI agents from different departments interact graphically — think "AI Town meets corporate office." Agents walk between departments, chat in real-time, and execute tasks while you monitor everything in a PixiJS canvas.

Business model: Plugin is open-source (MIT). Agent server SaaS is paid.

Quick Start

# In your Payload project:
pnpm add @main12/agent-office-plugin

// payload.config.ts
import { agentOfficePlugin } from '@main12/agent-office-plugin'

export default buildConfig({
  plugins: [
    agentOfficePlugin({ enabled: true })
  ]
})

// Any page/dashboard ('use client'):
import { AgentOffice } from '@main12/agent-office-plugin/client'

<AgentOffice officeSlug="acme-hq" theme="pixel" />

Plugin Options

agentOfficePlugin({
  enabled: true,                  // enable the plugin
  defaultWsEndpoint: 'wss://...', // default WebSocket endpoint for offices
  maxFloorsPerOffice: 10,         // floor limit per office (default: 10)
  maxAgentsPerFloor: 50,          // agent limit per floor (default: 50)
  collections: { ... }            // selectively enable collections
})

Features

• 🎮 PixiJS engine — isometric + flat tilemap renderers, animated agent sprites (LPC layered sprites), A* pathfinding, agent routines, chat bubbles
• 🏢 Multi-floor — scale vertically with floors instead of infinite single plane, floor selector UI
• 🗺️ Map Editor — design floor plans with predesigned office blocks, rotation support, save directly to Payload floors
• 🪑 Furniture system — furniture sets, styles registry, set editor and layout preview tools
• 📦 Asset pack uploads — upload agent sprite packs (ZIP) and furniture packs (ZIP/.nitro/.ps1) straight into Payload collections
• 🔀 Workflow channels — public | department | direct message visibility, channel-scoped communication
• 🔗 Cross-floor events — agents can escalate between floors
• 🎨 Three themes — pixel, corporate, minimal
• 🔌 AG-UI compatible WebSocket protocol — JSON over WSS with snapshot/spawn/move/message/action/tool-call events
• 📦 Zero template changes — install and use, no template modifications
• 👥 Multi-tenant ready — separate office per client

Collections Added

| Collection | Slug | Purpose | |------------|------|---------| | Offices | agent-offices | Office configs (floors, wsEndpoint, theme) | | Floors | agent-floors | Floor plans / tilemaps | | Departments | agent-departments | Department zones with colors | | Agents | agent-agents | Agent definitions (sprites, LPC layers) | | Agent Providers | agent-providers | WS/REST agent runtime providers | | Furniture | agent-furniture | Furniture sprites/items | | Furniture Sets | agent-furniture-sets | Furniture bundles | | Global | agent-office-settings | Plugin settings |

Exports

Server (.)

• agentOfficePlugin — plugin entry
• AgentOfficePluginOptions — plugin option types

Client (./client)

• Components: AgentOffice, MapEditor, MapViewer, SetEditor, FloorMapEditorUI, SetEditorAdminUI, AgentAvatarPreviewUI, FurniturePreviewUI, FurnitureBulkUploadUI, ConfigDrawer, PlacedItemsDrawer, FurnitureStylesModal, AgentSprite (Pixi)
• Presentation blocks: PREDESIGNED_BLOCKS, FLOOR_BLOCKS, rotateOfficeBlock, isWithinBlockBounds
• Mappers/adapters: OfficeMapper, FloorMapper, AgentMapper, FurnitureMapper, FurnitureSetMapper
• Types: AgentOfficeComponentProps, AgentState, AgentEvent, OfficeConfig, FloorPlan, OfficeBlock

WebSocket Protocol

See specs/PROTOCOL.md — Agent Office Protocol (AOP) v0.2.0-draft:

• JSON over WebSocket (WSS), orchestrator/broker pattern — the Main12 Agent Server routes events; clients own agents and API keys
• Provider types: hermes-agent, claude-api, openai-api, ollama, crewai, langgraph, autogen, custom-ws, main12-managed
• Lifecycle: SUBSCRIBE {officeId, token, channels, floor} → OFFICE_SNAPSHOT + AGENT_SPAWN events
• Agent states: idle | busy | thinking | waiting | error
• Events: AGENT_MOVE (tween path or local A*), AGENT_MESSAGE, AGENT_BROADCAST, AGENT_ACTION_START/COMPLETE, AGENT_TOOL_CALL — all AG-UI compatible

Architecture

┌──────────────┐     REST      ┌──────────────────┐
│   Payload    │◄─────────────►│   Agent Server   │
│   (config)   │               │   (Docker / DO)   │
└──────────────┘               └────────┬─────────┘
       │                                 │
       │ Payload API                     │ WebSocket (AOP)
       │                                 │
       ▼                                 ▼
┌─────────────────────────────────────────────────┐
│              <AgentOffice />                     │
│         (PixiJS + React, A* pathfinding)         │
└─────────────────────────────────────────────────┘

Project Structure

src/
├── index.ts              → Plugin entry (server)
├── exports/
│   ├── client.ts         → 'use client' exports
│   └── rsc.ts            → RSC exports
├── collections/          → Offices, Floors, Departments, Agents,
│                           AgentProviders, Furniture, FurnitureSets
├── globals/
│   └── AgentOfficeSettings.ts
└── shared/
    ├── domain/           → Types, protocol, tile model (0=empty,1=floor,2=wall,3=desk,4=meeting_room)
    ├── infrastructure/   → Pixi engine (OfficeCanvas, AgentSprite, IsoTilemapRenderer,
    │                       Pathfinding, AgentRoutines, ChatBubble, isometric helpers)
    ├── interface/        → Hooks (useAgentWebSocket), handlers
    └── presentation/     → Editor UI components

Development

pnpm install
pnpm dev          # Start dev server with test project (Next + Payload, turbo)
pnpm test:int     # Run integration tests (vitest)
pnpm test:e2e     # Run E2E tests (playwright)
pnpm build        # Build dist/ (copyfiles + tsc types + swc)

Dev app routes: office-demo (full AgentOffice demo), map-editor, set-editor, set-preview, agent-preview, furniture-preview.

Dependencies

| Required | Optional (enhanced UX) | |----------|----------------------| | payload ^3.86 | @heroui/react | | react ^19 | framer-motion | | next ^16 | lucide-react | | pixi.js ^8 | | | tailwindcss ^4 | |

Node ≥ 24.15, pnpm 9–11.

Roadmap

• [x] Phase 1: Data model + Payload collections
• [x] Phase 3: PixiJS engine (sprites, tilemaps, pathfinding, animations)
• [x] Map editor, set editor, asset pack uploaders
• [ ] WebSocket agent server implementation (protocol spec done)
• [ ] Agent detail panel
• [ ] Agent server (Docker + CrewAI ref)
• [ ] Playground / Demo hosting
• [ ] RSC exports

License

MIT — Main 12 Technologies