Define a Device Agent

A Device Agent represents a device category, not one physical device. It defines actions, state, and events, then provides the shared basis for conversation, device access, simulation, SDKs, and many bound devices with separate IDs, status, properties, and history.

Core Concepts

• Device Agent: the user-facing and integration-facing agent entry point. It understands conversations, selects devices, invokes commands, and queries status.
• Device model: The native capability definition for the selected access option. Devices managed directly by Device Agent use DeviceSpec; an existing IoT platform retains its own model.
• Device records: separately identified instances under the Device Agent. A record can be used by a temporary browser simulator session or by an explicitly configured SDK or MQTT client; physical hardware and business logic run on the device side.

Confirm the access option

Before modeling, decide whether devices will use an existing IoT platform or connect through SDK / MQTT. Configure Settings → Platform Access → IoT Platform, then use that platform's modeling rules.

Provide an existing native model with the device description when available. Keep identifiers, access constraints, and service semantics. Natural-language modeling generates and validates the selected platform's format. For synchronized Agents, use the platform's management and synchronization process to keep local and remote definitions consistent. See IoT Platform Integration.

Preserve native fields and constraints

Native models can contain structured fields, arrays, enums, and value constraints. Support depends on the IoT platform. When providing an existing model, describe each field's purpose and preserve:

• Structures and arrays: child field names, item types, and nesting, such as voltage, temperature, and a list of cells within a battery pack.
• Enums: stored values and display labels, such as 0 for standby and 1 for running. Keep protocol values consistent when changing labels.
• Constraints: read/write access, required fields, units, minimum and maximum values, and step sizes, so generated operations match what the device accepts.

Review these definitions in the capability preview. The model, simulation behavior, and SDK should use the same field meanings. Update device implementation when changing its protocol. The DeviceSpec type table below applies to devices managed directly by Device Agent; existing platforms retain their native model type rules.

Creation Entry Points

If there are no Device Agents yet, the console home page shows the creation input directly. You can enter a device description or upload an existing device definition file.

If you already have Device Agents, start a new creation flow from either entry point:

• Click the + button in the left sidebar
• Click Create device agent on the home page

The device description can be natural language, or any text content that describes device capabilities in a structured way, such as Markdown, JSON, or YAML. View examples is only a reference entry point; you can use your own description or a full native device model.

Click View examples to open the examples panel. Examples are grouped by device scenario. When you select one, a reference description is inserted into the input box; revise it before sending so it matches your own device.

The Energy category includes photovoltaic inverter and energy storage references:

Example	Capabilities to use as a reference
Photovoltaic inverter	Grid connection, power limits, operating modes, and reports for generation, grid measurements, and temperature
Energy storage	Operating modes, charging and discharging, power limits, reserve capacity, and reports for battery charge, health, and temperature

After selecting a reference, add the device's actual parameters, units, bounds, and events. For example, off-grid support and permitted charging power depend on the storage device's capabilities.

Send the device description to the creation agent, then review or refine the generated model.

Describe Capabilities

When defining a device, describe the capabilities in this order:

1. What the device is: device category, scenario, and main goal.
2. What commands it supports: user- or agent-invoked operations and their parameters.
3. What properties it reports: state fields to monitor, with reasonable initial values.
4. What events it emits: business changes, alerts, or faults, plus event payload fields.
5. Preferred field names: expected identifiers if you already have a device protocol or MQTT plan.

For example:

Define a smart thermostat. It supports power control, target temperature setting, and mode switching.
Supported modes are heat, cool, auto, fan_only, and eco.
It reports current temperature, target temperature, humidity, current mode, heating state, cooling state, and online state.
It emits an over_temperature alert when temperature is above 30 C, and a device_offline error event when the device goes offline.
Use lowercase English identifiers with underscores for commands, property fields, and events.

You can also upload a complete JSON or YAML DeviceSpec; see the DeviceSpec model example for its format. Prefer lowercase English identifiers with underscores, such as set_target_temperature, current_temperature, and device_offline. This makes MQTT access, SDK code, and device-side implementation more stable.

Generate and Review

After you send the description, the creation agent generates a device model draft. Use the conversation area on the left to refine it, and the preview panel on the right to review commands, properties, and events.

The Workspace AI flow generates browser simulation behavior separately alongside each valid device model revision. If you ask it to change and regenerate the capability model, the behavior is regenerated against that new model before the result can be saved.

Review the draft with these checks:

• Commands cover the operations users need to perform
• Command parameters include type, required, and clear description
• Properties cover the state the device should report or expose for queries
• Property defaultValue values match their field types
• Events cover exceptions or business changes that should be reported proactively
• Events use the right eventType and outputData
• Field names are stable enough for MQTT access and SDK access

If the draft does not match your intent, continue editing from the left conversation area:

Rename the temperature command to set_target_temperature, use value as the parameter name, and add a device_offline event with eventType set to error.

If the selected model returns malformed structure, the preview panel shows validation issues. You can click auto repair to have the creation agent fix the device model from those validation results, or continue refining it in the conversation area on the left.

Review simulation behavior

In the Simulator behavior preview, check the expected result for each action:

Preview	Meaning	What to check
State updates	Writes a parameter, fixed value, or mapped value to a state field	The parameter, destination field, and value match the device's meaning
No state change	Runs the action without updating simulated state	Queries, self-tests, or other actions should leave state unchanged
Unspecified	No simulated state change is defined; the current access option determines the result	Define the action-to-state relationship when a state change needs testing

For example, setting a target temperature should update that field, while querying temperature should leave state unchanged.

If the result differs from your intent, describe the expected effect in the creation conversation. For validation errors, click Repair simulator behavior, review the result, and save.

After saving, use the Device Simulator to test the action and its state report. Simulation validates interactions; real devices still need to implement the actions.

Set Version, Persona, and A2A

In the preview panel, you can also configure:

• Version: used for device and SDK compatibility checks, with a format such as 1.0, 1.1, or 2.0.3
• Persona: sets reply style, such as "warm, concise, lead with the answer." It affects tone only and does not change the device model or command permissions.
• A2A collaboration: uses the EMQX 6.2 A2A over MQTT capability to publish this Device Agent as a node that other A2A agents can discover and call

When A2A is enabled, the system generates a card and skills from capabilities publishable through the current access option. Check the card for the actual skills. Enable A2A when this Device Agent needs to collaborate with other A2A agents over MQTT. Published cards update when saving the model or synchronizing the platform changes capabilities; inspect the latest skills in the A2A workspace. See A2A Multi-Agent Collaboration for the usage flow.

Confirm that the model can generate callable A2A skills before publication. Follow the page guidance when no skills are available.

During creation, the system also selects a suitable sidebar icon based on the device model. If no reliable result is available, it uses the default icon.

Open the Device Agent

When the draft looks correct, click Create. The Device Agent appears in the left sidebar. Click Enter Agent, or open it from the Device Agent list.

Inside the Device Agent, you can:

• Select or connect devices accessible through the adapter, using approved test records for simulation
• Configure and run SDK or MQTT clients for one or more device records
• Send commands to the selected device through conversation
• Query the current device status and recent events
• Generate or adapt a device-side SDK and connect real hardware

Conversation uses the current device model and selected device. For example, when a user says "set the target temperature to 24 degrees", the Device Agent selects the matching command and generates the parameters. When the user asks for status or events, it reads the selected device's latest reported data.

DeviceSpec model example

The following DeviceSpec example applies to devices managed directly by Device Agent. Existing IoT platforms retain their native models and do not need to adopt this structure.

The top-level DeviceSpec structure is fixed: name, description, commands, properties, and events.

{
  "name": "SmartThermostat",
  "description": "A thermostat that controls temperature, switches modes, reports state, and emits alerts.",
  "commands": {
    "set_target_temperature": {
      "description": "Set the target temperature.",
      "parameters": {
        "value": {
          "type": "float",
          "description": "Target temperature in Celsius.",
          "required": true
        }
      }
    }
  },
  "properties": {
    "current_temperature": {
      "type": "float",
      "description": "Current room temperature in Celsius.",
      "defaultValue": 26
    },
    "target_temperature": {
      "type": "float",
      "description": "Configured target temperature in Celsius.",
      "defaultValue": 24
    }
  },
  "events": {
    "over_temperature": {
      "description": "Reported when the current temperature is above the safe threshold.",
      "eventType": "alert",
      "outputData": {
        "current_temperature": {
          "type": "float",
          "description": "Temperature that triggered the alert.",
          "required": true
        }
      }
    }
  }
}

Top-level fields:

Field	Description
name	Device Agent name. Use a stable, short English identifier.
description	Device Agent description used to help the model understand the scenario.
commands	Operations the device can execute.
properties	State fields the device reports or exposes for status queries.
events	Structured events reported by the device.

DeviceSpec field types

Command parameters, property fields, and event payload fields use the same type set:

Type	Usage	Example value
string	Text, status names, mode names	"warm", "idle"
int	Integer values, such as counts and levels	80, 0
float	Decimal or measured values, such as temperature, voltage, power, and ratios	22.5
bool	Switches, online state, enabled flags	true, false
json	Structured objects, such as coordinates, zones, and complex configuration	{ "mode": "eco" }
array	Lists, such as detection results or history records	["a", "b"]
enum	A string from the required enum list	"auto"

Use these exact type names in DeviceSpec JSON. Numeric enums use int or float with an enum list of matching numeric values. string can also declare an enum list. A description of allowed values alone does not enforce them.

DeviceSpec supports type, description, and enum; command and event fields also require required, and properties can include defaultValue. It does not accept native-platform fields such as min, max, step, read/write flags, or nested field schemas. For devices managed directly by Device Agent, describe additional limits for the Agent and enforce them in device code. Existing platforms retain their supported native constraints.

Events use eventType:

Type	Usage
info	Normal notifications or business state changes
alert	Alerts that need attention
error	Faults, offline events, execution failures, or other errors

DeviceSpec commands, properties, and events

Commands are actions the device can receive. Each command contains description and parameters. When a command is invoked, parameters are validated against the DeviceSpec. Missing required parameters, type mismatches, and unknown parameters are treated as invalid for the current spec.

{
  "set_mode": {
    "description": "Switch HVAC mode.",
    "parameters": {
      "mode": {
        "type": "string",
        "description": "One of heat, cool, auto, fan_only, eco.",
        "required": true,
        "enum": ["heat", "cool", "auto", "fan_only", "eco"]
      }
    }
  }
}

Properties define the state the device reports continuously or exposes for status queries. defaultValue is optional, but recommended for simulator and SDK examples. It must match the field type and any declared enum values.

{
  "humidity": {
    "type": "int",
    "description": "Current humidity percentage.",
    "defaultValue": 60
  }
}

Events are one-time changes reported by the device. Each event contains description, eventType, and outputData. Event names and payload fields are also validated against the DeviceSpec.

{
  "device_offline": {
    "description": "Reported when the device goes offline.",
    "eventType": "error",
    "outputData": {
      "reason": {
        "type": "string",
        "description": "Offline reason.",
        "required": false
      }
    }
  }
}

Next Steps

• Read Device Simulator to validate interactions without real hardware.
• Read MQTT Access to connect real devices to Device Agent.