Skip to main content
connic

Google Pub/Sub

Every message a Pub/Sub push subscription delivers starts an agent run, checked with the token Google signs. Results go to a topic as JSON messages with attributes.

Modes
Inbound, Outbound
Set up in
Dashboard or connectors/*.yaml
Documentation
Google Pub/Sub docs
Publisher
By connic

Turn every Pub/Sub message into an agent run

An inbound connector receives the messages of a push subscription and starts each linked agent once per message, with the message as its input.

JSON keeps its shape
connic decodes the data. A JSON object arrives with its top-level keys, plus _google_pubsub with the subscription, message ID, publish time, ordering key and attributes.
Text arrives as text
Any other data arrives under message: text as a string, other JSON values as parsed. A message with only attributes has message: null.
One run per message
Run IDs come from the message ID, so a message that Pub/Sub delivers again starts no new run.
message on orders (data decoded)
{
  "data": { "order_id": "A-1001", "customer": "jana@example.com", "total": 49.9 },
  "attributes": { "event": "order.created" },
  "orderingKey": "customer-42"
}
context["payload"]
{
  "order_id": "A-1001",
  "customer": "jana@example.com",
  "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" }
  }
}

No key to receive: Google signs every push

Pub/Sub sends a token signed by Google with every push request. connic starts runs only when the token belongs to your push service account and names the right audience.

Your service account
The push subscription authenticates with a service account in your own Google Cloud project. Receiving needs no key on the connic side.
Long runs don't hold messages
connic answers once the runs are stored, not when they finish, so long runs never reach the acknowledgement deadline.
Retries stay with Pub/Sub
Without a 200, Pub/Sub retries the message with its backoff until it expires or the dead-letter topic takes it.
  1. Pub/Sub pushes a message

    The push subscription sends the message to the connector's push endpoint, with an OIDC token for its service account.

    Authorization: Bearer
  2. connic checks the token

    Google's signature, the issuer, the audience, and the verified email of the push service account. Any other request gets 401 and starts nothing.

  3. Runs are stored

    connic stores a queued run for every linked agent and answers 200, so Pub/Sub acknowledges the message.

    200
  4. Agents run

    Runs execute in parallel up to max_concurrent_runs. A concurrency rule on the ordering key runs messages with the same key one at a time.

    concurrency.key: _google_pubsub.ordering_key

Keep the connector next to your agents

Declare it as a YAML file in connectors/. An inbound connector names only the push service account, and its push endpoint is created on the first deploy.

One gcloud command
Create the push subscription with the endpoint and the service account in one command. The docs have it, along with the roles Google asks for.
Optional audience
Leave the audience empty to use the default, the push endpoint, or set the same custom audience on the subscription and in connic.
connectors/order-events.yaml
type: google_pubsub
mode: inbound
name: Order events
config:
  push_service_account: pubsub-push@acme.iam.gserviceaccount.com
agents:
  - order-processor
create: connectors/order-events.yaml (google_pubsub)

Publish results to a topic

An outbound connector publishes each completed run to a topic as JSON, with run_id, agent_name and status as attributes that subscriptions can filter on.

Ordering keys carry over
A run that started from a message with an ordering key publishes its result with the same key.
Let the agent publish
Linked as an agent tool, the connector lets the model publish its own payload during the run, with attributes and an ordering key.
Your service account publishes
A Connection holds the JSON key of a service account with the Pub/Sub Publisher role on the topic. Rate limits and Google server errors are retried.
connectors/order-results.yaml
type: google_pubsub
mode: outbound
name: Order results
connection: acme-pubsub
config:
  topic: projects/acme/topics/order-results
agents:
  - name: order-processor
    outbound:
      usage: automatic
      source: [order-events]
data on order-results
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "order-processor",
  "status": "completed",
  "output": "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": 642,
    "output_tokens": 38,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 680
  }
}
attributes on order-results
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "order-processor",
  "status": "completed"
}

Where Google Pub/Sub fits

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

Each order event starts a run, and the result lands on the order-results topic with the order's ordering key.

Checkout service
Pub/Sub push
order-processor
Result on order-results
context["payload"]
{
  "order_id": "A-1001",
  "customer": "jana@example.com",
  "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" }
  }
}
data on order-results
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "order-processor",
  "status": "completed",
  "output": "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": 642,
    "output_tokens": 38,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 680
  }
}

The agent reads each new product review and publishes its decision with an attribute your shop can filter on.

Product reviews
Pub/Sub push
review-moderator
Decision on reviews-moderated
context["payload"]
{
  "review_id": "R-7781",
  "product": "trail-runner-2",
  "rating": 1,
  "text": "Sole came off after two weeks. Get the same shoe for half the price at cheap-sneakers.example!",
  "_google_pubsub": {
    "subscription": "projects/acme/subscriptions/reviews-connic",
    "message_id": "2070443601311622",
    "publish_time": "2026-11-17T09:13:55.749Z",
    "ordering_key": null,
    "attributes": { "source": "shop" }
  }
}
connector-payload.json
{
  "payload": {
    "review_id": "R-7781",
    "decision": "hold",
    "reason": "Links to another shop"
  },
  "attributes": { "decision": "hold" }
}

Your monitoring publishes an alert, and the agent posts a short summary to the on-call channel in Slack.

Monitoring
Pub/Sub push
alert-summarizer
Message in Slack
context["payload"]
{
  "service": "checkout",
  "alert": "Error rate above 5%",
  "error_rate": 0.12,
  "window": "5m",
  "_google_pubsub": {
    "subscription": "projects/acme/subscriptions/alerts-connic",
    "message_id": "2070443601311705",
    "publish_time": "2026-11-17T09:13:55.749Z",
    "ordering_key": null,
    "attributes": { "severity": "high" }
  }
}
connector-payload.json
{
  "text": "Checkout error rate is at 12% over the last 5 minutes, above the 5% alert threshold."
}

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

Warehouse system
Pub/Sub push
delay-notifier
Email to the customer
context["payload"]
{
  "shipment_id": "shp_5531",
  "order_id": "A-1001",
  "customer": "jana@example.com",
  "status": "delayed",
  "new_eta": "2026-11-20",
  "_google_pubsub": {
    "subscription": "projects/acme/subscriptions/shipments-connic",
    "message_id": "2070443601311814",
    "publish_time": "2026-11-17T09:13:55.749Z",
    "ordering_key": "A-1001",
    "attributes": {}
  }
}
connector-payload.json
{
  "body": "Your order A-1001 is running late. It now arrives on November 20.",
  "to": "jana@example.com",
  "subject": "New delivery date for your order"
}

Google Pub/Sub FAQ

Add a Google Pub/Sub connector in Inbound (Push subscription) mode, enter the email of the service account your push subscription authenticates with, and link the agent. Then point a push subscription on your topic at the connector's push endpoint, with authentication by that service account. Each message starts a run for every linked agent.

None for receiving: every push request carries a token Google signs for your service account, and connic checks it. To publish, connic needs a Connection with the JSON key of a service account that has the Pub/Sub Publisher role on the topic.

No. Run IDs come from the Pub/Sub message ID, so a message that Pub/Sub delivers again starts no new run. connic acknowledges a message once its runs are stored, before they execute.

Pub/Sub retries every push that doesn't get a 200, with exponential backoff, until the message expires or the subscription's dead-letter topic takes it. connic rejects requests without a valid token, payloads unwrapped by the subscription, and data that is neither JSON nor UTF-8 text. The Google Pub/Sub docs list every answer.