Skip to main content
You’ll build a device for a packing station: the agent can scan a barcode, read the scale, look up stock, print a receipt, and open a dock gate after confirmation, and the station wakes the agent when stock runs low. The hardware is simulated so the example runs anywhere with Node 18 and an agent created with lua init. Verified against lua-cli 3.45.0.

What you’ll build

  • A Node device warehouse-station-01 with five commands.
  • A low_stock_alert trigger fired by the station and handled by a defineDeviceTrigger on the agent.
  • Persona guidance so the model confirms before opening a gate.
1

Create the credential

From the agent project, issue a device credential for device name warehouse-station-01; the default operations, commands and triggers, are what the station needs. Then load it in the folder where the device will run and install the client.
2

Write the device

Each handler talks to simulated hardware; replace the stubs with your drivers. The station checks stock every minute and fires low_stock_alert for each SKU under its threshold.
device.ts
3

Handle the trigger on the agent

In the agent project, a standalone trigger stores the alert and hands it to the model. The name matches the device’s string exactly.
src/devices/LowStockAlert.ts
4

Register and publish

Register the trigger, give the model its rules in the persona, then push the trigger live.
src/index.ts
5

Run and talk to it

Start the station, then ask the agent from the project.
The model calls device__warehouse_station_01__scan_barcode, then check_stock_level, and reports Widget A as low.
6

Verify the trigger

Within a minute the station fires low_stock_alert for Widget A. Read the handler’s run.
Stop the script: lua devices status --device-name warehouse-station-01 --ci prints offline and the five tools are gone on the agent’s next turn. If the connection drops while the script runs, each minute’s trigger() call rejects with Not connected to device gateway and the loop logs it until the client reconnects.

What you learned

  • Timeouts per command (timeoutMs) cover slow hardware such as a printer. See Expose device commands as tools.
  • Confirmation rules belong in the persona and the command description; the device can’t see the conversation.
  • A trigger is queued and acknowledged before its handler runs, and the handler is published with lua push device-trigger --auto-deploy. See Handle device triggers.

Next steps

Smart office

Several devices in a group with one fan-out tool.

defineDevice and defineDeviceTrigger

Every handler field.