Google Pub/Sub
Start agents from the messages a Google Cloud Pub/Sub push subscription delivers, or publish run results to a topic.
On this page
| Modes | Inbound, outbound |
| YAML type | google_pubsub |
| Credentials | Inbound: none, since every push request carries a token Google signs. Outbound: a Connection of type google_pubsub with the JSON key of your own Google Cloud service account. |
| Bridge | Not supported |
| Custom domain | Not supported |
| Linked agents | One or more. A message starts every linked agent. |
| While paused | Inbound: messages get 200 and start no runs, so Pub/Sub drops them. Outbound publishes nothing. |
Set up
An inbound connector receives the messages of a push subscription, and an outbound connector publishes to a topic. Set up the mode you need, or both with one connector each.
Receive messages
Pick the service account the push subscription authenticates with. It must be in the same Google Cloud project as the subscription, and whoever creates the subscription needs
iam.serviceAccounts.actAson it, for example throughroles/iam.serviceAccountUser. Google's docs also have you grant the Pub/Sub service agent the Service Account Token Creator role:Terminalgcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"In connic, open the agent. In Connector Flow, click Add inbound connector, then Create New Connector, and choose Google Pub/Sub.
Choose Inbound (Push subscription), enter the service account's email under Push service account, and click Create. Leave Audience (Optional) empty unless the subscription sets its own audience. Copy the Push endpoint from the details drawer.
Create a push subscription on the topic with that endpoint and authentication by the service account:
Terminalgcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --push-auth-service-account=SERVICE_ACCOUNT_EMAILWith
--push-auth-token-audience=AUDIENCE, enter the same value as Audience (Optional) in connic. For an existing subscription, rungcloud pubsub subscriptions modify-push-config SUBSCRIPTION_IDwith the same flags. Keep Pub/Sub's default wrapped payload: connic rejects messages from a subscription with--push-no-wrapper. In the Google Cloud console, the same settings are the push delivery type, the endpoint URL, and authentication with the service account, with payload unwrapping left off.
Publish messages
Give the service account that publishes the Pub/Sub Publisher role on the topic, and create a JSON key for it. Google downloads the key file once and can't show it again.
Terminalgcloud pubsub topics add-iam-policy-binding TOPIC_ID \ --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \ --role="roles/pubsub.publisher"Terminalgcloud iam service-accounts keys create key.json \ --iam-account=SERVICE_ACCOUNT_EMAILGoogle Cloud organizations created on or after May 3, 2024 block service account key creation by default with the organization policy
iam.managed.disableServiceAccountKeyCreation. An organization policy administrator has to allow it for the project first; see Google's secure-by-default organizations.In connic, open Project Settings → Connections, click New connection, and choose Google Pub/Sub. You can also create the Connection from the Connection picker in the connector form. Enter a Name, paste the contents of the key file into Service account key (JSON), and click Create connection.
Open the agent. In Connector Flow, click Add outbound connector, then Create New Connector, and choose Google Pub/Sub.
Choose Outbound (Publish), pick the Connection under Connection, and enter the Topic by its full name, such as
projects/acme/topics/order-results. Click Create, then choose how the agent uses the connector and click Link connector.
In code
Declare the connector in connectors/*.yaml. An inbound connector names no Connection. Its push endpoint is created on the first deploy; create the subscription after that. An outbound connector names the Connection that holds the service account key.
type: google_pubsub
mode: inbound
config:
push_service_account: pubsub-push@acme.iam.gserviceaccount.com
agents:
- order-processortype: google_pubsub
mode: outbound
connection: acme-pubsub # Connection with the service account key
config:
topic: projects/acme/topics/order-results
agents:
- name: order-processor
outbound: { usage: automatic }Configuration
The fields of a Google Pub/Sub 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 | google_pubsub. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Optional | Outbound, required there. Name or ID of a Connection of type google_pubsub; see Connection. Inbound connectors don't use one, so leave it out. Dashboard: Connection. |
| config | object | Required | Google Pub/Sub settings. |
| push_service_account | string | Required | Inbound. Email of the service account the push subscription authenticates with, such as pubsub-push@acme.iam.gserviceaccount.com. Requests with a token for any other account are rejected. Dashboard: Push service account. |
| audience | string | Optional | Inbound. The audience set on the push subscription. Leave it empty when the subscription uses its default audience, the push endpoint. Dashboard: Audience (Optional). |
| topic | string | Required | Outbound. Full name of the topic, projects/<project>/topics/<topic>. Dashboard: Topic. |
Connection
A Connection of type google_pubsub, shown as Google Pub/Sub on the Connections page, holds one field. Every outbound Google Pub/Sub connector in the project can use it, and a connector's config doesn't take it. Manage Connections in Project Settings → Connections or through the REST API; a changed Connection applies to every connector that uses it.
| Field | Type | Status | Description |
|---|---|---|---|
| service_account_key | string | Required | The contents of a JSON key file of a Google Cloud service account with the Pub/Sub Publisher role on the topic. Saving checks that it's a service account key with a readable private key. Secret. Dashboard: Service account key (JSON). |
To rotate the key, create a new one, paste it into the Connection, and then delete the old key in Google Cloud.
Generated values
| Value | Modes | Description |
|---|---|---|
| Push endpoint | Inbound | The URL Pub/Sub pushes to, https://connect.connic.co/google-pubsub/<connector-id>. connic creates it with the connector and keeps it across updates and deploys. Copy it from the details drawer. |
Agent input
Modes: Inbound
Each message becomes the input of every linked agent. connic decodes the message data from base64. A JSON object keeps its keys at the top level, and connic adds the message's metadata under _google_pubsub:
{
"order_id": "A-1001",
"total": 49.9,
"_google_pubsub": {
"subscription": "projects/acme/subscriptions/orders-connic",
"message_id": "2070443601311540",
"publish_time": "2026-11-17T09:13:55.749Z",
"ordering_key": "customer-42",
"attributes": { "event": "order.created" }
}
}subscriptionis the full name of the subscription that pushed the message.message_idandpublish_timeare the ID and publish time Pub/Sub gave the message.ordering_keyis the message's ordering key, ornullwhen it has none.attributesholds the message's attributes as an object, empty when it has none.
Any other data goes under message: text as a string, and other JSON values, such as an array or a number, as parsed. A message with only attributes has message: null. Data that is neither JSON nor UTF-8 text is rejected with 400.
Push authentication
Modes: Inbound
A subscription with authentication sends an OIDC token that Google signs in the Authorization: Bearer header of every push request. connic checks Google's signature, that accounts.google.com issued the token, that its audience is the connector's Audience or, without one, the push endpoint, and that it belongs to the Push service account with a verified email. Requests without such a token get 401 and start no runs, so knowing the push endpoint isn't enough to start an agent.
Pub/Sub treats the 401 as a failed push and retries the message. After a change to the subscription's service account or audience, update the connector to match.
Delivery and ordering
Modes: Inbound
connic answers 200 once it has stored a queued run for every linked agent, before those runs execute, and Pub/Sub acknowledges the message. Stored runs survive worker restarts and deployments. Since connic doesn't hold a message until its runs finish, long runs never reach the subscription's acknowledgement deadline.
When the Project has no active deployment or the runs can't be stored, connic answers 503, and 429 when the connector's request limit is reached. Pub/Sub retries both with its backoff, as it does after every answer other than 200. To hold on to messages that fail again and again, such as data connic can't read, give the subscription a dead-letter topic.
Run IDs come from the message ID, so a message that Pub/Sub delivers again starts no new run. A run that fails after it was stored causes no redelivery; it keeps its full input, so you can rerun it.
Runs execute in parallel up to max_concurrent_runs, so runs of two messages with the same ordering key can overlap. To run them one at a time in arrival order, add a concurrency rule on the ordering key:
concurrency:
key: _google_pubsub.ordering_key
on_conflict: queueMessages without an ordering key still run in parallel.
Outbound delivery
Modes: Outbound
An outbound Google Pub/Sub connector publishes one message to its topic each time it's used: 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. The message data is JSON.
Automatic payload
An automatic link publishes the completed run as the message data, the same envelope that Kafka, SQS, and RabbitMQ connectors publish:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "order-processor",
"status": "completed",
"output": "Order A-1001 approved for standard shipping.",
"error": null,
"started_at": "2026-11-17T09:13:56Z",
"ended_at": "2026-11-17T09:14:01Z",
"token_usage": {
"input_tokens": 150,
"output_tokens": 50,
"thinking_tokens": 0,
"cached_input_tokens": 0,
"total_tokens": 200
}
}The message carries run_id, agent_name, and status as attributes, so subscriptions can filter on them:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "order-processor",
"status": "completed"
}When the run started from an inbound Pub/Sub message with an ordering key, the published message keeps that ordering key. To build a pipeline, link an inbound Google Pub/Sub connector and an automatic outbound one to the same agent; the agent's output arrives in output. Automatic sources describes which runs publish.
Agent-tool and middleware payload
The model or middleware passes the message data as an object under payload, which is required, and optionally attributes, an object of text values, and an ordering_key. Other fields are rejected, and attribute values that aren't text fail the delivery. connic adds the topic, the sign-in, and the retries, none of which the model sees.
{
"payload": {
"order_id": "A-1001",
"status": "approved"
},
"attributes": {
"event": "order.approved"
},
"ordering_key": "customer-42"
}Delivery and retries
connic signs in as the Connection's service account and publishes the message. The connector's runs show each delivery with the published message ID, or with the error. Rate limits, Google server errors, and connection errors are tried 3 times in total; on a rate limit, connic waits as long as Google asks. Other errors fail at once: 403 means the service account lacks the Pub/Sub Publisher role on the topic, and 404 that the topic doesn't exist.
Publishing is at least once: when an answer from Google gets lost, the retry can publish the message twice. Subscribers can drop duplicates of automatic messages by their run_id attribute. Messages with the same ordering key arrive in order only on subscriptions with message ordering turned on.
Limits and errors
| Limit | Value |
|---|---|
| Push request | 10 MiB. Pub/Sub sends the data base64-encoded, so data above roughly 7.5 MB can't be received. |
| Failed pushes | Pub/Sub retries them with exponential backoff between 100 ms and 60 seconds, until the message expires or the subscription's dead-letter topic takes it. |
| Published message data | 10 MB, per Pub/Sub quotas and limits |
| Attributes | 100 per message, names up to 256 bytes, values up to 1,024 bytes |
| Ordering key | Publishing up to 1 MBps per ordering key |
| Publish attempts | 3, for rate limits, Google server errors, and connection errors |
A push request gets one of these answers. Pub/Sub retries the message after every answer other than 200.
| Status | Meaning |
|---|---|
| 200 | The runs are stored, and Pub/Sub acknowledges the message. A paused connector, or one without linked agents, also answers 200 and starts no run; the message is gone. |
| 400 | The request isn't a wrapped push message, for example from a subscription with --push-no-wrapper, or its data is neither JSON nor UTF-8 text. |
| 401 | The token is missing or doesn't pass the check. |
| 404 | No inbound Google Pub/Sub connector exists at this URL. |
| 413 | The request is larger than 10 MiB. |
| 429 | The connector's request limit is reached. |
| 503 | The Project has no active deployment, the runs couldn't be stored, or Google's signing keys couldn't be fetched. |
Saving an inbound connector fails when the push service account isn't an email address, and saving an outbound connector fails without a Connection or when the topic isn't a full topic name. When Google rejects the service account's sign-in, for example because the key was deleted, the delivery fails; a server error during sign-in is retried.