Quick Start

After installing and starting Device Agent, create an Agent from a thermostat description, then add a device record and connect it to the browser simulator to verify command delivery, state reporting, and chat control without hardware. Device Agent manages this example directly; for existing IoT platform devices, complete IoT Platform Integration and verify queries and control in the workspace.

Before You Start

On macOS and Linux, run the commands below to install Device Agent and configure MQTT and the LLM for the first startup:

curl -fsSL https://emqx.sh/device-agent | sh

ZERO_EMQX_ENABLED=true \
LLM_PROVIDER=openai \
LLM_MODEL=gpt-5.5 \
OPENAI_API_KEY=sk-... \
device-agent

ZERO_EMQX_ENABLED=true creates a temporary Zero EMQX Broker at startup and writes the MQTT settings. When using an existing MQTT Broker, configure the connection values from MQTT Broker.

After Device Agent starts, open http://127.0.0.1:3000. For Windows installation, see Installation. The model can also be changed from Settings → Models in the console. See LLM Configuration for fields and provider examples.

1. Enter a Device Description

If there are no Device Agents yet, the console home page shows an input box where you can enter or upload a device description. If you already have Device Agents, click the + button in the left sidebar, or click Create device agent on the home page to start a new creation flow.

A device description can be plain text, JSON, YAML, or Markdown, as long as it describes the device's commands, properties, and events. View examples is optional; use it as a reference, or enter your own device description directly.

For this quick start, copy this description and send it:

Smart thermostat with on/off, target temperature setting and HVAC mode switching (heat/cool/auto/fan_only/eco), reporting current temperature, humidity and heating/cooling status, and reporting alert events when the temperature exceeds 30 degrees or the device goes offline.
Use set_target_temperature(value) to update target_temperature, and set_mode(mode) to update mode.
Use heat, cool, auto, fan_only, and eco as the mode enum values. Simulate these two state changes.

Click send, and Device Agent generates a DeviceSpec draft.

2. Review Device Capabilities

In the preview panel, check whether the commands, properties, and events generated by the model cover the expected behavior. Results vary with your input; the thermostat description above may produce:

• Commands: power control, target temperature setting, mode switching
• Properties: current temperature, target temperature, humidity, mode, heating/cooling status, online status
• Events: over-temperature and device offline alerts

Review Simulator behavior and confirm that the two setting commands update target_temperature and mode. If a mapping is missing or incorrect, describe the expected effect in the creation conversation and review the regenerated result. If validation fails, use Repair simulator behavior before saving.

If the capabilities and simulation behavior look correct, click Create. After creation finishes, click Enter Agent on the completion page, or open the newly created Device Agent from the left sidebar. Changing the capability model before saving also regenerates its simulation behavior.

3. Connect a Device to the Browser Simulator

After entering the Device Agent, the left side shows the Devices panel. Click Connect device, enter a device name and ID, and click Create device.

Select the new device in the list, then click Connect simulator in the status panel. The browser simulator connects to MQTT with that device ID and starts reporting state. The same device record can later be used by an SDK or MQTT client after the browser session is disconnected and the device-side client is configured and started explicitly.

After it connects, the status panel shows:

• Device status
• Current data
• Available actions
• Latest reported events

4. Control the Device and Query Status and Events

Keep the browser-connected device selected, then enter this control request in the chat box:

Set the target temperature to 24 degrees and switch to auto mode.

The Device Agent uses the current DeviceSpec and selected device context to call the matching commands. After the browser simulator receives them, it applies the generated simulation behavior. Commands with a state mapping update current data and continue reporting it. In this example, commands with explicitly empty effects succeed without changing state, while commands without declared behavior return unsupported.

You can then query the current device status and recent events:

Show the current device status, including current temperature, target temperature, humidity, and mode. Also check whether there have been any recent reported events, and list them by time if available.

Check whether target_temperature and mode changed in the status panel. The simulator does not generate threshold or offline events automatically. To test a modeled event, use Simulator report → Emit event as described in Device Simulator. Until an event is reported, the conversation returns that no events are available.

Result

After completing the steps above, you have verified several core Device Agent capabilities:

• Generate a Device Agent draft from a text, JSON, YAML, or Markdown device description.
• Review commands, properties, and events in the DeviceSpec.
• Create a normal device record and connect it to the browser simulator.
• Send a device control command and query device status and events through conversation.

Next Steps

• Read Define a Device Agent to understand how Device Agents, DeviceSpec, and real devices relate.
• Read MQTT Access to connect real devices to Device Agent.
• Read SDK Access to generate or adapt a device-side access project.