Skip to main content
connic

MQTT

Every message from a device or machine on a matching topic starts an agent run, and results go back to a topic. connic keeps a persistent session, so the broker holds messages while connic is away.

Modes
Inbound, Outbound
Set up in
Dashboard or connectors/*.yaml
Documentation
MQTT docs
Publisher
By connic

Turn every message into an agent run

An inbound connector subscribes to a topic filter and starts each linked agent once per message, with the message as its input.

Wildcards in the filter
+ matches one topic level and # all remaining levels, so one connector can follow every line, machine or site.
JSON keeps its shape
A JSON object arrives with its top-level fields, plus _mqtt with the topic, QoS, retain flag and MQTT 5 user properties.
Text arrives as text
Any other UTF-8 payload arrives under message: other JSON values as parsed, plain text as a string.
message on factory/line-1/alarms
{
  "machine": "press-4",
  "alarm": "overtemperature",
  "value": 92.5
}
context["payload"]
{
  "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"
  }
}

Acknowledge each message after its runs are stored

connic sends the PUBACK for a QoS 1 message once a queued run exists for every linked agent, so a restart or a deploy doesn't drop work.

Persistent session
connic connects with Clean Start 0, so the broker keeps the subscription and its QoS 1 messages across reconnects and pauses.
One run per message
A message sent again reuses its stored run. A message ID field makes that hold even when the broker resends under a new packet ID.
Retained messages once
Retained messages arrive when the subscription is new, not again on every reconnect.
  1. Receive

    The broker delivers messages on matching topics, including the ones it held while connic was disconnected.

  2. Store

    connic stores a queued run for every linked agent. Stored runs survive worker restarts and deployments.

  3. Acknowledge

    connic sends the PUBACK. If storing a run fails, connic reconnects without it, and the broker sends the message again.

    PUBACK
  4. Run

    Runs execute in parallel up to max_concurrent_runs. A concurrency rule on a field such as the machine ID starts runs for the same value one at a time.

    concurrency.key: machine

Keep the subscriber next to your agents

Declare it as a YAML file in connectors/. Host, credentials and certificates live in a Connection, so the file names only the topic filter and its options. A subscriber declared in code starts when its deployment goes live.

TLS and client certificates
connic connects over TLS and checks the broker's certificate. Add a client certificate and key for brokers that authenticate devices by certificate, such as AWS IoT Core.
Brokers on the shop floor
Direct connections need a broker that resolves to public IP addresses. Reach a broker inside your plant network through a bridge.
connectors/plant-alarms.yaml
type: mqtt
mode: inbound
name: Plant alarms
connection: plant-broker
config:
  topic_filter: factory/+/alarms
  qos: 1
  message_id_field: message_id
agents:
  - alarm-triage
create: connectors/plant-alarms.yaml (mqtt)

Publish results to a topic

An outbound connector publishes each completed run to its topic with the QoS and retain flag you set, and waits for the broker's PUBACK with QoS 1.

Run ID as message ID
Each message carries the run ID in the message_id user property, so subscribers can drop duplicates after a retry.
User properties from the agent
Linked as an agent tool, the connector lets the model publish its own payload and add MQTT 5 user properties.
Retain for the latest state
With retain on, the broker keeps the last result and hands it to every new subscriber of the topic.
connectors/line-commands.yaml
type: mqtt
mode: outbound
name: Line commands
connection: plant-broker
config:
  topic: factory/line-1/commands
  qos: 1
  retain: false
agents:
  - name: alarm-triage
    outbound:
      usage: automatic
      source: [plant-alarms]
message on factory/line-1/commands (message_id = run_id)
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "alarm-triage",
  "status": "completed",
  "output": "press-4: reduce speed to 60% and send maintenance.",
  "error": null,
  "started_at": "2026-10-13T09:00:01Z",
  "ended_at": "2026-10-13T09:00:05Z",
  "token_usage": {
    "input_tokens": 512,
    "output_tokens": 31,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 543
  }
}

Where MQTT fits

Pick a setup to see which topic starts the run, what the agent receives and where the result goes.

Each alarm from the line starts a run, and the agent's decision goes back to the line's command topic.

PLC gateway
MQTT subscriber
alarm-triage
Command on factory/line-1/commands
context["payload"]
{
  "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"
  }
}
message on factory/line-1/commands
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "alarm-triage",
  "status": "completed",
  "output": "press-4: reduce speed to 60% and send maintenance.",
  "error": null,
  "started_at": "2026-10-13T09:00:01Z",
  "ended_at": "2026-10-13T09:00:05Z",
  "token_usage": {
    "input_tokens": 512,
    "output_tokens": 31,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 543
  }
}

A trailer reports a temperature above its limit, and the agent tells dispatch what to check.

Trailer telematics
MQTT subscriber
cold-chain-watch
Email to dispatch
context["payload"]
{
  "trailer": "TR-208",
  "temperature_c": 9.1,
  "limit_c": 7.0,
  "door_open": false,
  "_mqtt": {
    "topic": "fleet/TR-208/telemetry",
    "qos": 1,
    "retain": false,
    "duplicate": false,
    "user_properties": { "message_id": "TR-208-0931" },
    "content_type": "application/json"
  }
}
connector-payload.json
{
  "body": "Trailer TR-208 is at 9.1 °C, above the 7 °C limit. The door is closed, so the cooling unit needs a check.",
  "to": "dispatch@example.com",
  "subject": "TR-208 above temperature limit"
}

A pump reports rising vibration, and the agent publishes an inspection order for the maintenance system.

Pump sensors
MQTT subscriber
maintenance-planner
Order on maintenance/orders
context["payload"]
{
  "pump": "P-17",
  "vibration_mm_s": 11.4,
  "running_hours": 18240,
  "_mqtt": {
    "topic": "site-b/pumps/P-17/status",
    "qos": 1,
    "retain": false,
    "duplicate": false,
    "user_properties": { "message_id": "P-17-18240" },
    "content_type": "application/json"
  }
}
connector-payload.json
{
  "payload": {
    "pump": "P-17",
    "action": "schedule_inspection",
    "within_hours": 48
  },
  "user_properties": {
    "priority": "high"
  }
}

A zone reports high CO2, and the agent sets the ventilation for the occupancy it sees.

Building sensors
MQTT subscriber
climate-control
Setpoint on hq/hvac/commands
context["payload"]
{
  "zone": "floor-3-east",
  "co2_ppm": 1450,
  "occupancy": 38,
  "_mqtt": {
    "topic": "hq/hvac/floor-3-east",
    "qos": 1,
    "retain": false,
    "duplicate": false,
    "user_properties": { "message_id": "f3e-1102" },
    "content_type": "application/json"
  }
}
connector-payload.json
{
  "payload": {
    "zone": "floor-3-east",
    "ventilation_percent": 80
  }
}

MQTT FAQ

Add an MQTT connector in Inbound (Subscriber) mode, pick a Connection with your broker, enter a topic filter and link the agent. Connectors created in the dashboard start paused, so click Resume when you're ready. Each message on a matching topic then starts a run for every linked agent, with the topic and user properties under _mqtt.

Any broker that speaks MQTT 5, such as Mosquitto 2, HiveMQ, EMQX, AWS IoT Core or Azure Event Grid. connic connects over TLS by default, with a username and password, a client certificate, or both. A broker inside your network is reachable through a bridge.

connic keeps a persistent session on the broker, so the broker holds QoS 1 messages for it and sends them when connic reconnects, as long as the session hasn't expired. QoS 1 messages are acknowledged only after their runs are stored.

Not within the same session: connic reuses the run it stored for a message it hadn't acknowledged yet. Set a message ID field, a user property or a JSON key with a unique ID, and connic also recognizes messages the broker resends under a new packet ID, as AWS IoT Core can. The MQTT docs explain every case.