Connect EMQX Agents to EMQX Broker

The EMQX Broker connector lets an agent receive MQTT messages as event triggers and publish MQTT messages as actions. Use this connector for telemetry processing, anomaly detection, alert routing, and device command workflows.

Common Use Cases

• Trigger an agent when device telemetry arrives on an MQTT topic.
• Analyze telemetry and publish an alert to another MQTT topic.
• Route normalized messages between topic namespaces.
• Publish a device command after evaluating external data.

Example chat prompt:

Use the factory-broker connector. Trigger the agent when a message arrives on devices/+/telemetry. If the temperature is above 80, publish a JSON alert to alerts/temperature with QoS 1.

Prerequisites

Before adding the connector, prepare:

• The MQTT broker address and listener port.
• A username and password if the broker requires authentication.
• The TLS setting required by the listener.
• The MQTT topic filters that the agent can subscribe to.
• The concrete MQTT topics that the agent can publish to.

Add an EMQX Broker Connector

1. In the left navigation menu, click Connectors.
2. On the Available tab, locate EMQX Broker 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 Broker.
Name	Yes	A display name, such as factory-broker. The name must start with a letter and can contain letters, numbers, hyphens, and underscores, up to 64 characters.
Address	Yes	The broker address in host:port format. Include the port, such as broker.example.com:1883 for MQTT or broker.example.com:8883 for MQTT over TLS.
Username	No	The username used to authenticate with the broker.
Password	No	The password used to authenticate with the broker.
Client ID Prefix	No	A prefix applied to MQTT client IDs created by this connector. Use a recognizable prefix when you need to identify agent connections in broker logs.
Enable TLS/SSL	No	Enables TLS for the connection. Disabled by default.
Default QoS	No	The default MQTT QoS for subscriptions and publications. Available values: 0, 1, and 2. Default: 1.

Edit an EMQX Broker Connector

1. On the Added tab, click the edit icon for the EMQX Broker connector.
2. If the connector is not used by a deployed agent, update any of the following fields in the Edit Connector panel:
   • Name
   • Address
   • Username
   • Password
   • Client ID Prefix
   • Enable TLS/SSL
   • Default QoS
3. If the connector is used by a deployed agent, update only Name.
4. Click Confirm.

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

Important Notice

Do not change the address, credentials, TLS setting, client ID prefix, or default QoS of a connector used by a deployed agent, even if a field is currently enabled. The Console rejects an address change with the message connector is used by deployed agents: <agent-id>.

Supported Trigger and Tool

MQTT Subscription Trigger

The mqtt.subscribe trigger starts an agent run when a message matches the configured topic filter.

Document the following values in the chat prompt:

• Connector name.
• MQTT topic filter.
• QoS.
• Expected payload format.

MQTT subscription topic filters can contain + and # wildcards. Use the narrowest topic filter that satisfies the workflow.

MQTT Publish Tool

The mqtt.publish tool publishes a message to an allowed MQTT topic through the connector.

The generated agent definition restricts publishing to explicitly allowed topics. MQTT publish topics must be concrete topic names and cannot contain wildcards.

Important Notice

Avoid broad subscriptions such as # and broad publish permissions unless the workflow requires them. Broad topic access can expose unrelated device data or allow unintended publications.

Permissions and Security

• Configure broker authentication and authorization so the connector can access only the required topics.
• Use a separate MQTT user for agent workflows when possible.
• Do not include the broker username or password in the chat prompt.
• Use TLS when the broker is accessed over an untrusted network.

Limitations

• Broker authentication and authorization rules can reject subscriptions or publications even when the connector is configured successfully.
• Network or TLS errors prevent the trigger and publish tool from reaching the broker.
• The connector does not replace MQTT topic authorization configured on the broker.

Troubleshooting

Symptom	Resolution
The connector cannot connect to the broker.	Verify the address, port, TLS setting, listener availability, and network access.
MQTT authentication fails.	Verify the username and password in the connector and the authentication configuration on the broker.
A subscription receives no messages.	Verify the topic filter, QoS, and broker authorization rules.
The agent cannot publish.	Verify that the target topic is included in the generated agent's allowed topics and permitted by broker authorization.

Related Links

• Connectors
• Start a Chat
• Manage Agents