MQTT
Start agents from messages on MQTT topics, or publish run results to a topic on an MQTT 5 broker.
On this page
| Modes | Inbound, outbound |
| YAML type | mqtt |
| Protocol | MQTT 5 |
| Credentials | A Connection of type mqtt with the host, the optional user, and the TLS settings, including a client certificate for mutual TLS |
| Bridge | On the Connection, to reach a broker in a private network |
| Custom domain | Not supported |
| Linked agents | One or more. A message starts every linked agent. |
| While paused | Inbound: connic disconnects, and the broker keeps QoS 1 messages in the session until you resume or the session expires. Outbound: nothing is published. |
| New connectors | Inbound connectors are created paused in the dashboard, and through the REST API or connic MCP unless the request sets enabled: true. Start them with Resume. Connectors in code start active. |
Set up
Allow connic on the broker. The broker must speak MQTT 5. Give the user or the client certificate permission to subscribe to the topic filter for inbound, or to publish to the topic for outbound. If the broker restricts client IDs, allow the connector's Client ID; see Client ID.
Open the agent. In Connector Flow, click Add inbound connector for inbound or Add outbound connector for outbound. Then click Create New Connector and select MQTT.
Choose Inbound (Subscriber) or Outbound (Publisher). Under Connection, pick a saved Connection or create one with the host, the user or client certificate, and the TLS settings; see Connection. If the broker is in a private network, select the Bridge in the Connection.
For inbound, enter the Topic Filter and optionally a Message ID Field. For outbound, enter the Topic and choose whether to Retain results. Both modes take a QoS and an optional Client ID.
Click Create. A new inbound connector is paused: click Resume in its details drawer to subscribe. To reopen the drawer, hover over the connector in the flow and click the eye icon.
In code
Declare the connector in connectors/*.yaml. The file names the Connection and never contains broker credentials. Connectors in code start active, so an inbound connector subscribes when its first deploy goes live.
type: mqtt
mode: inbound
connection: plant-broker # Connection with the host, credentials, TLS, and optional Bridge
config:
topic_filter: factory/+/alarms
qos: 1
message_id_field: message_id
agents:
- alarm-triagetype: mqtt
mode: outbound
connection: plant-broker
config:
topic: factory/line-1/commands
qos: 1
retain: false
agents:
- name: alarm-triage
outbound: { usage: automatic }Configuration
The fields of an MQTT connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | mqtt. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Name or ID of a Connection of type mqtt, which holds the host, the credentials, TLS, and the Bridge. See Connection. Dashboard: Connection. |
| config | object | Required | MQTT settings. |
| topic_filter | string | Required | Inbound. The topics to subscribe to. + matches one topic level and # all remaining levels; each wildcard fills a whole level. Shared subscriptions ($share/) are rejected, since connic runs one subscriber per connector. Dashboard: Topic Filter. |
| message_id_field | string | Optional | Inbound. The name of an MQTT 5 user property, or else of a top-level JSON key in the payload, that carries a unique message ID. See Delivery and ordering. Dashboard: Message ID Field. |
| topic | string | Required | Outbound. The topic that results are published to. It can't contain wildcards. Dashboard: Topic. |
| qos | integer | Optional | 0 delivers at most once, 1 at least once. Inbound, it is the highest QoS the broker delivers with; outbound, the QoS of every published message. Dashboard: QoS.Default: 1 |
| retain | boolean | Optional | Outbound. The broker keeps the last published result on the topic and sends it to new subscribers. Dashboard: Retain.Default: false |
| client_id | string | Optional | The MQTT client ID. Leave it empty and connic generates connic- followed by 16 hex characters. It stays the same when you update the connector. Dashboard: Client ID. |
Connection
A Connection of type mqtt holds these fields. Every MQTT connector in the project can use it, and a connector's config doesn't take them. Manage Connections in Project Settings → Connections or through the REST API.
| Field | Type | Status | Description |
|---|---|---|---|
| host | string | Required | Hostname or IP address of the broker. Without a Bridge, it must resolve only to public IP addresses. Dashboard: Host. |
| port | integer | Optional | MQTT port. Without one, connic uses 8883 with TLS and 1883 without. Dashboard: Port. |
| username | string | Optional | The MQTT user. Leave it empty when the broker authenticates the client certificate alone. Dashboard: Username. |
| password | string | Optional | The user's password. Secret. Dashboard: Password. |
| use_tls | boolean | Optional | Connect over TLS and check the broker's certificate and hostname. Dashboard: Use TLS.Default: true |
| ssl_ca_pem | string | Optional | With TLS. CA certificate in PEM format for a broker whose certificate isn't from a public CA. Paste the contents, not a file path. Secret. Dashboard: SSL CA Certificate PEM. |
| ssl_cert_pem | string | Optional | With TLS. Client certificate in PEM format for mutual TLS. Set it together with ssl_key_pem. Secret. Dashboard: SSL Client Certificate PEM. |
| ssl_key_pem | string | Optional | With TLS. Private key of the client certificate in PEM format, unencrypted. Secret. Dashboard: SSL Client Key PEM. |
| bridge | string | Optional | Name or ID of the Bridge that reaches a broker in a private network. TLS still checks the certificate against the host. The REST API and connic MCP take it as the Connection's top-level bridge, not in config. Dashboard: Bridge. |
Every connector that uses the Connection goes through its Bridge. To use a different Bridge per environment, give each environment its own Connection; see Connections and Bridges. When you change the host, port, user, TLS, or Bridge of a saved Connection, enter the password again; when you change the host, port, TLS, or Bridge, enter the CA certificate, the client certificate, and its key again too. connic refuses the change otherwise.
Client ID
An inbound connector connects with its Client ID, and the broker keeps the connector's session under it. An outbound connector opens a connection for every publish, with the Client ID followed by a hyphen and 8 random hex characters, so publishes that run at the same time never take over each other's session.
A broker hands a session to the newest connection with its client ID and disconnects the older one. Give every connector its own Client ID, and don't reuse it in other clients. If the broker only allows certain client IDs, allow the Client ID itself for an inbound connector and every ID that starts with the Client ID and a hyphen for an outbound connector.
Agent input
Modes: Inbound
Each message becomes the input of every linked agent. A JSON object keeps its fields, and connic adds the message details under _mqtt:
{
"machine": "press-4",
"alarm": "overtemperature",
"value": 92.5,
"_mqtt": {
"topic": "factory/line-1/alarms",
"qos": 1,
"retain": false,
"duplicate": false,
"user_properties": { "message_id": "press-4-1731840000" },
"content_type": "application/json"
}
}_mqtt holds the topic the message was published to, the qos it was delivered with, retain, which is true for a retained message the broker sent when the subscription was new, duplicate, which is true when the broker sent the message before, the MQTT 5 user_properties as an object, and the content_type property, or null without one.
Any other payload is wrapped under message: other JSON values as parsed, text that isn't JSON as a string, and an empty payload as null. Binary payloads that aren't valid UTF-8 start no run; see Limits and errors.
A JSON object can carry files in a files array. Each file has a name, a mime_type, and base64-encoded data. connic accepts up to 50 complete files, at most 32 MiB combined, within the broker's message size limit. Invalid files are omitted one by one. At the first file over a limit, connic keeps the files before it and accepts no further files. Each omitted file is described in file_issues, and the run continues without it.
Topic filters and sessions
Modes: Inbound
Each inbound connector subscribes to one topic filter. To start agents from several filters, create one inbound connector per filter and link them to the same agent; _mqtt.topic tells the events apart. Every connector gets every matching message, so two connectors whose filters overlap both start runs for the same message.
connic keeps a persistent session on the broker: it connects with Clean Start 0 and asks for a session that lasts one day after a disconnect. Brokers can grant less. While connic is disconnected, after a restart or while the connector is paused, the broker keeps the QoS 1 messages for the subscription and sends them when connic reconnects. QoS 0 messages published in that time are lost. When the session expires, the broker drops it with its messages, and connic starts a new one on the next connect.
Retained messages arrive once, when the subscription is new. A reconnect to an existing session doesn't send them again.
When you change the topic filter, connic subscribes to the new one, but the old subscription stays in the session until it expires. connic acknowledges the messages it brings without starting runs. To end the old subscription right away, change the Client ID too, which starts a new session.
Deleting a connector doesn't delete its session on the broker; the broker drops it when it expires.
Delivery and ordering
Modes: Inbound
connic acknowledges a QoS 1 message with PUBACK once it has stored a queued run for every linked agent, before those runs execute. Stored runs survive worker restarts and deployments. If storing a run fails, connic closes the connection without acknowledging the message, and the broker sends it again after the reconnect. connic only sends successful PUBACKs. QoS 0 messages need no acknowledgement.
With a message_id_field, connic identifies a message by the value of that user property, or of that top-level JSON key when the message has no such user property. A message with an ID that already started a run for an agent on the same topic starts no new run for it, however and whenever the broker delivers it. Give every message on a topic its own ID: two different messages with the same ID on one topic start one run per agent.
Without a message_id_field, or for a message that doesn't carry the field, connic remembers each QoS 1 message it hasn't acknowledged yet. When the broker sends it again in the same session after a failure, it reuses the stored run. Identical messages always start their own runs. Only if the subscriber restarts between storing the runs and acknowledging the message can a resent message start a second run.
A run that fails after it was stored causes no redelivery. The failed run keeps its full input, so you can rerun it. Retries inside a run follow the agent's retry_options.
connic handles messages one after another in the order they arrive. Runs are stored in that order but execute in parallel up to max_concurrent_runs. For ordering by a field, such as a machine ID, add a concurrency rule on it:
concurrency:
key: machine
on_conflict: queueRuns with the same value then start one at a time in arrival order, while different values still run in parallel. A failed run releases its value, so the next message with it still runs.
Outbound delivery
Modes: Outbound
An outbound MQTT connector publishes JSON messages to its topic with its QoS and retain flag. It publishes when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage.
Automatic payload
An automatic link publishes the completed run as the message payload:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "alarm-triage",
"status": "completed",
"output": "press-4: stop the line and send maintenance.",
"error": null,
"started_at": "2026-01-15T10:30:00Z",
"ended_at": "2026-01-15T10:30:05Z",
"token_usage": {
"input_tokens": 150,
"output_tokens": 50,
"thinking_tokens": 0,
"cached_input_tokens": 0,
"total_tokens": 200
}
}To build a pipeline, link an inbound MQTT connector and an automatic outbound MQTT connector to the same agent; the agent's output arrives in output. Automatic sources describes which runs publish. A run that middleware ends with StopProcessing counts as completed and publishes the StopProcessing response as its output, unless it is raised with publish_outbound=False. That flag doesn't undo an agent-tool or middleware call made earlier in the run.
Agent-tool and middleware payload
The model or middleware passes the message payload under payload and can add MQTT 5 user properties with text values under user_properties. connic publishes the value of payload and adds the topic, QoS, retain flag, credentials, serialization, retries, and Bridge routing, none of which the model sees.
{
"payload": {
"machine": "press-4",
"command": "stop"
},
"user_properties": {
"priority": "high"
}
}Delivery and retries
Each message has a JSON payload, the content type application/json, and a message_id user property with the run ID. For a tool or middleware call, it is the payload's run_id field if it has one, otherwise an ID that stays the same across the delivery's retries. Consumers can use it to drop duplicates, and an inbound MQTT connector reads it with message_id_field: message_id.
With QoS 1, connic waits up to 30 seconds for the broker's PUBACK. Connection errors and unconfirmed messages are tried 3 times in total, waiting 1 and then 2 seconds between attempts. A refused login or a PUBACK with an error, such as a missing permission on the topic, fails at once. The connector's runs show each delivery and its error.
Broker differences
connic works with any MQTT 5 broker, such as Mosquitto 2, HiveMQ, or EMQX. Managed brokers set limits of their own.
AWS IoT Core
- Use the account's data endpoint as the host, port 8883, and the thing's certificate and private key in the Connection. Username and password stay empty.
- The IoT policy must allow
iot:Connectonclient/<Client ID>for an inbound connector and onclient/<Client ID>-*for an outbound one, plusiot:Subscribeandiot:Receiveon the topics, oriot:Publish. - QoS 0 and 1 only, and payloads up to 128 KB.
- Persistent sessions last one hour by default. The account quota raises it up to 7 days.
- AWS IoT Core can send a message again with a new packet ID and without the duplicate flag. Set a
message_id_fieldso such a message doesn't start a second run. - Retained messages reach only subscriptions to their exact topic, not wildcard filters.
Azure Event Grid
- Use the namespace's MQTT hostname and port 8883. The username is the client authentication name; with certificate authentication, add the client certificate and key to the Connection.
- A PUBACK with an error code closes the connection. connic never sends one.
- Sessions last one hour by default; the namespace setting raises it up to 8 hours. A session holds at most 100 messages or 1 MB while connic is disconnected, and the broker ends it when it overflows.
- QoS 0 and 1 only, and messages up to 1 MB.
Limits and errors
| Situation | What happens |
|---|---|
| A payload isn't valid UTF-8 | connic acknowledges the message without starting a run and records a failed connector run. |
| Storing a run fails | For a QoS 1 message, connic closes the connection without acknowledging it. The subscriber reconnects after a short delay, and the broker sends the message again. A QoS 0 message is recorded as a failed connector run and not sent again. |
| QoS 0 messages arrive faster than runs start | Once 100 messages are waiting, connic drops further QoS 0 messages. QoS 1 messages are never dropped; the broker sends them as connic acknowledges earlier ones. |
| A message arrives on a topic the filter doesn't match | connic acknowledges it without a run. Such messages come from a subscription that stayed in the broker session after the topic filter changed; see Topic filters and sessions. |
| No agent is linked | connic acknowledges each message without starting a run and records it as a connector run with No agents linked. |
| The broker or the network fails | The subscriber reconnects with exponential backoff, from 5 seconds up to 2 minutes. |
| Login, certificate, client ID, or subscription is refused | The subscriber stops and writes the broker's reason to the connector logs. It starts again when you update the connector or its Connection, or pause and resume it. |
| Another client connects with the same client ID | The broker hands the session to the newer connection and disconnects the older one. Give every connector its own Client ID. |
| Publishing fails (outbound) | Connection errors and messages the broker doesn't confirm get up to 3 attempts. A refused login, a missing permission on the topic, or a message the broker rejects fails at once. See Delivery and retries. |