Wie bekommt ein KI-Agent Lesezugriff auf die Search Console?
Ein KI-Agent soll in der Google Search Console messen, aber nichts ändern. Welche Rolle Dienstkonto, OAuth-Bereich, ACCESS.md und Guard Rail dabei spielen.
Ein Agent für die Suchmaschinenoptimierung kann eine Seite selbst lesen und Titel, Canonical und hreflang prüfen. Was Google mit derselben Adresse gemacht hat, sieht er von außen nicht: ob sie indexiert ist, welchen Canonical Google stattdessen gewählt hat und mit welchen Suchanfragen Menschen gekommen sind. Diese Antworten stehen in der Google Search Console, und wer sie einem Agenten öffnet, will dazu eine Zusage haben. Der Agent soll messen und an der Property nichts ändern.
Das Beispiel dieses Beitrags ist ein Agent namens SEO-Audit, der täglich die Property sc-domain:example.com ansieht. Er soll für die Adresse https://example.com/blog/agenten herausfinden, warum sie nicht im Index steht. Das Einreichen einer Sitemap bleibt ihm verwehrt.
Der Zugang ist ein Dienstkonto in Google Cloud
Ein gewöhnlicher OAuth-Ablauf setzt voraus, dass jemand im Browser auf „Zulassen“ klickt. Ein Agent hat keinen Browser und um drei Uhr nachts auch niemanden, der klickt. Das Search-Console-Plugin aus dem covey-Plugin-Pack arbeitet deshalb mit einem Google-Dienstkonto, das sich als es selbst anmeldet.
Die Einrichtung des Plugins beschreibt dafür drei Handgriffe in Google Cloud: die „Google Search Console API“ aktivieren, ein Dienstkonto ohne Projektrolle anlegen und dafür einen Schlüssel im Format JSON herunterladen. Der vierte Handgriff liegt in der Search Console selbst, denn dort wird die Mailadresse des Dienstkontos unter Einstellungen, Nutzer und Berechtigungen als Nutzer der Property eingetragen. Fehlt dieser Schritt, antwortet die API nach der Einrichtungsanleitung mit einer leeren Liste statt mit einem Fehler.
In covey landet die ganze Schlüsseldatei als Secret searchconsole_token, die Property als searchconsole_url. Der Verbindungstest ruft list_sites auf, sodass er Schlüssel und Freigabe in einem Aufruf prüft. Findet er keine Property, nennt er die Mailadresse des Dienstkontos und den Ort, an dem die Freigabe fehlt.
Lesende Aktionen fragen Google nur nach dem Lesebereich
Das Plugin kennt fünf Aktionen, und vier davon lesen: list_sites, search_analytics, inspect_url und sitemaps. Die fünfte, submit_sitemap, meldet Google eine Sitemap und ist die einzige, die an der Property etwas ändert.
Google unterscheidet dafür zwei OAuth-Bereiche, webmasters.readonly zum Ansehen und webmasters zum Ansehen und Verwalten. In Googles eigener Beschreibung der API verlangt das Einreichen einer Sitemap den weiten Bereich, während die Abfragen auch mit dem Lesebereich auskommen.
Das Plugin wählt den Bereich je Aktion. Jede lesende Aktion läuft über eine Funktion, die ein Zugriffstoken nur für webmasters.readonly anfordert, und allein submit_sitemap geht über eine zweite Funktion mit dem weiten Bereich. Für SEO-Audit heißt das: Wenn er inspect_url auf https://example.com/blog/agenten aufruft, hält er dabei ein Token, mit dem Google keine Sitemap annimmt.
Der Eintrag scope: read kürzt die Beschreibung
In der ACCESS.md des Agenten steht das System mit einem Scope, für SEO-Audit also system: searchconsole scope: read. Naheliegend ist die Annahme, dass dieser Eintrag das Schreiben bereits verhindert, und die Übersicht der Zielsysteme in der covey-Dokumentation legt das auch nahe.
Im Quelltext reicht der Eintrag weniger weit. Mit scope: read lässt das Plugin den Abschnitt über submit_sitemap aus der Beschreibung weg, die der Agent in jedem Schritt liest. Eine Prüfung je Aktion gegen die ACCESS.md führt covey nur für Plugins durch, die für jede Aktion einen Scope nennen. Das Search-Console-Plugin nennt keinen, sodass bei ihm allein die Beschreibung gekürzt wird. Ruft SEO-Audit submit_sitemap trotzdem auf, lehnt covey den Aufruf deshalb nicht am Scope ab, und das Plugin fordert mit demselben Schlüssel den weiten Bereich an.
Gesperrt wird die Aktion mit einer Guard Rail vom Typ „Aktion verboten“ auf das Muster searchconsole:submit_sitemap. Das Plugin meldet jede Aktion unter einem eigenen Namen dieser Form an covey, sodass die Regel genau diese eine Aktion trifft und die vier lesenden frei lässt. Die Regel lässt sich für einen einzelnen Agenten anlegen. Sie greift in der Control Plane, bevor das Plugin ein Token anfordert, und SEO-Audit bekommt den Grund der Ablehnung zurück.
Der Preis ist ein Schlüssel, der beide Bereiche anfordern kann
Der Lesebereich ist eine Eigenschaft des einzelnen Zugriffstokens. Der JSON-Schlüssel dahinter bleibt ein privater Schlüssel, mit dem sich auch der weite Bereich anfordern lässt. Ob Google eine eingereichte Sitemap dann annimmt, entscheidet die Berechtigung, die das Dienstkonto an der Property hat. Die Einrichtungsanleitung nennt dafür „Full“ oder „Restricted“ und hält fest, dass zum Lesen beides genügt.
Wer das Schreiben ausdrücklich erlauben will, trägt scope: read,write ein und legt keine Guard Rail an. Auch dann nimmt das Plugin nur Sitemaps an, deren Adresse zur Property gehört, an der die Aktion arbeitet (ohne site_url die eingetragene), bei sc-domain:example.com also zu example.com und seinen Subdomains. Eine Aktion zum Entfernen einer Sitemap gibt es im Plugin nicht, sodass jedes Schreiben dort nur etwas hinzufügt.
Für SEO-Audit liegt die Zusage damit an drei Stellen. Die Berechtigung an der Property legt fest, was Google dem Dienstkonto überhaupt erlaubt. Der Bereich je Aktion hält die lesenden Aufrufe auf webmasters.readonly. Die Guard Rail auf searchconsole:submit_sitemap sperrt die einzige schreibende Aktion für diesen Agenten.