MQTT
Agenten durch Nachrichten auf MQTT-Topics starten oder Run-Ergebnisse auf einem Topic eines MQTT-5-Brokers veröffentlichen.
Auf dieser Seite
| Modi | Inbound, Outbound |
| YAML-Typ | mqtt |
| Protokoll | MQTT 5 |
| Zugangsdaten | Ein Kontozugang (Connection) vom Typ mqtt mit Host, optionalem Benutzer und TLS-Einstellungen, auch mit Client-Zertifikat für Mutual TLS |
| Bridge | Am Kontozugang, um einen Broker in einem privaten Netzwerk zu erreichen |
| Custom Domain | Nicht unterstützt |
| Verknüpfte Agenten | Einer oder mehrere. Jede Nachricht startet alle verknüpften Agenten. |
| Während der Pause | Inbound: connic trennt die Verbindung zum Broker, und der Broker hält QoS-1-Nachrichten in der Session, bis du fortsetzt oder die Session abläuft. Outbound: Es wird nichts veröffentlicht. |
| Neue Verbindungen | Inbound-Verbindungen legt das Dashboard pausiert an, ebenso die REST API und connic MCP, sofern die Anfrage nicht enabled: true setzt. Starte sie mit Resume. Verbindungen im Code starten aktiv. |
Einrichtung
Gib connic am Broker frei. Der Broker muss MQTT 5 sprechen. Erlaube dem Benutzer oder dem Client-Zertifikat für Inbound, den Topic-Filter zu abonnieren, für Outbound, auf dem Topic zu veröffentlichen. Lässt der Broker nur bestimmte Client IDs zu, erlaube die Client ID der Verbindung; siehe Client ID.
Öffne den Agenten. Klicke im Connector Flow für Inbound auf Add inbound connector oder für Outbound auf Add outbound connector. Klicke dann auf Create New Connector und wähle MQTT.
Wähle Inbound (Subscriber) oder Outbound (Publisher). Wähle unter Connection einen gespeicherten Kontozugang oder lege einen mit Host, Benutzer oder Client-Zertifikat und TLS-Einstellungen an; siehe Kontozugang. Liegt der Broker in einem privaten Netzwerk, wähle im Kontozugang die Bridge.
Gib für Inbound den Topic Filter und optional ein Message ID Field ein. Gib für Outbound das Topic ein und wähle, ob der Broker Ergebnisse behalten soll (Retain). Beide Modi nehmen eine QoS und optional eine Client ID.
Klicke auf Create. Eine neue Inbound-Verbindung ist pausiert: Klicke in ihrem Detailbereich auf Resume, damit connic das Topic abonniert. Den Detailbereich öffnest du wieder, indem du im Flow mit der Maus über die Verbindung fährst und auf das Augensymbol klickst.
Im Code
Deklariere die Verbindung in connectors/*.yaml. Die Datei nennt den Kontozugang und enthält nie Zugangsdaten für den Broker. Verbindungen im Code starten aktiv: Eine Inbound-Verbindung abonniert ihren Topic-Filter, sobald ihr erstes Deployment live geht.
type: mqtt
mode: inbound
connection: plant-broker # Kontozugang mit Host, Zugangsdaten, TLS und optionaler 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 }Konfiguration
Die Felder einer MQTT-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Felder, die alle Verbindungen teilen, etwa agents und environments, beschreibt Verbindungen im Code.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| type | string | Required | mqtt. |
| mode | string | Required | inbound oder outbound. Dashboard: Mode. |
| connection | string | Required | Name oder ID eines Kontozugangs vom Typ mqtt, der Host, Zugangsdaten, TLS und Bridge enthält. Siehe Kontozugang. Dashboard: Connection. |
| config | object | Required | MQTT-Einstellungen. |
| topic_filter | string | Required | Inbound. Die Topics, die connic abonniert. + steht für genau eine Topic-Ebene, # für alle restlichen Ebenen; jede Wildcard füllt eine ganze Ebene. Shared Subscriptions ($share/) lehnt connic ab, weil je Verbindung genau ein Subscriber läuft. Dashboard: Topic Filter. |
| message_id_field | string | Optional | Inbound. Der Name einer User Property von MQTT 5 oder, falls die Nachricht keine solche hat, eines JSON-Schlüssels auf oberster Ebene der Payload, der eine eindeutige Nachrichten-ID trägt. Siehe Zustellung und Reihenfolge. Dashboard: Message ID Field. |
| topic | string | Required | Outbound. Das Topic, auf dem connic Ergebnisse veröffentlicht. Es darf keine Wildcards enthalten. Dashboard: Topic. |
| qos | integer | Optional | 0 stellt höchstens einmal zu, 1 mindestens einmal. Bei Inbound ist es die höchste QoS, mit der der Broker zustellt, bei Outbound die QoS jeder veröffentlichten Nachricht. Dashboard: QoS.Default: 1 |
| retain | boolean | Optional | Outbound. Der Broker behält das zuletzt veröffentlichte Ergebnis auf dem Topic und schickt es an neue Abonnenten. Dashboard: Retain.Default: false |
| client_id | string | Optional | Die Client ID für MQTT. Bleibt das Feld leer, erzeugt connic connic- mit 16 Hex-Zeichen dahinter. Sie bleibt gleich, wenn du die Verbindung änderst. Dashboard: Client ID. |
Kontozugang
Ein Kontozugang vom Typ mqtt enthält diese Felder. Alle MQTT-Verbindungen des Projekts können ihn nutzen, und die config einer Verbindung nimmt die Felder nicht an. Verwalte Kontozugänge unter Project Settings → Connections oder über die REST API.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| host | string | Required | Hostname oder IP-Adresse des Brokers. Ohne Bridge muss er ausschließlich zu öffentlichen IP-Adressen auflösen. Dashboard: Host. |
| port | integer | Optional | MQTT-Port. Ohne Angabe nutzt connic 8883 mit TLS und 1883 ohne. Dashboard: Port. |
| username | string | Optional | Der MQTT-Benutzer. Bleibt leer, wenn der Broker allein das Client-Zertifikat prüft. Dashboard: Username. |
| password | string | Optional | Das Passwort des Benutzers. Secret. Dashboard: Password. |
| use_tls | boolean | Optional | Verbindet über TLS und prüft Zertifikat und Hostnamen des Brokers. Dashboard: Use TLS.Default: true |
| ssl_ca_pem | string | Optional | Mit TLS. CA-Zertifikat im PEM-Format für einen Broker, dessen Zertifikat nicht von einer öffentlichen CA stammt. Füge den Inhalt ein, keinen Dateipfad. Secret. Dashboard: SSL CA Certificate PEM. |
| ssl_cert_pem | string | Optional | Mit TLS. Client-Zertifikat im PEM-Format für Mutual TLS. Nur zusammen mit ssl_key_pem. Secret. Dashboard: SSL Client Certificate PEM. |
| ssl_key_pem | string | Optional | Mit TLS. Unverschlüsselter privater Schlüssel des Client-Zertifikats im PEM-Format. Secret. Dashboard: SSL Client Key PEM. |
| bridge | string | Optional | Name oder ID der Bridge, über die connic einen Broker in einem privaten Netzwerk erreicht. TLS prüft das Zertifikat weiterhin gegen den Host. REST API und connic MCP nehmen sie als bridge auf oberster Ebene des Kontozugangs an, nicht in config. Dashboard: Bridge. |
Jede Verbindung, die den Kontozugang nutzt, geht über seine Bridge. Für eine andere Bridge je Environment gibst du jedem Environment einen eigenen Kontozugang; siehe Kontozugänge und Bridges. Änderst du bei einem gespeicherten Kontozugang Host, Port, Benutzer, TLS oder Bridge, gib das Passwort erneut ein. Bei Host, Port, TLS oder Bridge gilt das auch für CA-Zertifikat, Client-Zertifikat und Schlüssel. Sonst lehnt connic die Änderung ab.
Client ID
Eine Inbound-Verbindung meldet sich mit ihrer Client ID an, und der Broker führt die Session der Verbindung unter dieser ID. Eine Outbound-Verbindung baut für jede Veröffentlichung eine eigene Verbindung zum Broker auf, mit der Client ID, einem Bindestrich und 8 zufälligen Hex-Zeichen. So übernehmen gleichzeitige Veröffentlichungen nie gegenseitig ihre Session.
Ein Broker übergibt eine Session an die neueste Verbindung mit ihrer Client ID und trennt die ältere. Gib deshalb jeder Verbindung eine eigene Client ID und nutze sie in keinem anderen Client. Lässt der Broker nur bestimmte Client IDs zu, erlaube für eine Inbound-Verbindung die Client ID selbst, für eine Outbound-Verbindung jede ID, die mit der Client ID und einem Bindestrich beginnt.
Input des Agenten
Modi: Inbound
Jede Nachricht wird zum Input aller verknüpften Agenten. Ein JSON-Objekt behält seine Felder, und connic ergänzt die Angaben zur Nachricht unter _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 enthält das topic, auf dem die Nachricht veröffentlicht wurde, die qos, mit der sie zugestellt wurde, retain, das bei einer gespeicherten Nachricht true ist, die der Broker beim neuen Abonnement geschickt hat, duplicate, das true ist, wenn der Broker die Nachricht schon einmal geschickt hat, die user_properties von MQTT 5 als Objekt und die Property content_type, ohne Angabe null.
Jede andere Payload steht unter message: andere JSON-Werte geparst, Text, der kein JSON ist, als String, eine leere Payload als null. Binäre Payloads, die kein gültiges UTF-8 sind, starten keinen Run; siehe Limits und Fehler.
Ein JSON-Objekt kann Dateien in einem Array files mitbringen. Jede Datei hat name, mime_type und Base64-kodierte data. connic nimmt bis zu 50 vollständige Dateien an, höchstens 32 MiB insgesamt, innerhalb der Größengrenze des Brokers für Nachrichten. Ungültige Dateien werden einzeln ausgelassen. Bei der ersten Datei über einem Limit behält connic die Dateien davor und nimmt keine weiteren an. Jede ausgelassene Datei ist in file_issues beschrieben, und der Run läuft ohne sie weiter.
Topic-Filter und Sessions
Modi: Inbound
Jede Inbound-Verbindung abonniert genau einen Topic-Filter. Für mehrere Filter legst du je Filter eine Inbound-Verbindung an und verknüpfst alle mit demselben Agenten. _mqtt.topic unterscheidet die Ereignisse. Jede Verbindung erhält jede passende Nachricht: Überschneiden sich die Filter zweier Verbindungen, starten beide Runs für dieselbe Nachricht.
connic hält eine persistente Session beim Broker: connic meldet sich mit Clean Start 0 an und bittet um eine Session, die nach einer Trennung einen Tag bestehen bleibt. Broker können weniger gewähren. Solange connic getrennt ist, nach einem Neustart oder während die Verbindung pausiert ist, hält der Broker die QoS-1-Nachrichten des Abonnements zurück und schickt sie, sobald connic sich wieder verbindet. QoS-0-Nachrichten aus dieser Zeit gehen verloren. Läuft die Session ab, verwirft der Broker sie samt Nachrichten, und connic beginnt bei der nächsten Anmeldung eine neue.
Gespeicherte Nachrichten (Retained Messages) kommen einmal an, wenn das Abonnement neu ist. Eine erneute Anmeldung an einer bestehenden Session schickt sie nicht noch einmal.
Änderst du den Topic-Filter, abonniert connic den neuen, das alte Abonnement bleibt aber bis zum Ablauf in der Session. connic bestätigt die Nachrichten daraus, ohne Runs zu starten. Um das alte Abonnement sofort zu beenden, änderst du auch die Client ID. Damit beginnt eine neue Session.
Wenn du eine Verbindung löschst, bleibt ihre Session beim Broker bestehen, bis sie abläuft.
Zustellung und Reihenfolge
Modi: Inbound
connic bestätigt eine QoS-1-Nachricht mit PUBACK, sobald für jeden verknüpften Agenten ein Run in der Warteschlange gespeichert ist, also bevor diese Runs laufen. Gespeicherte Runs überstehen Neustarts und Deployments. Lässt sich ein Run nicht speichern, trennt connic die Verbindung zum Broker, ohne die Nachricht zu bestätigen, und der Broker schickt sie nach der erneuten Anmeldung noch einmal. connic schickt nur erfolgreiche PUBACKs. QoS-0-Nachrichten brauchen keine Bestätigung.
Mit message_id_field erkennt connic eine Nachricht am Wert dieser User Property oder, wenn die Nachricht keine solche hat, am Wert dieses JSON-Schlüssels auf oberster Ebene. Eine Nachricht, deren ID auf demselben Topic für einen Agenten schon einen Run gestartet hat, startet für ihn keinen neuen, egal wann und wie der Broker sie zustellt. Gib deshalb jeder Nachricht auf einem Topic eine eigene ID: Zwei verschiedene Nachrichten mit derselben ID auf einem Topic starten nur einen Run pro Agent.
Ohne message_id_field oder bei einer Nachricht ohne dieses Feld merkt sich connic jede QoS-1-Nachricht, die noch nicht bestätigt ist. Schickt der Broker sie nach einem Fehler in derselben Session erneut, verwendet sie den bereits gespeicherten Run. Gleiche Nachrichten starten immer eigene Runs. Nur wenn der Subscriber zwischen dem Speichern der Runs und der Bestätigung neu startet, kann eine erneut geschickte Nachricht einen zweiten Run starten.
Schlägt ein Run nach dem Speichern fehl, folgt keine erneute Zustellung. Der fehlgeschlagene Run behält seinen vollständigen Input, sodass du ihn erneut ausführen kannst. Wiederholungen innerhalb eines Runs folgen den retry_options des Agenten.
connic verarbeitet Nachrichten nacheinander in der Reihenfolge ihres Eingangs. Runs werden in dieser Reihenfolge gespeichert, laufen aber parallel bis zu max_concurrent_runs. Für eine Reihenfolge nach einem Feld, etwa einer Maschinen-ID, ergänzt du eine Concurrency-Regel auf diesem Feld:
concurrency:
key: machine
on_conflict: queueRuns mit demselben Wert starten dann einzeln in Eingangsreihenfolge, Runs mit unterschiedlichen Werten laufen weiter parallel. Ein fehlgeschlagener Run gibt seinen Wert frei, die nächste Nachricht mit diesem Wert läuft also trotzdem.
Outbound-Zustellung
Modi: Outbound
Eine Outbound-MQTT-Verbindung veröffentlicht JSON-Nachrichten mit ihrer QoS und ihrem Retain-Flag auf ihrem Topic. Je nach Nutzung der Verknüpfung veröffentlicht sie, wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn die Middleware sie aufruft.
Automatische Payload
Eine automatische Verknüpfung veröffentlicht den abgeschlossenen Run als Payload der Nachricht:
{
"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
}
}Für eine Pipeline verknüpfst du eine Inbound-MQTT-Verbindung und eine automatische Outbound-MQTT-Verbindung mit demselben Agenten; die Ausgabe des Agenten steht dann in output. Welche Runs veröffentlicht werden, beschreibt Automatische Quellen. Ein Run, den die Middleware mit StopProcessing beendet, gilt als abgeschlossen und veröffentlicht die StopProcessing-Antwort als Ausgabe, außer StopProcessing wird mit publish_outbound=False ausgelöst. Dieses Flag macht einen früheren Aufruf einer Agent-Tool- oder Middleware-Verknüpfung im selben Run nicht rückgängig.
Payload für Agent-Tool und Middleware
Das Modell oder die Middleware übergibt die Payload der Nachricht unter payload und kann unter user_properties User Properties von MQTT 5 mit Textwerten ergänzen. connic veröffentlicht den Wert von payload und ergänzt Topic, QoS, Retain-Flag, Zugangsdaten, Serialisierung, Wiederholungen und Bridge-Routing. Davon sieht das Modell nichts.
{
"payload": {
"machine": "press-4",
"command": "stop"
},
"user_properties": {
"priority": "high"
}
}Zustellung und Wiederholungen
Jede Nachricht hat eine JSON-Payload, den Content Type application/json und die User Property message_id mit der Run-ID. Bei einem Aufruf durch Tool oder Middleware ist es das Feld run_id der Payload, falls vorhanden, sonst eine ID, die bei allen Wiederholungen der Zustellung gleich bleibt. Abonnenten können daran Duplikate erkennen, und eine Inbound-MQTT-Verbindung liest sie mit message_id_field: message_id.
Mit QoS 1 wartet connic bis zu 30 Sekunden auf das PUBACK des Brokers. Verbindungsfehler und unbestätigte Nachrichten versucht connic insgesamt 3-mal, mit 1 und dann 2 Sekunden Abstand. Eine abgelehnte Anmeldung oder ein PUBACK mit Fehler, etwa wegen fehlender Berechtigung für das Topic, schlägt sofort fehl. Die Runs der Verbindung zeigen jede Zustellung mit ihrem Fehler.
Unterschiede zwischen Brokern
connic arbeitet mit jedem MQTT-5-Broker, etwa Mosquitto 2, HiveMQ oder EMQX. Verwaltete Broker setzen eigene Grenzen.
AWS IoT Core
- Trage den Data-Endpoint des Kontos als Host ein, dazu Port 8883 sowie Zertifikat und privaten Schlüssel des Things im Kontozugang. Benutzername und Passwort bleiben leer.
- Die IoT-Policy muss
iot:Connectaufclient/<Client ID>für eine Inbound-Verbindung und aufclient/<Client ID>-*für eine Outbound-Verbindung erlauben, dazuiot:Subscribeundiot:Receiveauf die Topics oderiot:Publish. - Nur QoS 0 und 1, Payloads bis 128 KB.
- Persistente Sessions bestehen standardmäßig eine Stunde. Über das Kontingent des Kontos lässt sich das auf bis zu 7 Tage erhöhen.
- AWS IoT Core kann eine Nachricht mit neuer Packet ID und ohne Duplikat-Flag erneut schicken. Setze ein
message_id_field, damit eine solche Nachricht keinen zweiten Run startet. - Gespeicherte Nachrichten erreichen nur Abonnements genau ihres Topics, keine Filter mit Wildcards.
Azure Event Grid
- Trage den MQTT-Hostnamen des Namespace und Port 8883 ein. Der Benutzername ist der Authentifizierungsname des Clients; bei Authentifizierung per Zertifikat kommen Client-Zertifikat und Schlüssel in den Kontozugang.
- Ein PUBACK mit Fehlercode beendet die Verbindung. connic schickt nie ein solches PUBACK.
- Sessions bestehen standardmäßig eine Stunde, über die Einstellung des Namespace bis zu 8 Stunden. Solange connic getrennt ist, hält eine Session höchstens 100 Nachrichten oder 1 MB. Läuft sie über, beendet der Broker sie.
- Nur QoS 0 und 1, Nachrichten bis 1 MB.
Limits und Fehler
| Situation | Was passiert |
|---|---|
| Eine Payload ist kein gültiges UTF-8 | connic bestätigt die Nachricht, ohne einen Run zu starten, und protokolliert einen fehlgeschlagenen Verbindungs-Run. |
| Ein Run lässt sich nicht speichern | Bei einer QoS-1-Nachricht trennt connic die Verbindung zum Broker, ohne die Nachricht zu bestätigen. Der Subscriber verbindet sich nach einer kurzen Pause neu, und der Broker schickt die Nachricht erneut. Eine QoS-0-Nachricht wird als fehlgeschlagener Verbindungs-Run protokolliert und nicht erneut geschickt. |
| QoS-0-Nachrichten kommen schneller, als Runs starten | Sobald 100 Nachrichten warten, verwirft connic weitere QoS-0-Nachrichten. QoS-1-Nachrichten verwirft connic nie; der Broker schickt sie, sobald connic frühere bestätigt. |
| Eine Nachricht kommt auf einem Topic, das nicht zum Filter passt | connic bestätigt sie ohne Run. Solche Nachrichten stammen von einem Abonnement, das nach einer Änderung des Topic-Filters in der Session des Brokers geblieben ist; siehe Topic-Filter und Sessions. |
| Kein Agent ist verknüpft | connic bestätigt jede Nachricht, ohne einen Run zu starten, und protokolliert sie als Verbindungs-Run mit No agents linked. |
| Broker oder Netzwerk fallen aus | Der Subscriber verbindet sich mit exponentiellem Backoff neu, von 5 Sekunden bis zu 2 Minuten. |
| Anmeldung, Zertifikat, Client ID oder Abonnement wird abgelehnt | Der Subscriber stoppt und schreibt den Grund des Brokers in die Verbindungs-Logs. Er startet wieder, sobald du die Verbindung oder ihren Kontozugang änderst oder die Verbindung pausierst und fortsetzt. |
| Ein anderer Client meldet sich mit derselben Client ID an | Der Broker übergibt die Session an die neuere Verbindung und trennt die ältere. Gib jeder Verbindung eine eigene Client ID. |
| Veröffentlichen schlägt fehl (Outbound) | Bei Verbindungsfehlern und Nachrichten, die der Broker nicht bestätigt, unternimmt connic bis zu 3 Versuche. Eine abgelehnte Anmeldung, eine fehlende Berechtigung für das Topic oder eine Nachricht, die der Broker ablehnt, schlägt sofort fehl. Siehe Zustellung und Wiederholungen. |