MQTT
Connects to an MQTT broker for publishing and subscribing to topics. An agent can publish messages, subscribe and collect messages over a time window, and ping the broker to check connectivity.
Add to an agent node's tools array with _node_type: "tool-mqtt". See Connector Reference — How connectors are used.
Authentication
| Field | Required | Description |
|---|---|---|
broker | Yes | MQTT broker URL, e.g. tcp://localhost:1883 or ssl://broker:8883. |
client_id | No | MQTT client ID (default: goagents-tool). |
username | No | Username for broker authentication. |
password | No | Password for broker authentication. |
tls_skip | No | Set to "true" to skip TLS certificate verification (for self-signed certs). |
{
"name": "mqtt",
"_node_type": "tool-mqtt",
"broker": "ssl://broker.example.com:8883",
"username": "{{ secret.MQTT_USERNAME }}",
"password": "{{ secret.MQTT_PASSWORD }}"
}
Tools
mqtt_publish
Publish a message to an MQTT topic.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
topic | string | Yes | MQTT topic path (e.g. sensors/temp) |
payload | string | Yes | Message payload (string or JSON) |
qos | number | No | Quality of service: 0 at-most-once, 1 at-least-once, 2 exactly-once |
retain | boolean | No | Whether the broker should retain this message for new subscribers |
Returns: A confirmation message, e.g. "published <N> bytes to <topic> (qos=<N>)".
mqtt_subscribe
Subscribe to an MQTT topic and collect messages for a given duration.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
topic | string | Yes | MQTT topic filter (supports wildcards # and +) |
duration_ms | number | No | How long to listen in milliseconds (default 3000) |
limit | number | No | Stop after this many messages (default 20) |
qos | number | No | Subscription QoS (0, 1, or 2) |
Returns: A JSON object string with messages (array of {topic, payload, qos, retained}), count, and topic.
mqtt_ping
Ping the MQTT broker to verify connectivity.
No parameters.
Returns: A confirmation message, e.g. "ok — broker reachable in <N>ms".