5-Minute Quickstart

Connect Your First Device

Get a device connected and responding to agent commands.

Install the device client

npm install @lua-ai-global/device-client

yarn add @lua-ai-global/device-client

pnpm add @lua-ai-global/device-client

pip install lua-device-client

Configure the credential

For Node.js, create a credential bound to your exact agent, the device name my-first-device, and the commands operation. Follow Provision a device credential, then save the returned secret in an environment variable:

export LUA_DEVICE_CREDENTIAL="your-device-credential"

The published Python 1.3.0 client uses api_key. Set LUA_API_KEY to an existing non-dotted legacy key. Existing legacy configurations remain supported indefinitely.

For the Python example, set the variable that its api_key field reads:

export LUA_API_KEY="your-existing-legacy-key"

Create a device client

Create a file called device.ts or device.py. Use the same agent ID and device name that you used at provisioning:

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

const device = new DeviceClient({
  agentId: 'your-agent-id',
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  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' },
        },
      },
    },
  ],
});

import os
from lua_device import DeviceClient, DeviceCommandDefinition

client = DeviceClient(
    agent_id="your-agent-id",
    api_key=os.environ["LUA_API_KEY"],
    device_name="my-first-device",
    commands=[
        DeviceCommandDefinition(
            name="ping",
            description="Check if the device is alive",
        ),
        DeviceCommandDefinition(
            name="read_sensor",
            description="Read the current temperature in celsius",
            input_schema={
                "type": "object",
                "properties": {
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
                },
            },
        ),
    ],
)

Find your agentId in .lua/lua.config.yaml after running lua init, or in the Lua dashboard.

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' };
});

from datetime import datetime, timezone

@client.on_command("ping")
async def handle_ping(payload):
    return {"status": "ok", "timestamp": datetime.now(timezone.utc).isoformat()}

@client.on_command("read_sensor")
async def handle_read_sensor(payload):
    # In a real device, read from hardware here
    temp_celsius = 22.5
    unit = (payload or {}).get("unit", "celsius")
    temp = (temp_celsius * 9 / 5) + 32 if unit == "fahrenheit" else temp_celsius
    return {"temperature": temp, "unit": unit}

Connect

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

main().catch(console.error);

import asyncio

async def main():
    await client.connect()
    print("Device connected and ready for commands")

asyncio.run(main())

Run your device:

npx tsx device.ts

python device.py

You should see:

Device connected and ready for commands

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-global/device-client';

const device = new DeviceClient({
  agentId: 'your-agent-id',
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  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);

import asyncio
import os
from datetime import datetime, timezone
from lua_device import DeviceClient, DeviceCommandDefinition

client = DeviceClient(
    agent_id="your-agent-id",
    api_key=os.environ["LUA_API_KEY"],
    device_name="my-first-device",
    commands=[
        DeviceCommandDefinition(
            name="ping",
            description="Check if the device is alive",
        ),
        DeviceCommandDefinition(
            name="read_sensor",
            description="Read the current temperature in celsius",
            input_schema={
                "type": "object",
                "properties": {
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
                },
            },
        ),
    ],
)

@client.on_command("ping")
async def handle_ping(payload):
    return {"status": "ok", "timestamp": datetime.now(timezone.utc).isoformat()}

@client.on_command("read_sensor")
async def handle_read_sensor(payload):
    temp_celsius = 22.5
    unit = (payload or {}).get("unit", "celsius")
    temp = (temp_celsius * 9 / 5) + 32 if unit == "fahrenheit" else temp_celsius
    return {"temperature": temp, "unit": unit}

async def main():
    await client.connect()
    print("Device connected and ready for commands")

asyncio.run(main())

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

Getting Started

Device Client

Agent Integration

Examples

Advanced

CLI Commands

5-Minute Quickstart

Connect Your First Device

Complete Working Example

Next Steps

Architecture

Self-Describing Commands

Triggers

Node.js Client Reference

​Connect Your First Device

​Complete Working Example

​Next Steps

Architecture

Self-Describing Commands

Triggers

Node.js Client Reference

Connect Your First Device

Complete Working Example

Next Steps