Connect EMQX Agents to EMQX Fleets

The EMQX Fleets connector lets an agent work with the device registry, device shadows, commands, jobs, groups, tags, saved queries, and device searches. Use this connector to automate device operations and combine fleet state with MQTT or external service workflows.

Common Use Cases

• Find devices that match a saved query or tag.
• Read a device shadow before deciding whether to send a command.
• Update the desired shadow state for a group of devices.
• Create or inspect device jobs and their execution status.
• Combine device state with Slack, email, or ticketing notifications.

Example chat prompt:

Use the production-fleets connector to find devices tagged with cold-storage. Read their shadows and list devices whose reported temperature is above 8.

Prerequisites

Before adding the connector, prepare:

• The EMQX Fleets API endpoint.
• An API key and API secret.
• The Fleets deployment version and API permissions required by the workflow.
• The thing names, thing IDs, group IDs, tag names, or job IDs used by the workflow.

Add an EMQX Fleets Connector

1. In the left navigation menu, click Connectors.
2. On the Available tab, locate EMQX Fleets and click Add.
3. Configure the connector fields.
4. Click Confirm.
5. On the Added tab, verify that the connector appears in the list.

Field	Required	Description
Type	Yes	The selected connector type, EMQX Fleets.
Name	Yes	A display name, such as production-fleets.
API Endpoint	Yes	The Fleets API endpoint, such as https://example.fleets.mqttce.net:8443.
API Key	Yes	The API key used to authenticate with the Fleets API.
API Secret	Yes	The API secret used to authenticate with the Fleets API.
Timeout (seconds)	No	The request timeout. Default: 10 seconds.
Verify TLS/SSL Certificate	No	Verifies TLS certificates when connecting to the Fleets API. Enabled by default.

Edit an EMQX Fleets Connector

1. On the Added tab, click the edit icon for the EMQX Fleets connector.
2. Update any of the following fields in the Edit Connector panel:
   • Name
   • API Endpoint
   • API Key
   • API Secret
   • Timeout (seconds)
   • Verify TLS/SSL Certificate
3. Click Confirm.

The Type field is read-only and cannot be changed.

Supported Operations

The connector exposes Fleets operations through the fleets.tools provider.

Read Operations

• Check API health, version, and deployment overview.
• List and retrieve things, thing types, thing groups, group members, and tags.
• Read thing tags and device shadows.
• Search devices and list saved queries.
• List jobs, job executions, commands, and thing events.

Write Operations

• Create, update, or delete supported registry resources.
• Add or remove tags.
• Update or clear a desired device shadow.
• Send a command.
• Create, update, cancel, or delete jobs and job executions.

Approve Write Operations

Fleets write operations require explicit approval by default. Before executing a write operation:

1. Run the operation with dry_run=true, or call it without approval, to generate a planned_action without sending the request to EMQX Fleets.
2. Review the operation, target resources, and request body in planned_action.
3. Explicitly approve the planned operation.
4. Run the operation with approved=true to execute it.

When approval is required and has not been provided, the tool returns approval_required=true with the planned operation instead of sending the request.

Important Notice

Commands, shadow updates, registry changes, and job operations can affect devices or fleet state. Review the target devices and planned operation before approving the action.

Permissions and Security

• Use an API key limited to the required Fleets operations and resources.
• Do not include the API key or API secret in chat prompts or agent instructions.
• Resolve thing names and thing IDs carefully because Fleets operations can require different identifiers.
• Limit the number of target devices for write operations.

Limitations

• Available operations can depend on the Fleets deployment version and API key permissions.
• Saved queries and some global job execution routes might not be available to every deployment.
• The connector does not expose API key lifecycle, setup, certificate, listener, or device impersonation operations.

Troubleshooting

Symptom	Resolution
The connector cannot reach EMQX Fleets.	Verify the API endpoint, TLS verification setting, and network access.
The API returns an authentication or authorization error.	Verify the API key, API secret, and permissions.
A thing, group, or job is not found.	Verify whether the operation requires an ID or a name and resolve the resource before retrying.
An operation is unavailable.	Check the Fleets deployment version and API key permissions.

Related Links

• Connectors
• Start a Chat
• Manage Agents