Zum Hauptinhalt springen
connic
Starte kostenlos
Verbindungen

Azure Service Bus

Agenten durch Nachrichten aus einer Queue oder Topic-Subscription in Azure Service Bus starten oder Run-Ergebnisse an eine Queue oder ein Topic senden.

Zuletzt aktualisiert
ModiInbound, Outbound
YAML-Typazure_service_bus
ZugangsdatenEin Kontozugang (Connection) vom Typ azure_service_bus mit dem Namespace und einem Shared Access Key oder einer Microsoft-Entra-ID-App
BridgeNicht unterstützt. connic erreicht Service Bus über das Internet.
Custom DomainNicht unterstützt
Verknüpfte AgentenEiner oder mehrere. Jede Nachricht startet alle verknüpften Agenten.
Während der PauseInbound: connic empfängt nichts mehr, und die Nachrichten bleiben bis zum Fortsetzen in der Queue oder Subscription. Outbound: Es wird nichts gesendet.
Neue VerbindungenInbound-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

  1. Lege in deinem Service-Bus-Namespace die Queue an, oder das Topic mit einer Subscription für connic. connic legt sie nicht selbst an. Queues und Subscriptions, aus denen connic empfängt, dürfen keine Sessions erfordern.

  2. Gib connic Zugriff. Für einen Shared Access Key legst du am Namespace oder an der Entität eine Shared Access Policy an, mit dem Recht Listen für Inbound-Verbindungen oder Send für Outbound-Verbindungen. Für eine Microsoft-Entra-ID-App registrierst du eine App, erstellst ein Client Secret und weist ihr die Rolle Azure Service Bus Data Receiver für Inbound-Verbindungen oder Azure Service Bus Data Sender für Outbound-Verbindungen zu.

  3. Ö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 Azure Service Bus.

  4. Wähle Inbound (Receiver) oder Outbound (Sender). Wähle unter Connection einen gespeicherten Kontozugang oder lege einen mit Namespace und Anmeldung an; siehe Kontozugang.

  5. Wähle unter Queue or Topic entweder Queue und gib ihren Namen ein, oder Topic und gib das Topic und für Inbound die Subscription ein.

  6. Klicke auf Create. Eine neue Inbound-Verbindung ist pausiert: Klicke in ihrem Detailbereich auf Resume, damit connic Nachrichten empfängt. 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 Keys oder Secrets. Verbindungen im Code starten aktiv: Eine Inbound-Verbindung beginnt zu empfangen, sobald ihr erstes Deployment live geht.

connectors/order-events.yaml
type: azure_service_bus
mode: inbound
connection: orders-service-bus   # Kontozugang mit Namespace und Anmeldung
config:
  entity_type: topic
  topic: orders
  subscription: connic
agents:
  - order-processor
connectors/order-results.yaml
type: azure_service_bus
mode: outbound
connection: orders-service-bus
config:
  entity_type: queue
  queue: order-results
agents:
  - name: order-processor
    outbound: { usage: automatic }

Konfiguration

Die Felder einer Azure-Service-Bus-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.

FeldTypStatusBeschreibung
typestringRequiredazure_service_bus.
modestringRequiredinbound oder outbound. Dashboard: Mode.
connectionstringRequiredName oder ID eines Kontozugangs vom Typ azure_service_bus, der Namespace und Anmeldung enthält. Siehe Kontozugang. Dashboard: Connection.
configobjectRequiredService-Bus-Einstellungen.
entity_typestringOptionalqueue oder topic. Inbound-Verbindungen lesen eine Queue oder eine Topic-Subscription, Outbound-Verbindungen senden an eine Queue oder ein Topic. Dashboard: Queue or Topic.Default: queue
queuestringRequiredBei entity_type: queue. Die Queue, aus der connic empfängt oder an die es sendet. Sie muss bereits existieren. Dashboard: Queue.
topicstringRequiredBei entity_type: topic. Das Topic, aus dem connic empfängt oder an das es sendet. Es muss bereits existieren. Dashboard: Topic.
subscriptionstringRequiredInbound, bei entity_type: topic. Die Subscription des Topics, aus der connic empfängt. Sie muss bereits existieren. Dashboard: Subscription.

Kontozugang

Ein Kontozugang vom Typ azure_service_bus enthält diese Felder. Alle Azure-Service-Bus-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.

FeldTypStatusBeschreibung
namespacestringRequiredHostname des Namespace, etwa contoso.servicebus.windows.net, von seiner Übersichtsseite im Azure-Portal. Dashboard: Namespace.
auth_methodstringOptionalsas für einen Shared Access Key oder entra für eine Microsoft-Entra-ID-App. Dashboard: Sign-in.Default: sas
sas_key_namestringRequiredBei sas. Name der Shared Access Policy. Sie braucht das Recht Listen für Inbound-Verbindungen und Send für Outbound-Verbindungen. Dashboard: Policy Name.
sas_keystringRequiredBei sas. Primärer oder sekundärer Schlüssel der Policy. Secret. Dashboard: Key.
tenant_idstringRequiredBei entra. Verzeichnis-ID (Tenant) der App oder eine Domain wie contoso.onmicrosoft.com. Dashboard: Directory (tenant) ID.
client_idstringRequiredBei entra. Anwendungs-ID (Client) der App. Sie braucht die Rolle Azure Service Bus Data Receiver für Inbound-Verbindungen und Data Sender für Outbound-Verbindungen. Dashboard: Application (client) ID.
client_secretstringRequiredBei entra. Der Wert eines Client Secrets der App. Secret. Dashboard: Client secret.

Änderst du bei einem gespeicherten Kontozugang den Namespace oder den Policy-Namen, gib den Schlüssel erneut ein. Bei Namespace, Tenant oder Client-ID gilt das für das Client Secret. Sonst lehnt connic die Änderung ab.

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 Properties der Nachricht unter _azure_service_bus:

payload.json
{
  "order_id": "12345",
  "customer": "john@example.com",
  "_azure_service_bus": {
    "namespace": "contoso.servicebus.windows.net",
    "topic": "orders",
    "subscription": "connic",
    "message_id": "order-12345-created",
    "sequence_number": 42,
    "correlation_id": null,
    "subject": "order.created",
    "content_type": "application/json",
    "reply_to": null,
    "application_properties": { "tenant": "acme" },
    "enqueued_time": "2026-01-15T10:30:00+00:00",
    "delivery_count": 0
  }
}

_azure_service_bus enthält den namespace, die queue oder das topic mit der subscription, die Properties message_id, correlation_id, subject, content_type und reply_to, die application_properties, die von Service Bus vergebene sequence_number, die enqueued_time als ISO-8601-Zeitpunkt und den delivery_count, der frühere Zustellungen der Nachricht zählt. Properties, die der Sender nicht gesetzt hat, sind null.

Jeder andere Body steht unter message: andere JSON-Werte geparst, Text, der kein JSON ist, als String, ein leerer Body als null.

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

Dateien sind standardmäßig optional. Aktiviere Files required für einen Agenten im Detailbereich der Verbindung oder setze files_required: true an seiner Verknüpfung in YAML. Dann schlägt der Run vor dem Start fehl, wenn eine Datei fehlt oder ausgelassen wurde.

Queues und Subscriptions

Modi: Inbound

Jede Inbound-Verbindung empfängt aus genau einer Queue oder einer Topic-Subscription. Verbindungen an derselben Queue oder Subscription teilen sich deren Nachrichten: Service Bus stellt jede Nachricht nur einer von ihnen zu. Ein Topic kopiert jede Nachricht in alle seine Subscriptions. Lesen auch andere Systeme das Topic, gib connic deshalb eine eigene Subscription. Für mehrere Entitäten legst du je Entität eine Inbound-Verbindung an und verknüpfst alle mit demselben Agenten. _azure_service_bus unterscheidet die Ereignisse.

connic empfängt eine Nachricht nach der anderen und verarbeitet sie in der Reihenfolge ihres Eingangs. Queues und Subscriptions, die Sessions erfordern, werden nicht unterstützt.

Wenn du eine Verbindung löschst, bleiben Queue, Topic und Subscription mit ihren Nachrichten erhalten.

Zustellung und Reihenfolge

Modi: Inbound

connic empfängt im Peek-Lock-Modus: Service Bus sperrt eine Nachricht, während connic sie verarbeitet. connic verlängert die Sperre, solange es für jeden verknüpften Agenten einen Run in der Warteschlange speichert, und schließt die Nachricht danach ab, also bevor diese Runs laufen. Gespeicherte Runs überstehen Neustarts und Deployments. Weil connic eine Nachricht nicht bis zum Ende ihrer Runs festhält, stoßen auch lange Runs nie an die Sperrdauer.

Stellt Service Bus eine Nachricht nach einem Teilfehler oder einem Neustart vor dem Abschluss erneut zu, verwendet sie den bereits gespeicherten Run. connic erkennt eine Nachricht an ihrer message_id innerhalb der Queue oder Subscription. Fehlt sie, zählt die Sequenznummer, die Service Bus vergeben hat. Setze beim Senden eine eindeutige message_id, damit jede Nachricht zählt.

Erneut bereitgestellt wird eine Nachricht nur, wenn connic ihre Runs nicht speichern konnte. Jede Rückgabe zählt als Zustellung, und sobald die maximale Zustellanzahl der Entität überschritten ist, standardmäßig 10, verschiebt Service Bus die Nachricht in die Dead-Letter-Queue.

Schlägt ein Run nach dem Speichern fehl, folgt weder eine erneute Zustellung noch eine Dead-Letter-Nachricht. 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.

Runs werden in Eingangsreihenfolge gespeichert, laufen aber parallel bis zu max_concurrent_runs. Für eine Reihenfolge nach einem Feld, etwa einer Bestellnummer, ergänzt du eine Concurrency-Regel auf diesem Feld:

agents/order-processor.yaml
concurrency:
  key: order_id
  on_conflict: queue

Runs 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-Verbindung für Azure Service Bus sendet JSON-Nachrichten an ihre Queue oder ihr Topic. Je nach Nutzung der Verknüpfung sendet 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 sendet den abgeschlossenen Run als Body der Nachricht:

payload.json
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "order-processor",
  "status": "completed",
  "output": "Order processed successfully. Total: $234.56",
  "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- und eine automatische Outbound-Verbindung für Azure Service Bus mit demselben Agenten; die Ausgabe des Agenten steht dann in output. Welche Runs gesendet werden, beschreibt Automatische Quellen. Ein Run, den die Middleware mit StopProcessing beendet, gilt als abgeschlossen und sendet 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. Automatische Nachrichten tragen keine Session-ID. Eine Queue oder ein Topic, das Sessions erfordert, nimmt daher nur Nachrichten aus Aufrufen durch Agent-Tool oder Middleware an.

Payload für Agent-Tool und Middleware

Das Modell oder die Middleware übergibt den Body der Nachricht unter payload und kann subject, correlation_id, session_id und application_properties mit Text-, Zahlen- oder Wahrheitswerten setzen. Eine Queue oder ein Topic, das Sessions erfordert, braucht session_id. connic ergänzt Queue oder Topic, Anmeldung, Serialisierung und Wiederholungen. Davon sieht das Modell nichts.

connector-payload.json
{
  "payload": {
    "order_id": "12345",
    "status": "approved"
  },
  "subject": "order.approved",
  "correlation_id": "order-12345-created",
  "session_id": "customer-42",
  "application_properties": { "tenant": "acme", "priority": 2 }
}

Zustellung und Wiederholungen

Jede Nachricht hat einen JSON-Body und den Content Type application/json. Ihre message_id ist die 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. Ist die Duplikaterkennung an Queue oder Topic aktiv, verwirft Service Bus eine Wiederholung, die schon angekommen ist. Sonst können Consumer Duplikate an der ID erkennen.

connic wartet bis zu 30 Sekunden, bis Service Bus eine Nachricht annimmt. Netzwerk- und Dienstfehler versucht connic insgesamt 3-mal, mit 1 und dann 2 Sekunden Abstand. Die Runs der Verbindung zeigen jede Zustellung mit ihrem Fehler.

Limits und Fehler

SituationWas passiert
Der Body einer Nachricht ist kein gültiges UTF-8connic verschiebt die Nachricht mit dem Grund Unparsable body in die Dead-Letter-Queue und protokolliert einen fehlgeschlagenen Verbindungs-Run.
Ein Run lässt sich nicht speichernconnic gibt die Nachricht frei, sodass Service Bus sie erneut bereitstellt, und verbindet sich nach einer kurzen Pause neu. Jeder Versuch zählt als Zustellung. Nach der maximalen Zustellanzahl der Entität, standardmäßig 10, verschiebt Service Bus die Nachricht in die Dead-Letter-Queue.
Kein Agent ist verknüpftconnic schließt jede Nachricht ab, ohne einen Run zu starten, und protokolliert sie als Verbindungs-Run mit No agents linked.
Die Queue oder Subscription erfordert SessionsDer Empfänger stoppt und schreibt den Fehler in die Verbindungs-Logs. Nutze eine Queue oder Subscription ohne Sessions.
Die Anmeldung wird abgelehnt, ein Recht oder eine Rolle fehlt, oder die Entität fehlt oder ist deaktiviertDer Empfänger stoppt und schreibt den Fehler in die Verbindungs-Logs. Er startet wieder, sobald du die Verbindung oder ihren Kontozugang änderst oder die Verbindung pausierst und fortsetzt.
Ein Netzwerk- oder DienstfehlerDer Empfänger verbindet sich mit exponentiellem Backoff neu, von 5 Sekunden bis zu 2 Minuten.
Senden schlägt fehl (Outbound)Bei Netzwerk- und Dienstfehlern unternimmt connic bis zu 3 Versuche. Eine abgelehnte Anmeldung, ein fehlendes Recht, eine fehlende Entität und eine Nachricht, die Service Bus nicht annimmt, etwa weil sie die Größengrenze des Tarifs überschreitet, schlagen sofort fehl. Siehe Zustellung und Wiederholungen.