Skip to main content
connic
Connectors

Google Pub/Sub

Start agents from the messages a Google Cloud Pub/Sub push subscription delivers, or publish run results to a topic.

Last updated
ModesInbound, outbound
YAML typegoogle_pubsub
CredentialsInbound: 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.
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. A message starts every linked agent.
While pausedInbound: 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

  1. 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.actAs on it, for example through roles/iam.serviceAccountUser. Google's docs also have you grant the Pub/Sub service agent the Service Account Token Creator role:

    Terminal
    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com" \
      --role="roles/iam.serviceAccountTokenCreator"
  2. In connic, open the agent. In Connector Flow, click Add inbound connector, then Create New Connector, and choose Google Pub/Sub.

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

  4. Create a push subscription on the topic with that endpoint and authentication by the service account:

    Terminal
    gcloud pubsub subscriptions create SUBSCRIPTION_ID \
      --topic=TOPIC_ID \
      --push-endpoint=PUSH_ENDPOINT \
      --push-auth-service-account=SERVICE_ACCOUNT_EMAIL

    With --push-auth-token-audience=AUDIENCE, enter the same value as Audience (Optional) in connic. For an existing subscription, run gcloud pubsub subscriptions modify-push-config SUBSCRIPTION_ID with 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

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

    Terminal
    gcloud pubsub topics add-iam-policy-binding TOPIC_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role="roles/pubsub.publisher"
    Terminal
    gcloud iam service-accounts keys create key.json \
      --iam-account=SERVICE_ACCOUNT_EMAIL

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

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

  3. Open the agent. In Connector Flow, click Add outbound connector, then Create New Connector, and choose Google Pub/Sub.

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

connectors/order-events.yaml
type: google_pubsub
mode: inbound
config:
  push_service_account: pubsub-push@acme.iam.gserviceaccount.com
agents:
  - order-processor
connectors/order-results.yaml
type: 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.

FieldTypeStatusDescription
typestringRequiredgoogle_pubsub.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringOptionalOutbound, 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.
configobjectRequiredGoogle Pub/Sub settings.
push_service_accountstringRequiredInbound. 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.
audiencestringOptionalInbound. The audience set on the push subscription. Leave it empty when the subscription uses its default audience, the push endpoint. Dashboard: Audience (Optional).
topicstringRequiredOutbound. 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.

FieldTypeStatusDescription
service_account_keystringRequiredThe 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

ValueModesDescription
Push endpointInboundThe 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:

payload.json
{
  "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" }
  }
}
  • subscription is the full name of the subscription that pushed the message.
  • message_id and publish_time are the ID and publish time Pub/Sub gave the message.
  • ordering_key is the message's ordering key, or null when it has none.
  • attributes holds 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:

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

Messages 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:

data.json
{
  "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:

attributes.json
{
  "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.

connector-payload.json
{
  "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

LimitValue
Push request10 MiB. Pub/Sub sends the data base64-encoded, so data above roughly 7.5 MB can't be received.
Failed pushesPub/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 data10 MB, per Pub/Sub quotas and limits
Attributes100 per message, names up to 256 bytes, values up to 1,024 bytes
Ordering keyPublishing up to 1 MBps per ordering key
Publish attempts3, 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.

StatusMeaning
200The 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.
400The 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.
401The token is missing or doesn't pass the check.
404No inbound Google Pub/Sub connector exists at this URL.
413The request is larger than 10 MiB.
429The connector's request limit is reached.
503The 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.