Handle device triggers

After this guide, an event your device sends runs code on the platform: stored, handed to the model, or turned into a workflow run. Use a device trigger when the hardware decides when something happens; when the model should ask the device, expose a command instead. Verified against lua-cli 3.45.0. Before you begin

A connected device with a credential that grants triggers, which lua devices credential grants by default.
The agent project signed in, and the agent ID from agent.agentId in lua.skill.yaml if the handler hands the event to the model. A device trigger handler runs with an empty env(), so keep the ID in the handler file rather than in an environment variable.

Fire the trigger from the device

Send a name and a JSON payload. Use underscores in the name; the platform matches it character for character against your handler.

Node
Python
MicroPython

device.ts

import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({
  agentId: process.env.LUA_AGENT_ID!,
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  deviceName: 'bench-sensor',
});

async function reportAlert() {
  await device.connect();
  const ack = await device.trigger('temperature_alert', { temperature: 41.2, threshold: 40 });
  console.log('queued as', ack.triggerId);
}

reportAlert().catch((err: Error) => console.error(err.message));

trigger() resolves when the platform has queued the event and rejects with Trigger 'temperature_alert' ACK timeout (10s) if no acknowledgment arrives.

device.py

import asyncio
import os

from lua_device import DeviceClient

client = DeviceClient(
    agent_id=os.environ["LUA_AGENT_ID"],
    api_key=os.environ["LUA_DEVICE_CREDENTIAL"],
    device_name="bench-sensor",
)


async def report_alert():
    await client.connect()
    ack = await client.trigger("temperature_alert", {"temperature": 41.2, "threshold": 40})
    print("queued as", ack.trigger_id)


asyncio.run(report_alert())

Raises TimeoutError after 10 seconds without an acknowledgment.

main.py

device.trigger("temperature_alert", {"temperature": 41.2, "threshold": 40})

Returns at once; the acknowledgment is printed when it arrives.

Write the handler

A handler runs on the platform with the payload and { device: { name }, trigger: { name, triggerId } }, and has up to 10 minutes to return, the platform’s default cap for event handlers. Declare it inline on the device or as a standalone trigger that any device on the agent can fire.

Inline on defineDevice
Standalone defineDeviceTrigger

src/devices/BenchSensor.ts

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

export const benchSensor = defineDevice({
  name: 'bench-sensor',
  description: 'Temperature sensor on the test bench',
  triggers: {
    temperature_alert: {
      description: 'Fires when the bench temperature exceeds its threshold',
      payloadSchema: z.object({ temperature: z.number(), threshold: z.number() }),
      async execute(payload, { device, trigger }) {
        await Data.create('bench-alerts', {
          device: device.name,
          triggerId: trigger.triggerId,
          temperature: payload.temperature,
          at: Date.now(),
        });
      },
    },
  },
});

src/devices/DoorOpened.ts

import { Agents, defineDeviceTrigger } from 'lua-cli';
import { z } from 'zod';

// From lua.skill.yaml; env() is empty inside device-trigger handlers.
const AGENT_ID = 'agent_abc123';

export const doorOpened = defineDeviceTrigger({
  name: 'door_opened',
  description: 'Any door sensor reports that its door opened',
  payloadSchema: z.object({ door: z.string(), openedAt: z.string() }),
  async execute(payload, { device }) {
    await Agents.invoke(
      AGENT_ID,
      `Device ${device.name} reports door ${payload.door} opened at ${payload.openedAt}.`
    );
  },
});

Agents.invoke starts a turn with the prompt and resolves with the model’s reply. The agent member of the context is typed but not populated at runtime, so don’t call it.

Only declarations referenced from LuaAgent are compiled.

src/index.ts

import { LuaAgent } from 'lua-cli';
import { benchSensor } from './devices/BenchSensor';
import { doorOpened } from './devices/DoorOpened';

export default new LuaAgent({
  name: 'bench-agent',
  persona: 'You help engineers on the test bench.',
  devices: [benchSensor],
  deviceTriggers: [doorOpened],
});

Publish the handlers

Devices and device triggers 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. --force alone skips the prompt and leaves the version unpublished.

lua push device --name bench-sensor --auto-deploy
lua push device-trigger --name door_opened --auto-deploy

The platform runs the latest live handler for a name.

Verify

Fire the trigger from the device, or from the agent project without the device, then read the handler’s run.

lua devices test-trigger --device-name bench-sensor --trigger temperature_alert --payload '{"temperature":41.2,"threshold":40}' --ci
lua logs --type device-trigger --limit 20

lua devices test-trigger sends the event through the same live pipeline as the device, with the same 1 MB payload cap and rate limit, so the handler really runs; the device receives nothing and doesn’t need to be connected, but a disabled device is refused.A trigger with no live handler is logged as skipped and dropped; the device still receives received: true, because the acknowledgment means queued, not handled.

Options you may need

Start a workflow instead of a chat turn

Return { startWorkflow: { name, input, idempotencyKey } } from execute to start a run of a workflow on the agent; the fields match a LuaTrigger transform. Any other return value is logged.

React to connections

The platform fires device_connected with { deviceName, connectedAt, metadata } when a device’s connection opens and device_disconnected with { deviceName, disconnectedAt } when it closes or its MQTT will is published; a device timed out by the heartbeat sweep fires neither. Handle them with a defineDeviceTrigger of the same name.

Delivery guarantees

Events are delivered at least once from a durable queue: a handler that throws or exceeds its time limit is run again, up to 3 attempts 60 seconds apart, so make handlers idempotent; trigger.triggerId is the same on every attempt. The platform never sends a trigger_result back to the device, so the clients’ trigger-result handlers don’t run.

If it isn’t working

The log says the trigger was skipped

No live handler matched the name. Check the exact spelling on both sides (temperature_alert and temperature-alert are different names), and that the push finished with the version live.

trigger_error with RATE_LIMITED

The agent received more than 10 triggers in one second across all its devices. Batch readings into one payload or fire less often. Only the Node Socket.IO client surfaces the event; the MQTT clients don’t subscribe to trigger_error, so their trigger() call times out after 10 seconds instead.

trigger_error with OPERATION_FORBIDDEN

The credential doesn’t grant triggers. Issue a new credential with the operation; over MQTT the publish is denied silently instead.

Next steps

defineDevice and defineDeviceTrigger

Every handler field, the dispatch rules, and startWorkflow.

Triggers

How HTTP triggers differ from device triggers.

Factory monitor

A MicroPython device that fires anomaly triggers.

Get started

Concepts

Build

Channels

Integrations

Devices

Ship and operate

Ship logs to your stack

Marketplace

Build with AI

Examples

Handle device triggers

Options you may need

Start a workflow instead of a chat turn

React to connections

Delivery guarantees

If it isn’t working

Next steps

defineDevice and defineDeviceTrigger

Triggers

Factory monitor

​Options you may need

​Start a workflow instead of a chat turn

​React to connections

​Delivery guarantees

​If it isn’t working

​Next steps

defineDevice and defineDeviceTrigger

Triggers

Factory monitor

Options you may need

Start a workflow instead of a chat turn

React to connections

Delivery guarantees

If it isn’t working

Next steps