Azure Service Bus
Start agents from messages in an Azure Service Bus queue or topic subscription, or send run results to a queue or topic.
On this page
| Modes | Inbound, outbound |
| YAML type | azure_service_bus |
| Credentials | A Connection of type azure_service_bus with the namespace and a shared access key or a Microsoft Entra ID app |
| Bridge | Not supported. Service Bus is reached over the internet. |
| Custom domain | Not supported |
| Linked agents | One or more. A message starts every linked agent. |
| While paused | Inbound: connic stops receiving, and messages stay in the queue or subscription until you resume. Outbound: nothing is sent. |
| New connectors | Inbound 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
Create the queue, or the topic and a subscription for connic, in your Service Bus namespace. connic doesn't create them. Queues and subscriptions that connic receives from must not require sessions.
Give connic access. With a shared access key, add a shared access policy with the Listen right for inbound connectors or Send for outbound ones, on the namespace or the entity. With a Microsoft Entra ID app, register an app, add a client secret, and assign it the Azure Service Bus Data Receiver role for inbound connectors or Azure Service Bus Data Sender for outbound ones.
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 Azure Service Bus.
Choose Inbound (Receiver) or Outbound (Sender). Under Connection, pick a saved Connection or create one with the namespace and the sign-in; see Connection.
Under Queue or Topic, choose Queue and enter its name, or choose Topic and enter the topic and, for inbound, the Subscription.
Click Create. A new inbound connector is paused: click Resume in its details drawer to start receiving. 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 keys or secrets. Connectors in code start active, so an inbound connector starts receiving when its first deploy goes live.
type: azure_service_bus
mode: inbound
connection: orders-service-bus # Connection with the namespace and the sign-in
config:
entity_type: topic
topic: orders
subscription: connic
agents:
- order-processortype: azure_service_bus
mode: outbound
connection: orders-service-bus
config:
entity_type: queue
queue: order-results
agents:
- name: order-processor
outbound: { usage: automatic }Configuration
The fields of an Azure Service Bus 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.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | azure_service_bus. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Name or ID of a Connection of type azure_service_bus, which holds the namespace and the sign-in. See Connection. Dashboard: Connection. |
| config | object | Required | Service Bus settings. |
| entity_type | string | Optional | queue or topic. Inbound connectors read a queue or a topic subscription; outbound ones send to a queue or topic. Dashboard: Queue or Topic.Default: queue |
| queue | string | Required | With entity_type: queue. The queue to receive from or send to. It must already exist. Dashboard: Queue. |
| topic | string | Required | With entity_type: topic. The topic to receive from or send to. It must already exist. Dashboard: Topic. |
| subscription | string | Required | Inbound, with entity_type: topic. The subscription of the topic to receive from. It must already exist. Dashboard: Subscription. |
Connection
A Connection of type azure_service_bus holds these fields. Every Azure Service Bus 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.
| Field | Type | Status | Description |
|---|---|---|---|
| namespace | string | Required | Host name of the namespace, such as contoso.servicebus.windows.net, from its overview page in the Azure portal. Dashboard: Namespace. |
| auth_method | string | Optional | sas for a shared access key or entra for a Microsoft Entra ID app. Dashboard: Sign-in.Default: sas |
| sas_key_name | string | Required | With sas. Name of the shared access policy. It needs the Listen right for inbound connectors and Send for outbound ones. Dashboard: Policy Name. |
| sas_key | string | Required | With sas. Primary or secondary key of the policy. Secret. Dashboard: Key. |
| tenant_id | string | Required | With entra. Directory (tenant) ID of the app, or a domain such as contoso.onmicrosoft.com. Dashboard: Directory (tenant) ID. |
| client_id | string | Required | With entra. Application (client) ID of the app. It needs the Azure Service Bus Data Receiver role for inbound connectors and Data Sender for outbound ones. Dashboard: Application (client) ID. |
| client_secret | string | Required | With entra. The value of a client secret of the app. Secret. Dashboard: Client secret. |
When you change the namespace or the policy name of a saved Connection, enter the key again; when you change the namespace, tenant, or client ID, enter the client secret again. connic refuses the change otherwise.
Agent input
Modes: Inbound
Each message becomes the input of every linked agent. A JSON object keeps its fields, and connic adds the message properties under _azure_service_bus:
{
"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 holds the namespace, the queue or the topic and subscription, the message_id, correlation_id, subject, content_type, and reply_to properties, the application_properties, the sequence_number Service Bus assigned, the enqueued_time as an ISO 8601 time, and the delivery_count, which counts earlier deliveries of the message. Properties the sender didn't set are null.
Any other body is wrapped under message: other JSON values as parsed, text that isn't JSON as a string, and an empty body as null.
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. 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.
Files are optional by default. Turn on Files required for an agent in the connector's details drawer, or set files_required: true on its link in YAML, to fail the run before it starts when a file is missing or was omitted.
Queues and subscriptions
Modes: Inbound
Each inbound connector receives from one queue or one topic subscription. Connectors on the same queue or subscription share its messages: Service Bus delivers each message to one of them. A topic copies each message to every subscription, so give connic a subscription of its own when other systems read the topic too. To start agents from several entities, create one inbound connector per entity and link them to the same agent; _azure_service_bus tells the events apart.
connic receives one message at a time and handles them in the order they arrive. Queues and subscriptions that require sessions aren't supported.
Deleting a connector doesn't delete its queue, topic, or subscription, or the messages in them.
Delivery and ordering
Modes: Inbound
connic receives in peek-lock mode: Service Bus locks a message while connic handles it. connic renews the lock while it stores a queued run for every linked agent, then completes the message, before those runs execute. Stored runs survive worker restarts and deployments. Since connic doesn't hold a message until its runs finish, long runs never run into the lock duration.
A message that Service Bus delivers again, after a partial failure or a restart before it was completed, reuses the run already stored for it. connic identifies a message by its message_id within the queue or subscription. Without one, it uses the sequence number Service Bus assigned. Set a unique message_id when you send to make every message count.
A message comes back only when connic couldn't store its runs. Each return counts as a delivery, and Service Bus moves the message to the dead-letter queue once its delivery count passes the entity's max delivery count, 10 by default.
A run that fails after it was stored causes no redelivery and no dead-letter message. The failed run keeps its full input, so you can rerun it. Retries inside a run follow the agent's retry_options.
Runs are stored in arrival order but execute in parallel up to max_concurrent_runs. For ordering by a field, such as an order ID, add a concurrency rule on it:
concurrency:
key: order_id
on_conflict: queueRuns 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 Azure Service Bus connector sends JSON messages to its queue or topic. It sends 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 sends the completed run as the message body:
{
"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
}
}To build a pipeline, link an inbound Azure Service Bus connector and an automatic outbound one to the same agent; the agent's output arrives in output. Automatic sources describes which runs send. A run that middleware ends with StopProcessing counts as completed and sends 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. Automatic messages carry no session ID, so a queue or topic that requires sessions takes messages only from agent-tool and middleware calls.
Agent-tool and middleware payload
The model or middleware passes the message body under payload and can set the message's subject, correlation_id, session_id, and application_properties with text, number, or boolean values. A queue or topic that requires sessions needs session_id. connic adds the queue or topic, the sign-in, serialization, and retries, none of which the model sees.
{
"payload": {
"order_id": "12345",
"status": "approved"
},
"subject": "order.approved",
"correlation_id": "order-12345-created",
"session_id": "customer-42",
"application_properties": { "tenant": "acme", "priority": 2 }
}Delivery and retries
Each message has a JSON body and the content type application/json. Its message_id is 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. With duplicate detection on the queue or topic, Service Bus drops a retry it already received; otherwise consumers can use the ID to drop duplicates.
connic waits up to 30 seconds for Service Bus to accept a message. Network and service errors are tried 3 times in total, waiting 1 and then 2 seconds between attempts. The connector's runs show each delivery and its error.
Limits and errors
| Situation | What happens |
|---|---|
| A message body isn't valid UTF-8 | connic moves the message to the dead-letter queue with the reason Unparsable body and records a failed connector run. |
| Storing a run fails | connic abandons the message, so Service Bus makes it available again, and reconnects after a short delay. Each attempt counts as a delivery; after the entity's max delivery count, 10 by default, Service Bus moves the message to the dead-letter queue. |
| No agent is linked | connic completes each message without starting a run and records it as a connector run with No agents linked. |
| The queue or subscription requires sessions | The receiver stops and writes the error to the connector logs. Use a queue or subscription without sessions. |
| The sign-in is refused, a right or role is missing, or the entity doesn't exist or is disabled | The receiver stops and writes the error to the connector logs. It starts again when you update the connector or its Connection, or pause and resume it. |
| A network or service error | The receiver reconnects with exponential backoff, from 5 seconds up to 2 minutes. |
| Sending fails (outbound) | Network and service errors get up to 3 attempts. A refused sign-in, a missing right or entity, and a message Service Bus doesn't accept, such as one over the size limit of the tier, fail at once. See Delivery and retries. |