Skip to main content

​
Connect Your First Device

Get a device connected and responding to agent commands in five steps.
1

Install the device client

npm install @lua-ai/device-client
2

Create a device client

Create a file called device.ts (or device.js) and configure the client with your agent credentials:
import { DeviceClient } from '@lua-ai/device-client';

const device = new DeviceClient({
  agentId: 'your-agent-id',
  apiKey: 'your-api-key',
  deviceName: 'my-first-device',
  commands: [
    {
      name: 'ping',
      description: 'Check if the device is alive',
    },
    {
      name: 'read_sensor',
      description: 'Read the current temperature in celsius',
      inputSchema: {
        type: 'object',
        properties: {
          unit: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' },
        },
      },
    },
  ],
});
Find your agentId and apiKey in .lua/lua.config.yaml after running lua init, or in the Lua dashboard.
3

Register command handlers

Tell the device what to do when the agent sends each command:
device.onCommand('ping', async () => {
  return { status: 'ok', timestamp: new Date().toISOString() };
});

device.onCommand('read_sensor', async (payload) => {
  // In a real device, read from hardware here
  const tempCelsius = 22.5;
  const temp = payload?.unit === 'fahrenheit'
    ? (tempCelsius * 9/5) + 32
    : tempCelsius;

  return { temperature: temp, unit: payload?.unit || 'celsius' };
});
4

Connect

async function main() {
  await device.connect();
  console.log('Device connected and ready for commands');
}

main().catch(console.error);
Run your device:
npx tsx device.ts
You should see:
Device connected and ready for commands
5

Test with lua chat

In another terminal, start a chat session with your agent:
lua chat
Try saying:
> Ping my-first-device
> What's the temperature reading from my-first-device?
> Read the sensor in fahrenheit
The agent will use the device tools to send commands and return the results.
No compile or push needed. Your device declared its commands at connect time. The agent already has tools for them. Change the commands array, restart the device, and the agent sees the new tools instantly.

​
Complete Working Example

Here is the full file in one piece: 
import { DeviceClient } from '@lua-ai/device-client';

const device = new DeviceClient({
  agentId: 'your-agent-id',
  apiKey: 'your-api-key',
  deviceName: 'my-first-device',
  commands: [
    {
      name: 'ping',
      description: 'Check if the device is alive',
    },
    {
      name: 'read_sensor',
      description: 'Read the current temperature in celsius',
      inputSchema: {
        type: 'object',
        properties: {
          unit: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' },
        },
      },
    },
  ],
});

device.onCommand('ping', async () => {
  return { status: 'ok', timestamp: new Date().toISOString() };
});

device.onCommand('read_sensor', async (payload) => {
  const tempCelsius = 22.5;
  const temp = payload?.unit === 'fahrenheit'
    ? (tempCelsius * 9/5) + 32
    : tempCelsius;
  return { temperature: temp, unit: payload?.unit || 'celsius' };
});

async function main() {
  await device.connect();
  console.log('Device connected and ready for commands');
}

main().catch(console.error);

​
Next Steps

Architecture

Understand how commands and triggers flow through the system

Self-Describing Commands

Learn how devices declare their capabilities

Triggers

Let your device push events to the agent

Node.js Client Reference

Full API reference for the device client