Skip to main content
connic
Connectors

MQTT

Start agents from messages on MQTT topics, or publish run results to a topic on an MQTT 5 broker.

Last updated
ModesInbound, outbound
YAML typemqtt
ProtocolMQTT 5
CredentialsA Connection of type mqtt with the host, the optional user, and the TLS settings, including a client certificate for mutual TLS
BridgeOn the Connection, to reach a broker in a private network
Custom domainNot supported
Linked agentsOne or more. A message starts every linked agent.
While pausedInbound: connic disconnects, and the broker keeps QoS 1 messages in the session until you resume or the session expires. Outbound: nothing is published.
New connectorsInbound 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

connectors/plant-alarms.yaml
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-triage
connectors/line-commands.yaml
type: 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.

FieldTypeStatusDescription
typestringRequiredmqtt.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredName or ID of a Connection of type mqtt, which holds the host, the credentials, TLS, and the Bridge. See Connection. Dashboard: Connection.
configobjectRequiredMQTT settings.
topic_filterstringRequiredInbound. 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_fieldstringOptionalInbound. 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.
topicstringRequiredOutbound. The topic that results are published to. It can't contain wildcards. Dashboard: Topic.
qosintegerOptional0 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
retainbooleanOptionalOutbound. The broker keeps the last published result on the topic and sends it to new subscribers. Dashboard: Retain.Default: false
client_idstringOptionalThe 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.

FieldTypeStatusDescription
hoststringRequiredHostname or IP address of the broker. Without a Bridge, it must resolve only to public IP addresses. Dashboard: Host.
portintegerOptionalMQTT port. Without one, connic uses 8883 with TLS and 1883 without. Dashboard: Port.
usernamestringOptionalThe MQTT user. Leave it empty when the broker authenticates the client certificate alone. Dashboard: Username.
passwordstringOptionalThe user's password. Secret. Dashboard: Password.
use_tlsbooleanOptionalConnect over TLS and check the broker's certificate and hostname. Dashboard: Use TLS.Default: true
ssl_ca_pemstringOptionalWith 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_pemstringOptionalWith TLS. Client certificate in PEM format for mutual TLS. Set it together with ssl_key_pem. Secret. Dashboard: SSL Client Certificate PEM.
ssl_key_pemstringOptionalWith TLS. Private key of the client certificate in PEM format, unencrypted. Secret. Dashboard: SSL Client Key PEM.
bridgestringOptionalName 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:

payload.json
{
  "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:

agents/alarm-triage.yaml
concurrency:
  key: machine
  on_conflict: queue

Runs 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:

payload.json
{
  "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.

connector-payload.json
{
  "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:Connect on client/<Client ID> for an inbound connector and on client/<Client ID>-* for an outbound one, plus iot:Subscribe and iot:Receive on the topics, or iot: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_field so 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

SituationWhat happens
A payload isn't valid UTF-8connic acknowledges the message without starting a run and records a failed connector run.
Storing a run failsFor 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 startOnce 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 matchconnic 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 linkedconnic acknowledges each message without starting a run and records it as a connector run with No agents linked.
The broker or the network failsThe subscriber reconnects with exponential backoff, from 5 seconds up to 2 minutes.
Login, certificate, client ID, or subscription is refusedThe 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 IDThe 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.