Operational Agent Rooms quickstart

This walkthrough runs the complete deterministic reference application with PostgreSQL. It exercises the same canonical services used by the operational runtime without requiring a model account, Temporal or an external work-management provider.

1. Start the reference application

git clone https://github.com/Agentplat/agentplat.git
cd agentplat
corepack enable
pnpm install
cd examples/rooms-api
cp .env.example .env
docker compose up --build -d
curl --fail http://localhost:3000/health

Docker Compose applies PostgreSQL migrations 001–011 before accepting traffic. The application wires RoomService, automatic coordination, the coordination worker, execution sessions, Agent Definition Registry, Handoffs, Planner, human contributions, knowledge bundles, participant membership, operational events and LiveView.

2. Run the integrated scenario

bash scripts/demo.sh
pnpm scenario

The scenario creates a Room and participants, publishes an agent revision, persists a message and its coordination item transactionally, executes a policy-checked task and run, records an artifact, progresses a plan and human contribution, and reads the automatically discovered LiveView.

No external model is called: @agentplat/runtime-mock produces deterministic output. External writes remain denied unless an explicit policy allows them.

3. Observe durable state

curl -sS \
  -H 'X-Agentplat-Tenant-Id: demo' \
  'http://localhost:3000/rooms/ROOM_ID/events?limit=50'
 
curl -N \
  -H 'X-Agentplat-Tenant-Id: demo' \
  'http://localhost:3000/rooms/ROOM_ID/live/stream'

Replace ROOM_ID with the identifier printed by the scenario. The development header assumes a trusted local caller; replace it with an injected authenticator before exposing the API.

4. Verify restart recovery

pnpm scenario:restart

Separate processes recover expired coordination, run, intervention, execution-session, Handoff, contribution and delivery leases while preserving stable operation identity. This demonstrates deterministic integration and restart behavior, not production availability or a deployment-specific SLA.

5. Optional workflow adapter

Use @agentplat/rooms-temporal when the deployment needs Temporal wakeup, signals, retries or history rollover. PostgreSQL and Agent Room stores remain authoritative. The in-process worker and Temporal adapter must not own the same coordination scope concurrently.

6. Shut down

docker compose down

Add --volumes only when you intend to delete the disposable PostgreSQL data.