Run a smart office with device groups

You’ll build two devices, one per office floor, declared in the agent project with defineDevice and connected with the lua-device runner instead of a custom script. Because they share a group, the agent gets a fan-out tool that sends a notice to every connected floor in one call. The hardware is simulated; you need Node 18 and an agent created with lua init. The runner with a handlers file stands in for the hardware. lua devices test sends one command to one connected device and can’t call the fan-out tool, and lua test has no device type, so you’ll exercise the group with lua chat -m. Verified against lua-cli 3.45.0.

What you’ll build

office-floor-3 and office-floor-4 in the group office-floors, with four commands each.
The fan-out tool device__office_floors__show_notice__all.
A handler module the runner loads on each floor’s machine.

Declare the devices

Both declarations share one commands object. The runner sends no command list, so these declarations are the only source of the tools.

src/devices/FloorControllers.ts

import { defineDevice, DeviceCommandConfig } from 'lua-cli';
import { z } from 'zod';

const floorCommands: Record<string, DeviceCommandConfig> = {
  meeting_rooms: { description: 'List the meeting rooms on this floor with their occupancy' },
  set_temperature: {
    description: 'Set the target temperature for this floor in celsius',
    inputSchema: z.object({ celsius: z.number().min(18).max(26) }),
  },
  desk_occupancy: { description: 'Count occupied and free desks on this floor' },
  show_notice: {
    description: 'Show a notice on the floor display for a number of minutes',
    inputSchema: z.object({ text: z.string().max(200), minutes: z.number().int().min(1).max(120).default(10) }),
    timeoutMs: 5000,
  },
};

export const officeFloor3 = defineDevice({
  name: 'office-floor-3',
  description: 'Building controller for floor 3',
  group: 'office-floors',
  commands: floorCommands,
});

export const officeFloor4 = defineDevice({
  name: 'office-floor-4',
  description: 'Building controller for floor 4',
  group: 'office-floors',
  commands: floorCommands,
});

Devices are pushed one by one and are not part of an agent version. A pushed defineDevice declaration reaches the runtime on the agent’s next turn whether or not you publish it; --auto-deploy only records it as the active version. A standalone defineDeviceTrigger runs only after its pushed version is published, with --auto-deploy or the push prompt.

src/index.ts

import { LuaAgent } from 'lua-cli';
import { officeFloor3, officeFloor4 } from './devices/FloorControllers';

export default new LuaAgent({
  name: 'office-concierge',
  persona: 'You are the office concierge. Find free rooms, adjust comfort, and post notices on the floor displays.',
  devices: [officeFloor3, officeFloor4],
});

lua push device --name office-floor-3 --auto-deploy
lua push device --name office-floor-4 --auto-deploy

Write the handler module

The runner loads a CommonJS module whose commands map one handler per command name. The same file runs on both floors; it reads the floor from an environment variable.

handlers.cjs

const floor = process.env.FLOOR;
const rooms = { 3: ['Atlas', 'Everest'], 4: ['Summit', 'Pinnacle'] }[floor] ?? [];
let target = 21;

module.exports = {
  commands: {
    meeting_rooms: async () => ({ floor, rooms: rooms.map((name, i) => ({ name, occupied: i % 2 === 0 })) }),
    set_temperature: async (payload) => {
      target = Number(payload.celsius);
      return { floor, target };
    },
    desk_occupancy: async () => ({ floor, total: 48, occupied: 31 }),
    show_notice: async (payload) => {
      console.log(`[floor ${floor} display] ${payload.text} (${payload.minutes} min)`);
      return { floor, shown: true };
    },
  },
};

Create two credentials and connect

Each device needs its own credential, bound to its name, with commands. Issue one per floor from the agent project:

mkdir -p ../office-floors
lua devices credential --device-name office-floor-3 --operations commands --out ../office-floors/.env.floor-3
lua devices credential --device-name office-floor-4 --operations commands --out ../office-floors/.env.floor-4

The files sit outside the agent project so they are never committed. Then run one runner per floor, each in its own terminal; each prints Connected as 'office-floor-3' to agent '<id>' and Listening for commands... (Ctrl+C to stop).

npm install -g @lua-ai-global/device-client
(set -a; . ../office-floors/.env.floor-3; set +a; FLOOR=3 lua-device connect --agent-id "$LUA_AGENT_ID" --device-credential "$LUA_DEVICE_CREDENTIAL" --device-name "$LUA_DEVICE_NAME" --group office-floors --handler ./handlers.cjs)
(set -a; . ../office-floors/.env.floor-4; set +a; FLOOR=4 lua-device connect --agent-id "$LUA_AGENT_ID" --device-credential "$LUA_DEVICE_CREDENTIAL" --device-name "$LUA_DEVICE_NAME" --group office-floors --handler ./handlers.cjs)

Broadcast a notice

From the agent project, ask for a notice on every floor. The model calls device__office_floors__show_notice__all once; the result lists total, succeeded, failed, and one entry per device.

lua chat -m "Put 'Fire drill at 15:00' on every floor display for 30 minutes"

Verify

List the group and check each device.

lua devices list --group office-floors
lua devices status --device-name office-floor-3 --ci

Stop the floor-4 runner and ask again: the fan-out result reports total: 2, succeeded: 1, failed: 1, because every registered member of the group is addressed and the offline one fails.

What you learned

defineDevice puts the command contract in the agent project under version control; the runner needs no code. See defineDevice and defineDeviceTrigger.
A group on declared devices produces device__<group>__<command>__all; self-describing devices don’t get fan-out tools. See Expose device commands as tools.
One credential binds one device name; a fleet needs one credential per device. See Create a device credential.

Get started

Concepts

Build

Channels

Integrations

Devices

Ship and operate

Ship logs to your stack

Marketplace

Build with AI

Examples

Run a smart office with device groups

What you’ll build

What you learned

Next steps

Warehouse station

lua devices

​What you’ll build

​What you learned

​Next steps

Warehouse station

lua devices

What you’ll build

What you learned

Next steps