Google Pub/Sub
Agenten mit den Nachrichten einer Push-Subscription von Google Cloud Pub/Sub starten oder Run-Ergebnisse in einem Topic veröffentlichen.
Auf dieser Seite
| Modi | Inbound, Outbound |
| YAML-Typ | google_pubsub |
| Zugangsdaten | Inbound: keine, denn jede Push-Anfrage bringt ein von Google signiertes Token mit. Outbound: ein Kontozugang (Connection) vom Typ google_pubsub mit dem JSON-Schlüssel deines eigenen Google-Cloud-Dienstkontos. |
| Bridge | Nicht unterstützt |
| Custom Domain | Nicht unterstützt |
| Verknüpfte Agenten | Einer oder mehrere. Jede Nachricht startet alle verknüpften Agenten. |
| Während der Pause | Inbound: Nachrichten erhalten 200 und starten keine Runs, Pub/Sub verwirft sie also. Outbound veröffentlicht nichts. |
Einrichtung
Eine Inbound-Verbindung empfängt die Nachrichten einer Push-Subscription, eine Outbound-Verbindung veröffentlicht in einem Topic. Richte den Modus ein, den du brauchst, oder beide mit je einer Verbindung.
Nachrichten empfangen
Wähle das Dienstkonto, mit dem sich die Push-Subscription authentifiziert. Es muss im selben Google-Cloud-Projekt liegen wie die Subscription, und wer die Subscription anlegt, braucht dafür
iam.serviceAccounts.actAs, etwa überroles/iam.serviceAccountUser. Laut Google gibst du außerdem dem Pub/Sub-Dienst-Agenten die Rolle Ersteller von Dienstkonto-Tokens:Terminalgcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"Öffne in connic den Agenten. Klicke im Connector Flow auf Add inbound connector, dann auf Create New Connector, und wähle Google Pub/Sub.
Wähle Inbound (Push subscription), trag unter Push service account die E-Mail-Adresse des Dienstkontos ein und klicke auf Create. Audience (Optional) bleibt leer, solange die Subscription keine eigene Audience festlegt. Kopiere den Push endpoint aus dem Detailbereich.
Lege am Topic eine Push-Subscription mit diesem Endpunkt an, die sich mit dem Dienstkonto authentifiziert:
Terminalgcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --push-auth-service-account=SERVICE_ACCOUNT_EMAILSetzt du
--push-auth-token-audience=AUDIENCE, trag denselben Wert in connic unter Audience (Optional) ein. Für eine bestehende Subscription nutzt dugcloud pubsub subscriptions modify-push-config SUBSCRIPTION_IDmit denselben Flags. Behalte das Standardformat von Pub/Sub bei: Nachrichten einer Subscription mit--push-no-wrapperlehnt connic ab. In der Google Cloud Console entspricht das dem Zustellungstyp Push, der Endpunkt-URL und der Authentifizierung mit dem Dienstkonto, ohne das Entpacken der Payload.
Nachrichten veröffentlichen
Gib dem Dienstkonto, das veröffentlicht, die Rolle Pub/Sub-Publisher am Topic und erstelle einen JSON-Schlüssel dafür. Google lädt die Schlüsseldatei einmal herunter und kann sie danach nicht erneut anzeigen.
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_EMAILIn Google-Cloud-Organisationen, die am 3. Mai 2024 oder später angelegt wurden, verhindert die Organisationsrichtlinie
iam.managed.disableServiceAccountKeyCreationstandardmäßig, dass Dienstkonto-Schlüssel erstellt werden. Ein Administrator für Organisationsrichtlinien muss das zuerst für das Projekt erlauben; mehr dazu bei Google unter standardmäßig sichere Organisationen.Öffne in connic Project Settings → Connections, klicke auf New connection und wähle Google Pub/Sub. Den Kontozugang kannst du auch über die Auswahl Connection im Formular der Verbindung anlegen. Gib einen Name ein, füge den Inhalt der Schlüsseldatei unter Service account key (JSON) ein und klicke auf Create connection.
Öffne den Agenten. Klicke im Connector Flow auf Add outbound connector, dann auf Create New Connector, und wähle Google Pub/Sub.
Wähle Outbound (Publish), unter Connection den Kontozugang und trag das Topic mit seinem vollständigen Namen ein, etwa
projects/acme/topics/order-results. Klicke auf Create, wähle dann, wie der Agent die Verbindung nutzt, und klicke auf Link connector.
Im Code
Deklariere die Verbindung in connectors/*.yaml. Eine Inbound-Verbindung nennt keinen Kontozugang. Ihren Push-Endpunkt legt das erste Deployment an; die Subscription richtest du danach ein. Eine Outbound-Verbindung nennt den Kontozugang mit dem Schlüssel des Dienstkontos.
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 # Kontozugang mit dem Dienstkonto-Schlüssel
config:
topic: projects/acme/topics/order-results
agents:
- name: order-processor
outbound: { usage: automatic }Konfiguration
Die Felder einer Google-Pub/Sub-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Felder, die alle Verbindungen teilen, etwa agents und environments, beschreibt Verbindungen im Code.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| type | string | Required | google_pubsub. |
| mode | string | Required | inbound oder outbound. Dashboard: Mode. |
| connection | string | Optional | Outbound, dort Pflicht. Name oder ID eines Kontozugangs vom Typ google_pubsub; siehe Kontozugang. Inbound-Verbindungen brauchen keinen, lass das Feld dort weg. Dashboard: Connection. |
| config | object | Required | Einstellungen für Google Pub/Sub. |
| push_service_account | string | Required | Inbound. E-Mail-Adresse des Dienstkontos, mit dem sich die Push-Subscription authentifiziert, etwa pubsub-push@acme.iam.gserviceaccount.com. Anfragen mit einem Token für ein anderes Konto lehnt connic ab. Dashboard: Push service account. |
| audience | string | Optional | Inbound. Die Audience, die an der Push-Subscription eingestellt ist. Bleibt leer, wenn die Subscription ihre Standard-Audience nutzt, den Push-Endpunkt. Dashboard: Audience (Optional). |
| topic | string | Required | Outbound. Vollständiger Name des Topics, projects/<project>/topics/<topic>. Dashboard: Topic. |
Kontozugang
Ein Kontozugang vom Typ google_pubsub, auf der Seite Connections als Google Pub/Sub aufgeführt, enthält ein einziges Feld. Alle Outbound-Verbindungen für Google Pub/Sub im Projekt können ihn nutzen, und die config einer Verbindung nimmt das Feld nicht an. Verwalte Kontozugänge unter Project Settings → Connections oder über die REST API; eine Änderung gilt für alle Verbindungen, die den Kontozugang nutzen.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| service_account_key | string | Required | Der Inhalt einer JSON-Schlüsseldatei eines Google-Cloud-Dienstkontos mit der Rolle Pub/Sub-Publisher am Topic. Beim Speichern prüft connic, ob es ein Dienstkonto-Schlüssel mit lesbarem privatem Schlüssel ist. Secret. Dashboard: Service account key (JSON). |
Um den Schlüssel zu wechseln, erstellst du einen neuen, trägst ihn im Kontozugang ein und löschst danach den alten in Google Cloud.
Erzeugte Werte
| Wert | Modi | Beschreibung |
|---|---|---|
| Push-Endpunkt | Inbound | Die URL, an die Pub/Sub die Nachrichten schickt, https://connect.connic.co/google-pubsub/<connector-id>. connic legt sie mit der Verbindung an und behält sie über Änderungen und Deployments hinweg. Du kopierst sie im Detailbereich unter Push endpoint. |
Input des Agenten
Modi: Inbound
Jede Nachricht wird zum Input aller verknüpften Agenten. connic dekodiert die Daten der Nachricht aus Base64. Ein JSON-Objekt behält seine Schlüssel auf oberster Ebene, und connic ergänzt die Metadaten der Nachricht unter _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" }
}
}subscriptionist der vollständige Name der Subscription, die die Nachricht geschickt hat.message_idundpublish_timesind die ID und der Veröffentlichungszeitpunkt, die Pub/Sub der Nachricht gegeben hat.ordering_keyist der Ordering Key der Nachricht odernull, wenn sie keinen hat.attributesenthält die Attribute der Nachricht als Objekt; hat sie keine, ist es leer.
Alle anderen Daten stehen unter message: Text als String, andere JSON-Werte wie ein Array oder eine Zahl geparst. Eine Nachricht, die nur Attribute hat, kommt mit message: null an. Daten, die weder JSON noch UTF-8-Text sind, lehnt connic mit 400 ab.
Authentifizierung der Push-Anfragen
Modi: Inbound
Eine Subscription mit Authentifizierung schickt bei jeder Push-Anfrage im Header Authorization: Bearer ein OIDC-Token mit, das Google signiert. connic prüft die Signatur von Google, ob accounts.google.com das Token ausgestellt hat, ob seine Audience die Audience der Verbindung ist oder, ohne eine solche, der Push-Endpunkt, und ob es zum Push service account mit bestätigter E-Mail-Adresse gehört. Anfragen ohne ein solches Token erhalten 401 und starten keine Runs. Wer nur den Push-Endpunkt kennt, kann also keinen Agenten starten.
Pub/Sub wertet die 401 als fehlgeschlagene Zustellung und versucht die Nachricht erneut. Änderst du Dienstkonto oder Audience der Subscription, passe die Verbindung entsprechend an.
Zustellung und Reihenfolge
Modi: Inbound
connic antwortet mit 200, sobald für jeden verknüpften Agenten ein Run in der Warteschlange gespeichert ist, also bevor diese Runs laufen, und Pub/Sub bestätigt die Nachricht. Gespeicherte Runs überstehen Neustarts und Deployments. Weil connic eine Nachricht nicht bis zum Ende ihrer Runs festhält, erreichen auch lange Runs nie die Bestätigungsfrist der Subscription.
Hat das Projekt kein aktives Deployment oder lassen sich die Runs nicht speichern, antwortet connic mit 503. Ist das Anfragelimit der Verbindung erreicht, antwortet es mit 429. Pub/Sub versucht beides mit seinem Backoff erneut, wie nach jeder Antwort außer 200. Für Nachrichten, die immer wieder scheitern, etwa weil connic ihre Daten nicht lesen kann, richtest du an der Subscription ein Dead-Letter-Topic ein.
Die Run-IDs leiten sich aus der Nachrichten-ID ab. Stellt Pub/Sub eine Nachricht erneut zu, startet sie deshalb keinen neuen Run. Schlägt ein Run nach dem Speichern fehl, folgt keine erneute Zustellung. Der Run behält seinen vollständigen Input, sodass du ihn erneut ausführen kannst.
Runs laufen parallel bis zu max_concurrent_runs, die Runs zweier Nachrichten mit demselben Ordering Key können sich also überschneiden. Sollen sie einzeln in Eingangsreihenfolge laufen, ergänzt du eine Concurrency-Regel auf dem Ordering Key:
concurrency:
key: _google_pubsub.ordering_key
on_conflict: queueNachrichten ohne Ordering Key laufen weiterhin parallel.
Outbound-Zustellung
Modi: Outbound
Eine Outbound-Verbindung für Google Pub/Sub veröffentlicht bei jeder Nutzung eine Nachricht in ihrem Topic. Je nach Nutzung der Verknüpfung ist das der Fall, wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn die Middleware sie aufruft. Die Daten der Nachricht sind JSON.
Automatische Payload
Eine automatische Verknüpfung veröffentlicht den abgeschlossenen Run als Daten der Nachricht, im selben Format, das auch Kafka-, SQS- und RabbitMQ-Verbindungen veröffentlichen:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "order-processor",
"status": "completed",
"output": "Bestellung A-1001 für den Standardversand freigegeben.",
"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
}
}Die Nachricht trägt run_id, agent_name und status als Attribute, nach denen Subscriptions filtern können:
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "order-processor",
"status": "completed"
}Hat eine eingehende Pub/Sub-Nachricht mit Ordering Key den Run gestartet, behält die veröffentlichte Nachricht diesen Ordering Key. Für eine Pipeline verknüpfst du eine Inbound- und eine automatische Outbound-Verbindung für Google Pub/Sub mit demselben Agenten; die Ausgabe des Agenten steht dann in output. Welche Runs veröffentlicht werden, beschreibt Automatische Quellen.
Payload für Agent-Tool und Middleware
Das Modell oder die Middleware übergibt die Daten der Nachricht als Objekt unter payload, das Pflicht ist, und optional attributes, ein Objekt mit Textwerten, sowie einen ordering_key. Andere Felder lehnt connic ab, und Attributwerte, die kein Text sind, lassen die Zustellung fehlschlagen. connic ergänzt Topic, Anmeldung und Wiederholungen. Davon sieht das Modell nichts.
{
"payload": {
"order_id": "A-1001",
"status": "approved"
},
"attributes": {
"event": "order.approved"
},
"ordering_key": "customer-42"
}Zustellung und Wiederholungen
connic meldet sich als Dienstkonto des Kontozugangs an und veröffentlicht die Nachricht. Die Runs der Verbindung zeigen jede Zustellung mit der ID der veröffentlichten Nachricht oder mit dem Fehler. Bei Rate Limits, Serverfehlern von Google und Verbindungsfehlern versucht connic es insgesamt dreimal und wartet bei einem Rate Limit so lange, wie Google es verlangt. Andere Fehler beenden die Zustellung sofort: 403 heißt, dass dem Dienstkonto die Rolle Pub/Sub-Publisher am Topic fehlt, 404, dass es das Topic nicht gibt.
connic veröffentlicht jede Nachricht mindestens einmal: Geht eine Antwort von Google verloren, kann die Wiederholung die Nachricht ein zweites Mal veröffentlichen. Subscriber erkennen Duplikate automatischer Nachrichten am Attribut run_id. Nachrichten mit demselben Ordering Key kommen nur bei Subscriptions mit aktivierter Nachrichtenreihenfolge in Reihenfolge an.
Limits und Fehler
| Limit | Wert |
|---|---|
| Push-Anfrage | 10 MiB. Pub/Sub sendet die Daten Base64-kodiert, Daten über etwa 7,5 MB kommen also nicht an. |
| Fehlgeschlagene Push-Anfragen | Pub/Sub wiederholt sie mit exponentiellem Backoff zwischen 100 ms und 60 Sekunden, bis die Nachricht abläuft oder das Dead-Letter-Topic der Subscription sie übernimmt. |
| Daten veröffentlichter Nachrichten | 10 MB, laut den Kontingenten und Limits von Pub/Sub |
| Attribute | 100 je Nachricht, Namen bis 256 Byte, Werte bis 1.024 Byte |
| Ordering Key | Veröffentlichen mit bis zu 1 MB/s je Ordering Key |
| Veröffentlichungsversuche | 3, bei Rate Limits, Serverfehlern von Google und Verbindungsfehlern |
Eine Push-Anfrage erhält eine dieser Antworten. Nach jeder Antwort außer 200 versucht Pub/Sub die Nachricht erneut.
| Status | Bedeutung |
|---|---|
| 200 | Die Runs sind gespeichert, und Pub/Sub bestätigt die Nachricht. Auch eine pausierte Verbindung oder eine ohne verknüpfte Agenten antwortet mit 200 und startet keinen Run; die Nachricht ist dann weg. |
| 400 | Die Anfrage enthält keine Push-Nachricht im Standardformat von Pub/Sub, etwa weil die Subscription --push-no-wrapper nutzt, oder ihre Daten sind weder JSON noch UTF-8-Text. |
| 401 | Das Token fehlt oder besteht die Prüfung nicht. |
| 404 | Unter dieser URL gibt es keine Inbound-Verbindung für Google Pub/Sub. |
| 413 | Die Anfrage ist größer als 10 MiB. |
| 429 | Das Anfragelimit der Verbindung ist erreicht. |
| 503 | Das Projekt hat kein aktives Deployment, die Runs ließen sich nicht speichern, oder die Signaturschlüssel von Google waren nicht abrufbar. |
Eine Inbound-Verbindung lässt sich nicht speichern, wenn das Push-Dienstkonto keine E-Mail-Adresse ist, eine Outbound-Verbindung nicht ohne Kontozugang oder wenn das Topic nicht mit vollständigem Namen angegeben ist. Lehnt Google die Anmeldung des Dienstkontos ab, etwa weil der Schlüssel gelöscht wurde, schlägt die Zustellung fehl; bei einem Serverfehler während der Anmeldung versucht connic es erneut.