Skip to main content
connic

Azure Service Bus

Every message in a queue or topic subscription starts an agent run, and results go to a queue or topic. connic completes each message once its runs are stored.

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

Turn every message into an agent run

An inbound connector receives from one queue or topic subscription and starts each linked agent once per message, with the message as its input.

JSON keeps its shape
A JSON object arrives with its top-level fields, plus _azure_service_bus with the entity, message ID, subject, application properties and enqueued time.
Text arrives as text
Any other body arrives under message: other JSON values as parsed, plain text as a string.
Files in the message
A JSON object can carry a files array with each file's name, MIME type and base64 data, up to 50 files and 32 MiB in total.
message on orders
{
  "order_id": "ord_8812",
  "customer": "jana@example.com",
  "total": 184.5
}
context["payload"]
{
  "order_id": "ord_8812",
  "customer": "jana@example.com",
  "total": 184.5,
  "_azure_service_bus": {
    "namespace": "contoso.servicebus.windows.net",
    "topic": "orders",
    "subscription": "connic",
    "message_id": "ord_8812-created",
    "sequence_number": 1042,
    "correlation_id": null,
    "subject": "order.created",
    "content_type": "application/json",
    "reply_to": null,
    "application_properties": {},
    "enqueued_time": "2026-10-13T09:00:00+00:00",
    "delivery_count": 0
  }
}

Complete each message after its runs are stored

connic receives in peek-lock mode and completes a message once a queued run exists for every linked agent, so a restart or a deploy doesn't drop work, and long runs don't hold the lock.

One run per message
A message delivered again reuses its stored run, matched by message_id, or by sequence number without one.
Unreadable messages to the dead-letter queue
A body that isn't valid UTF-8 goes to the dead-letter queue with a reason, and the connector records a failed run.
Shared queues and subscriptions
Several connectors on the same queue or subscription split its messages: Service Bus delivers each message to one of them.
  1. Receive

    Service Bus locks the message, and connic receives one message at a time in arrival order.

  2. Store

    connic renews the lock while it stores a queued run for every linked agent. Stored runs survive worker restarts and deployments.

  3. Complete

    The message is completed. If storing a run fails, connic abandons it, and Service Bus delivers it again until its max delivery count.

    complete
  4. Run

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

    concurrency.key: order_id

Keep the receiver next to your agents

Declare it as a YAML file in connectors/. The namespace and the sign-in live in a Connection, so the file names only the queue or topic. A receiver declared in code starts when its deployment goes live.

Shared access key or Entra ID
Sign in with a shared access policy, or with a Microsoft Entra ID app that holds the Data Receiver or Data Sender role.
Queues and topics
Receive from a queue or a topic subscription, and send to a queue or topic. connic doesn't create entities.
connectors/order-events.yaml
type: azure_service_bus
mode: inbound
name: Order events
connection: orders-service-bus
config:
  entity_type: topic
  topic: orders
  subscription: connic
agents:
  - order-processor
create: connectors/order-events.yaml (azure_service_bus)

Send results to a queue or topic

An outbound connector sends each completed run to its queue or topic as a JSON message.

Run ID as message ID
Each message carries the run ID as message_id, so duplicate detection or your consumers can drop a retry.
Message properties
Called as a tool or from middleware, the connector sets subject, correlation ID, session ID and application properties.
Let the agent send
Linked as an agent tool, the connector lets the model send its own payload during the run.
connectors/order-results.yaml
type: azure_service_bus
mode: outbound
name: Order results
connection: orders-service-bus
config:
  entity_type: queue
  queue: order-results
agents:
  - name: order-processor
    outbound:
      usage: automatic
      source: [order-events]
message on order-results (message_id = run_id)
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "order-processor",
  "status": "completed",
  "output": "ord_8812 approved for standard shipping.",
  "error": null,
  "started_at": "2026-10-13T09:00:01Z",
  "ended_at": "2026-10-13T09:00:05Z",
  "token_usage": {
    "input_tokens": 642,
    "output_tokens": 38,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 680
  }
}

Where Azure Service Bus fits

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

Each order event on the orders topic starts a run, and the result lands on the order-results queue.

Checkout service
Service Bus receiver
order-processor
Result on order-results
context["payload"]
{
  "order_id": "ord_8812",
  "customer": "jana@example.com",
  "total": 184.5,
  "_azure_service_bus": {
    "namespace": "contoso.servicebus.windows.net",
    "topic": "orders",
    "subscription": "connic",
    "message_id": "ord_8812-created",
    "sequence_number": 1042,
    "correlation_id": null,
    "subject": "order.created",
    "content_type": "application/json",
    "reply_to": null,
    "application_properties": {},
    "enqueued_time": "2026-10-13T09:00:00+00:00",
    "delivery_count": 0
  }
}
message on order-results
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "order-processor",
  "status": "completed",
  "output": "ord_8812 approved for standard shipping.",
  "error": null,
  "started_at": "2026-10-13T09:00:01Z",
  "ended_at": "2026-10-13T09:00:05Z",
  "token_usage": {
    "input_tokens": 642,
    "output_tokens": 38,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 680
  }
}

The agent reads each new ticket and sends the team and priority, with the team as an application property for subscription filters.

Helpdesk
Service Bus receiver
ticket-router
Routing on tickets-routed
context["payload"]
{
  "ticket_id": "T-48213",
  "subject": "Invoice shows the wrong VAT number",
  "customer": "acme-gmbh",
  "_azure_service_bus": {
    "namespace": "contoso.servicebus.windows.net",
    "queue": "support-tickets",
    "message_id": "T-48213-opened",
    "sequence_number": 318,
    "correlation_id": null,
    "subject": "ticket.opened",
    "content_type": "application/json",
    "reply_to": null,
    "application_properties": {},
    "enqueued_time": "2026-10-13T09:00:00+00:00",
    "delivery_count": 0
  }
}
connector-payload.json
{
  "payload": {
    "ticket_id": "T-48213",
    "team": "billing",
    "priority": "normal"
  },
  "subject": "ticket.routed",
  "application_properties": { "team": "billing" }
}

A scanned invoice arrives with the message, and the agent sends the fields to a session queue, one session per supplier.

Mail gateway
Service Bus receiver
invoice-reader
Fields to the ERP queue
context["payload"]
{
  "supplier": "Nordlicht Logistik",
  "files": [
    { "name": "invoice-2210.pdf", "mime_type": "application/pdf", "data": "JVBERi0xLjcK..." }
  ],
  "_azure_service_bus": {
    "namespace": "contoso.servicebus.windows.net",
    "queue": "invoices",
    "message_id": "inv-2210",
    "sequence_number": 77,
    "correlation_id": null,
    "subject": "invoice.received",
    "content_type": "application/json",
    "reply_to": null,
    "application_properties": {},
    "enqueued_time": "2026-10-13T09:00:00+00:00",
    "delivery_count": 0
  }
}
connector-payload.json
{
  "payload": {
    "invoice_number": "2210",
    "total": 1840.0,
    "currency": "EUR",
    "due_date": "2026-11-12"
  },
  "session_id": "nordlicht-logistik"
}

A delayed shipment starts a run, and the agent emails the customer the new delivery date.

Warehouse system
Service Bus receiver
delay-notifier
Email to the customer
context["payload"]
{
  "shipment_id": "shp_5531",
  "order_id": "ord_8812",
  "status": "delayed",
  "new_eta": "2026-10-16",
  "_azure_service_bus": {
    "namespace": "contoso.servicebus.windows.net",
    "topic": "shipments",
    "subscription": "connic",
    "message_id": "shp_5531-delayed",
    "sequence_number": 2290,
    "correlation_id": null,
    "subject": "shipment.delayed",
    "content_type": "application/json",
    "reply_to": null,
    "application_properties": {},
    "enqueued_time": "2026-10-13T09:00:00+00:00",
    "delivery_count": 0
  }
}
connector-payload.json
{
  "body": "Your order ord_8812 is running late. It now arrives on October 16.",
  "to": "jana@example.com",
  "subject": "New delivery date for your order"
}

Azure Service Bus FAQ

Add an Azure Service Bus connector in Inbound (Receiver) mode, pick a Connection with your namespace, enter the queue or the topic and subscription, and link the agent. Connectors created in the dashboard start paused, so click Resume when you're ready. Each message then starts a run for every linked agent, with the message properties under _azure_service_bus.

As soon as a queued run is stored for every linked agent, before the runs execute. connic renews the message lock until then, so long runs never run into the lock duration. If storing a run fails, connic abandons the message and Service Bus makes it available again.

No. connic identifies a message by its message_id, or by its sequence number when it has none, and reuses the run it already stored. A failed run isn't retried by redelivery, so re-run it from Agent Runs.

With a shared access policy that has the Listen or Send right, or with a Microsoft Entra ID app that has the Azure Service Bus Data Receiver or Data Sender role. Both live in a Connection, never in the connector file. The Azure Service Bus docs list the fields.