Zum Hauptinhalt springen
connic
Starte kostenlos
Verbindungen

Google Sheets

Agenten mit neuen Zeilen in einer Google-Sheets-Tabelle starten und ihre Ergebnisse als Zeilen anfügen, über dein eigenes Google-Dienstkonto.

Zuletzt aktualisiert
ModiInbound, Outbound
YAML-Typgoogle_sheets
ZugangsdatenEin Kontozugang (Connection) vom Typ gmail, im Dashboard Google Workspace genannt, mit dem JSON-Schlüssel deines eigenen Google-Dienstkontos. Gmail-Verbindungen können denselben Kontozugang nutzen.
TabellenTabellen, die für die E-Mail-Adresse des Dienstkontos freigegeben sind
BridgeNicht unterstützt
Custom DomainNicht unterstützt
Verknüpfte AgentenEiner oder mehrere. Jede neue Zeile startet alle verknüpften Agenten.
Während der PauseInbound prüft das Tabellenblatt nicht mehr. Zeilen, die in der Zeit hinzukommen, werden nach Resume verarbeitet. Outbound fügt nichts an.

Einrichtung

  1. Lege in einem Google-Cloud-Projekt mit aktivierter Google Sheets API ein Dienstkonto mit JSON-Schlüssel an. Gib die Tabelle für die E-Mail-Adresse des Dienstkontos frei: als Betrachter für Inbound, als Bearbeiter für Outbound.

  2. Öffne den Agenten. Klicke im Connector Flow für Inbound auf Add inbound connector oder für Outbound auf Add outbound connector. Klicke dann auf Create New Connector und wähle Google Sheets.

  3. Wähle den Modus. Wähle unter Connection einen gespeicherten Google-Workspace-Kontozugang oder lege einen mit dem Inhalt der Schlüsseldatei an.

  4. Gib das Spreadsheet ein und, wenn es nicht das erste Tabellenblatt sein soll, das Sheet.

  5. Klicke auf Create. Eine Inbound-Verbindung beginnt dann, das Tabellenblatt zu prüfen. Bei Outbound legst du fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.

Im Code

Deklariere die Verbindung in connectors/*.yaml. connection nennt den Kontozugang mit dem Schlüssel des Dienstkontos.

connectors/new-leads.yaml
type: google_sheets
mode: inbound
connection: acme-google   # Google-Workspace-Kontozugang mit dem Dienstkonto-Schlüssel
config:
  spreadsheet: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
  sheet: Leads
agents:
  - lead-qualifier
connectors/qualified-leads.yaml
type: google_sheets
mode: outbound
connection: acme-google
config:
  spreadsheet: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
  sheet: Qualifiziert
agents:
  - name: lead-qualifier
    outbound: { usage: automatic }

Konfiguration

Die Felder einer Google-Sheets-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.

FeldTypStatusBeschreibung
typestringRequiredgoogle_sheets.
modestringRequiredinbound oder outbound. Dashboard: Mode.
connectionstringRequiredName oder ID eines Kontozugangs vom Typ gmail. Siehe Dienstkonto. Dashboard: Connection.
configobjectRequiredEinstellungen der Google-Sheets-Verbindung.
spreadsheetstringRequiredDie URL der Tabelle, etwa https://docs.google.com/spreadsheets/d/<ID>/edit, oder ihre ID. connic speichert die ID. Dashboard: Spreadsheet.
sheetstringOptionalDer Name des Tabellenblatts, genau so wie auf seinem Tab. Ohne Angabe nutzt die Verbindung das erste Tabellenblatt. Dashboard: Sheet.

Agent-Input

Modi: Inbound

Eine Inbound-Verbindung prüft das Tabellenblatt etwa jede Minute und startet mit jeder neuen Zeile einen Run für jeden verknüpften Agenten. Zeile 1 enthält die Spaltennamen. Bei ihrer ersten Prüfung setzt die Verbindung nach der letzten Zeile an; Zeilen, die schon da sind, verarbeitet sie nicht. Leere Zeilen überspringt sie. Eine andere Tabelle oder ein anderes Tabellenblatt beginnt ab diesem Zeitpunkt neu. Der Run erhält die Zeile so:

payload.json
{
  "row": {
    "Name": "Jana Schmidt",
    "E-Mail": "jana@example.com",
    "Firma": "Beispiel GmbH",
    "Nachricht": "Wir brauchen ab Januar 40 Plätze."
  },
  "row_number": 12,
  "_google_sheets": {
    "connector_id": "550e8400-e29b-41d4-a716-446655440000",
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "sheet": "Leads",
    "row_number": 12,
    "timestamp": "2026-10-12T08:30:05.123456"
  }
}
  • row hat einen Schlüssel je Spaltenname aus Zeile 1. Die Werte kommen als Text an, so formatiert, wie das Tabellenblatt sie anzeigt, etwa ein Datum oder ein Betrag mit Währung.
  • Eine Spalte ohne Namen oder mit einem Namen, den schon eine Spalte davor trägt, erscheint unter ihrem Spaltenbuchstaben, etwa C. Leere Zellen am Ende der Zeile fehlen.
  • row_number ist die Nummer der Zeile im Tabellenblatt zu dem Zeitpunkt, als connic sie gelesen hat. _google_sheets nennt die Verbindung, die ID der Tabelle, das Tabellenblatt und die Zeilennummer.

Zeilen hinzufügen

connic verarbeitet eine Zeile, sobald es sie zum ersten Mal sieht. Füge jede Zeile deshalb in einem Schritt hinzu, etwa über ein Formular, ein Skript oder durch Einfügen. Tippst du eine Zeile Zelle für Zelle ein, kann ein Run starten, in dem nur die ersten Zellen ausgefüllt sind. Änderungen an schon verarbeiteten Zeilen starten nichts.

Werden oberhalb der zuletzt verarbeiteten Zeile Zeilen eingefügt oder gelöscht, findet connic diese Zeile anhand ihrer Werte an der neuen Stelle und macht danach weiter. Wurde die Zeile geändert oder gelöscht, zeigen die Logs eine Warnung, und connic macht nach derselben Zeilennummer weiter oder, wenn das Tabellenblatt kürzer geworden ist, nach der letzten Zeile.

Dienstkonto

Google-Sheets-Verbindungen nutzen denselben Google-Workspace-Kontozugang wie Gmail; dort steht, wie du das Dienstkonto und seinen Schlüssel anlegst. Aktiviere im Projekt des Dienstkontos die Google Sheets API. Eine domainweite Delegierung brauchen Google-Sheets-Verbindungen nicht: Das Dienstkonto greift in eigenem Namen auf die Tabelle zu und braucht deshalb Zugriff auf jede Tabelle.

  1. Kopiere die E-Mail-Adresse des Dienstkontos. Die Adresse steht als client_email in der Schlüsseldatei und endet auf .iam.gserviceaccount.com.

  2. Klicke in der Tabelle auf Teilen und füge die Adresse hinzu: als Betrachter für eine Inbound-Verbindung, als Bearbeiter für eine Outbound-Verbindung.

Verbieten die Freigabeeinstellungen für Google Drive in deinem Google Workspace das Teilen außerhalb der Organisation, muss ein Admin es für diese Adresse erlauben.

Outbound-Zustellung

Modi: Outbound

Eine Outbound-Google-Sheets-Verbindung fügt bei jeder Nutzung eine Zeile unter den Daten des Tabellenblatts an: wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. connic fügt die neue Zeile ein, sodass nichts unterhalb der Daten überschrieben wird.

Jeder Schlüssel der Zeile nennt eine Spalte aus Zeile 1 und muss ihrem Namen genau entsprechen; Leerzeichen am Anfang und Ende des Spaltennamens zählen nicht. Eine Spalte ohne Namen oder mit einem Namen, den schon eine Spalte davor trägt, sprichst du über ihren Buchstaben an, etwa C. Fehlt ein Schlüssel, bleibt seine Zelle leer. Ein Schlüssel, der keine Spalte ist, lässt die Zustellung fehlschlagen, und der Fehler nennt die Schlüssel. Die Werte werden unverändert geschrieben: Text, der mit = beginnt, bleibt Text und wird nie als Formel ausgeführt, null lässt die Zelle leer, und Objekte und Listen landen als JSON-Text in der Zelle.

Automatische Ausgabe

Eine automatische Verknüpfung fügt die finale Ausgabe des Runs an, die ein JSON-Objekt sein muss. Jede andere Ausgabe lässt die Zustellung mit The agent output must be a JSON object whose keys name columns in the sheet's first row fehlschlagen. Mit einem Output Schema gibt der Agent die Spalten zuverlässig zurück. Diese Ausgabe füllt vier Spalten der neuen Zeile:

output.json
{
  "Name": "Jana Schmidt",
  "E-Mail": "jana@example.com",
  "Score": 82,
  "Nächster Schritt": "Demo vereinbaren"
}

Payload für Agent-Tool und Middleware

Das Modell oder die Middleware übergibt die Spalten unter row. row ist Pflicht, alle anderen Felder werden abgelehnt. Tabelle, Anmeldung und Wiederholungen ergänzt connic, das Modell sieht davon nichts.

connector-payload.json
{
  "row": {
    "Name": "Jana Schmidt",
    "Score": 82,
    "Nächster Schritt": "Demo vereinbaren"
  }
}

Zustellung und Wiederholungen

connic meldet sich als Dienstkonto an, liest die Spaltennamen aus Zeile 1 und fügt die Zeile an. Ist Google Sheets nicht erreichbar oder drosselt es die Anfrage, versucht connic es erneut, insgesamt dreimal, und wartet so lange, wie Google es verlangt. Jeder andere Fehler beendet die Zustellung ohne weiteren Versuch. Bricht die Netzwerkverbindung ab, nachdem die Zeile gesendet wurde, oder antwortet Google mit einem Serverfehler, weiß connic nicht, ob die Zeile angefügt wurde, und versucht es nicht erneut, damit sie nie doppelt erscheint. Prüfe dann das Tabellenblatt. Die Runs der Verbindung zeigen jede Zustellung mit ihrem Fehler.

Limits und Fehler

LimitWert
Prüfung des TabellenblattsEtwa jede Minute
Zeilen pro Prüfung500. Der Rest folgt bei der nächsten Prüfung.
Zustellversuche3, nur wenn Google Sheets nicht erreichbar ist oder die Anfrage drosselt
Limits der Google Sheets API60 Lese- und 60 Schreibanfragen pro Minute je Nutzer und Google-Cloud-Projekt, wobei das Dienstkonto als Nutzer zählt, und je 300 pro Projekt, laut den Nutzungslimits der Sheets API. Jede Prüfung braucht zwei Leseanfragen, jede angefügte Zeile eine Lese- und eine Schreibanfrage. Verbindungen mit demselben Dienstkonto teilen sich diese Limits.

Lehnt Google die Anmeldung ab, etwa weil der Schlüssel gelöscht wurde, ist die Tabelle nicht für das Dienstkonto freigegeben oder die Google Sheets API nicht aktiviert (403), stimmt die ID der Tabelle nicht (404) oder gibt es das Tabellenblatt nicht, zeigen die Logs der Verbindung Polling stopped mit dem Grund. connic prüft dann nicht weiter, bis du die Verbindung oder ihren Kontozugang erneut speicherst. Drosselung, Netzwerk- und Serverfehler erscheinen als Poll error. connic versucht es weiter und wartet nach jedem Fehler länger, bis zu 15 Minuten.

Jede verarbeitete Zeile erscheint in den Runs der Verbindung mit der Zahl der gestarteten Agenten. Lässt sich ein Run nicht starten, liest connic die Zeile bei der nächsten Prüfung erneut. Agenten, die sie schon erhalten haben, bekommen dabei keinen zweiten Run.