Zum Hauptinhalt springen
connic
Starte kostenlos
Verbindungen

Google Pub/Sub

Agenten mit den Nachrichten einer Push-Subscription von Google Cloud Pub/Sub starten oder Run-Ergebnisse in einem Topic veröffentlichen.

Zuletzt aktualisiert
ModiInbound, Outbound
YAML-Typgoogle_pubsub
ZugangsdatenInbound: 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.
BridgeNicht unterstützt
Custom DomainNicht unterstützt
Verknüpfte AgentenEiner oder mehrere. Jede Nachricht startet alle verknüpften Agenten.
Während der PauseInbound: 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

  1. 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 über roles/iam.serviceAccountUser. Laut Google gibst du außerdem dem Pub/Sub-Dienst-Agenten die Rolle Ersteller von Dienstkonto-Tokens:

    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. Öffne in connic den Agenten. Klicke im Connector Flow auf Add inbound connector, dann auf Create New Connector, und wähle Google Pub/Sub.

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

  4. Lege am Topic eine Push-Subscription mit diesem Endpunkt an, die sich mit dem Dienstkonto authentifiziert:

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

    Setzt du --push-auth-token-audience=AUDIENCE, trag denselben Wert in connic unter Audience (Optional) ein. Für eine bestehende Subscription nutzt du gcloud pubsub subscriptions modify-push-config SUBSCRIPTION_ID mit denselben Flags. Behalte das Standardformat von Pub/Sub bei: Nachrichten einer Subscription mit --push-no-wrapper lehnt 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

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

    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

    In Google-Cloud-Organisationen, die am 3. Mai 2024 oder später angelegt wurden, verhindert die Organisationsrichtlinie iam.managed.disableServiceAccountKeyCreation standardmäß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.

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

  3. Öffne den Agenten. Klicke im Connector Flow auf Add outbound connector, dann auf Create New Connector, und wähle Google Pub/Sub.

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

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

FeldTypStatusBeschreibung
typestringRequiredgoogle_pubsub.
modestringRequiredinbound oder outbound. Dashboard: Mode.
connectionstringOptionalOutbound, dort Pflicht. Name oder ID eines Kontozugangs vom Typ google_pubsub; siehe Kontozugang. Inbound-Verbindungen brauchen keinen, lass das Feld dort weg. Dashboard: Connection.
configobjectRequiredEinstellungen für Google Pub/Sub.
push_service_accountstringRequiredInbound. 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.
audiencestringOptionalInbound. Die Audience, die an der Push-Subscription eingestellt ist. Bleibt leer, wenn die Subscription ihre Standard-Audience nutzt, den Push-Endpunkt. Dashboard: Audience (Optional).
topicstringRequiredOutbound. 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.

FeldTypStatusBeschreibung
service_account_keystringRequiredDer 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

WertModiBeschreibung
Push-EndpunktInboundDie 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:

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 ist der vollständige Name der Subscription, die die Nachricht geschickt hat.
  • message_id und publish_time sind die ID und der Veröffentlichungszeitpunkt, die Pub/Sub der Nachricht gegeben hat.
  • ordering_key ist der Ordering Key der Nachricht oder null, wenn sie keinen hat.
  • attributes enthä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:

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

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

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

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

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

LimitWert
Push-Anfrage10 MiB. Pub/Sub sendet die Daten Base64-kodiert, Daten über etwa 7,5 MB kommen also nicht an.
Fehlgeschlagene Push-AnfragenPub/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 Nachrichten10 MB, laut den Kontingenten und Limits von Pub/Sub
Attribute100 je Nachricht, Namen bis 256 Byte, Werte bis 1.024 Byte
Ordering KeyVeröffentlichen mit bis zu 1 MB/s je Ordering Key
Veröffentlichungsversuche3, 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.

StatusBedeutung
200Die 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.
400Die 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.
401Das Token fehlt oder besteht die Prüfung nicht.
404Unter dieser URL gibt es keine Inbound-Verbindung für Google Pub/Sub.
413Die Anfrage ist größer als 10 MiB.
429Das Anfragelimit der Verbindung ist erreicht.
503Das 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.