Studio mit einem Browser-Agenten bedienen

Verbatra Studio ist normalerweise eine Oberfläche für Menschen: du öffnest das Loopback-Dashboard und klickst dich durch den Projektzustand, die Drift, die Review-Warteschlange und Bearbeitungen. Mit dem Opt-in-Flag --expose-agent-tools registriert Studio dieselben Review-Aktionen zusätzlich als WebMCP-Tools, sodass ein KI-Agent im Browser (zum Beispiel Gemini oder Claude in Chrome), der auf demselben offenen, authentifizierten Tab sitzt, sie strukturiert bedienen kann, statt am DOM zu raten.

Das ist dafür da, ein bestehendes verbatra-Projekt im Dialog zu bedienen: Zustand und Drift ansehen, die Review-Warteschlange abarbeiten, Einträge bearbeiten und (nur wenn du zusätzlich Ausgaben erlaubst) ausstehende Keys neu übersetzen und übersetzen. Es ist nicht für die Projekteinrichtung und nicht für Fernzugriff gedacht.

Was WebMCP ist

WebMCP lässt eine Seite Tools an document.modelContext registrieren, die ein im Browser ansässiger KI-Agent dann aufrufen kann. Studio nutzt das, um seine Review-Aktionen als benannte Tools anzubieten. Jeder Tool-Aufruf läuft weiterhin über genau denselben authentifizierten RPC wie das Dashboard, über denselben Loopback-Origin, mit derselben Eingabevalidierung und denselben Capability-Gates. Die Tools zu registrieren gibt einem Agenten nichts, was der offene, authentifizierte Tab nicht schon hatte: ein Agent, der das DOM steuert, konnte jede einzelne dieser Aktionen schon erreichen. Die Angriffsfläche deckt sich mit diesem einen offenen Tab und fügt keine neue Netzwerk-Exposition hinzu.

Voraussetzungen im Browser

• Ein WebMCP-fähiger Browser. Heute heißt das Chrome 149 oder neuer mit aktiviertem chrome://flags/#enable-webmcp-testing, oder ein späterer Browser mit nativer Unterstützung.
• document.modelContext muss vorhanden sein. Fehlt es, registriert Studio nichts und das Dashboard bleibt unverändert.
• Ein echter Browsing-Kontext. Headless funktioniert das nicht; der Agent bedient den offenen, laufenden Tab.
• Keine Konfigurations- oder CSP-Änderung auf Studios Seite. Die WebMCP-Permissions-Policy tools steht standardmäßig auf self, was genau Studios Same-Origin-Fall ist, also muss nichts gewährt werden.

Schalte es ein

Agent-Tools sind standardmäßig aus. Schalte sie mit dem Flag am studio-Befehl ein:

verbatra studio --expose-agent-tools

Oder setze die Variante über die Umgebung:

VERBATRA_STUDIO_AGENT_TOOLS=1 verbatra studio

Flag und Umgebungsvariable werden genau wie bei --allow-spend aufgelöst: 1, true, yes oder on (Groß- und Kleinschreibung egal) zählt als an, und das CLI-Flag gewinnt gegen die Variable. Ist keines von beiden gesetzt, wird kein Tool registriert. Alle Flags stehen unter verbatra studio.

Öffne dann die ausgegebene Loopback-URL in deinem WebMCP-fähigen Browser. Der Agent auf diesem Tab entdeckt die registrierten Tools und kann sie aufrufen.

Der Tool-Katalog

Mit aktiviertem Opt-in registriert Studio dreizehn Tools, eines pro Dashboard-Aktion. Ohne --allow-spend sind es elf: die beiden Ausgaben-Tools entfallen vollständig. Tool-Namen tragen ein Präfix und nutzen Unterstriche (zum Beispiel verbatra_project_snapshot).

Lese-Tools (zehn)

Sieh dir den Projektzustand an, ohne etwas zu ändern. Diese sind als read-only markiert.

Schreib-Tool (eines)

verbatra_translation_editEntry bearbeitet den Wert eines Locales an Ort und Stelle. Es läuft durch dasselbe Integritäts-Gate wie jeder andere verbatra-Schreibvorgang: ein Wert, der eine der Prüfungen nicht besteht, wird abgelehnt, und nichts wird geschrieben. Eine akzeptierte Bearbeitung schreibt die Locale-Datei und rückt den Lock-Eintrag des Keys vor, genau wie eine Bearbeitung im Dashboard. Bearbeiten braucht kein Ausgaben-Flag; es berührt nur deine lokalen Dateien und ruft nie einen Provider auf.

Ausgaben-Tools (zwei)

Diese rufen einen Übersetzungs-Provider auf und werden nur registriert, wenn Studio zusätzlich mit --allow-spend läuft:

• verbatra_translation_retranslateEntry: übersetzt einen Key und ein Locale neu.
• verbatra_translation_translatePending: übersetzt alles derzeit Ausstehende.

Beide schicken ihre Ergebnisse durch das Integritäts-Gate, bevor irgendetwas die Platte erreicht, und für beide gelten Studios bestehende Ratenlimits (Neuübersetzen 20 pro gleitender Minute, Translate-pending 5 pro gleitender Minute plus eine Sperre gegen parallele Läufe). Ohne --allow-spend fehlen sie im Tool-Set, und der Server registriert die zugrunde liegenden Endpunkte gar nicht erst: Ausgaben, die du beim Start nicht gewährt hast, sind für einen Agenten nicht erreichbar.

Der Degraded-Mode-Hinweis

Die Registrierung hat drei mögliche Ausgänge, und nur einer davon ist ein Problem.

Nichts versucht, nichts gemeldet. Fehlt document.modelContext (ein Browser ohne WebMCP oder Chrome ohne das Flag) oder hast du die Freigabe nicht gesetzt, versucht Studio überhaupt keine Registrierung. Das Dashboard bleibt unverändert und die Konsole bleibt still. Das ist der vorgesehene No-Op, kein Fehler.

Elf Tools und kein Hinweis. Ohne --allow-spend versucht Studio elf Registrierungen statt dreizehn: die beiden Ausgaben-Tools werden übersprungen, bevor sie überhaupt versucht werden. Elf Tools sind die gesunde Zahl für eine Sitzung ohne Ausgaben, ihr Fehlen ist also der erwartete Zustand und löst nie einen Hinweis aus.

Der Hinweis. Hat Studio eine Registrierung versucht und der Browser sie abgelehnt, zeigt das Dashboard oben im Inhaltsbereich eine Warnung, auf jeder Ansicht:

Agent tools degraded: 2 of the agent tool registrations failed with SecurityError. The dashboard itself is unaffected. The browser console lists every failing tool.

Zahl und Fehlername sind die echten aus diesem Durchlauf. Der Hinweis hat kein Bedienelement zum Schließen und bleibt für die Lebensdauer der Seite stehen. Ein Neuladen des Tabs startet einen frischen Registrierungsdurchlauf, denn der Status wird nur im Speicher gehalten.

Was im Degraded-Modus weiterhin funktioniert

Ein fehlschlagendes Tool bricht nie die nachfolgenden ab, also bleibt jedes Tool, das sich registriert hat, aufrufbar und die Oberfläche ist meist teilweise nutzbar statt ausgefallen. Das Dashboard bleibt unberührt: die menschliche Oberfläche, die RPCs und jedes Capability-Gate verhalten sich genau so, wie sie es mit ausgeschalteter Freigabe täten, und keine Locale-Datei ist betroffen.

Die Konsole lesen

Studio schreibt eine einzige zusammengefasste Zeile auf Error-Ebene, nicht eine Zeile pro Tool, denn eine gemeinsame Ursache lässt jedes Tool identisch scheitern:

Verbatra agent tools: 2 of 11 tool registrations failed. verbatra_status_diff (SecurityError: ...); verbatra_key_value (SecurityError: ...)

Der erste Satz nennt, wie viele der versuchten Registrierungen fehlgeschlagen sind, und von wie vielen Versuchen. Danach folgt jedes fehlschlagende Tool als name (ErrorName: message), getrennt durch Semikolons. Der Fehlername benennt die Ursache: es ist der name des Werts, mit dem der Browser abgelehnt hat, meist eine DOMException wie SecurityError oder InvalidStateError.

Ein Durchlauf, der die Tool-Schleife nie erreicht hat, meldet eine andere Zeile und löst den Hinweis nicht aus:

Verbatra agent tools: registration did not start (TypeError: Failed to fetch).

Das heißt, der Projekt-Snapshot-Aufruf, der über die Freigabe entscheidet, ist beim Laden fehlgeschlagen, sodass kein Tool versucht wurde.

Was du dagegen tun kannst

Keine Studio-Einstellung behebt eine abgelehnte Registrierung, denn die Ablehnung kommt vom Browser. In der Praxis:

• Lies zuerst den Fehlernamen in der Konsole. Er benennt die Ursache genauer als der Hinweis.
• Lade den Tab neu. Die Registrierung läuft einmal pro Seitenaufruf, eine vorübergehende Ablehnung verschwindet also.
• Prüfe die Voraussetzungen im Browser oben erneut. Ein fehlendes Flag oder ein Browser ohne WebMCP führt zum stillen No-Op, nie zu diesem Hinweis; wenn du den Hinweis siehst, ist die Oberfläche also angelaufen.
• Nutze weiter die Tools, die sich registriert haben, oder arbeite im Dashboard, das ohnehin unbetroffen ist.

Sicherheitsmodell

Behalte diese Punkte im Kopf, bevor du Agent-Tools einschaltest.

• Standardmäßig aus. Du schaltest sie ausdrücklich mit --expose-agent-tools (oder VERBATRA_STUDIO_AGENT_TOOLS) ein.
• Ausgaben brauchen beide Flags. Die beiden Ausgaben-Tools erscheinen nur, wenn du sowohl --expose-agent-tools als auch --allow-spend übergibst. Keines der Flags impliziert das andere. Lese- und Schreib-Tools geben nichts aus.
• Keine neue Netzwerk-Exposition. Jeder Tool-Aufruf nutzt denselben authentifizierten Loopback-RPC wie das Dashboard. Studio bindet sich weiterhin nur an 127.0.0.1, und das Browser-Sitzungstoken authentifiziert weiterhin jede Anfrage.
• Übersetzbare Strings sind nicht vertrauenswürdig. Tools, die aus dem Projekt stammenden Text zurückgeben können (Locale-Strings, Key-Namen, Glossarbegriffe, Commit-Betreffs, Platzhalter-Tokens), markieren ihren Inhalt als nicht vertrauenswürdig, damit ein konsumierender Agent diese Werte als Daten behandelt und nicht als Anweisungen.

Das akzeptierte Ausgabenrisiko

Sag es klar: sind --allow-spend und --expose-agent-tools beide an, kann ein autonomer Agent Provider-Ausgaben auslösen, ohne dass ein Mensch jeden Klick bestätigt. Studio baut keinen Freigabedialog pro Aufruf ein: der Server kann einen vom Agenten ausgelösten Aufruf nicht von einem menschlichen Klick in derselben Sitzung unterscheiden, ein solcher Dialog würde also falsche Sicherheit geben und den Sinn der Funktion zunichtemachen. Die Ratenlimits oben begrenzen die Kosten weiterhin, aber ein Agent kann von sich aus bis an diese Obergrenze laufen.

Schalte agentengesteuerte Ausgaben bewusst frei. Wenn ein Agent nur den Zustand ansehen und Einträge von Hand korrigieren soll, starte Studio ohne --allow-spend: Agent-Tools funktionieren in diesem Lese- und Bearbeitungsmodus vollständig, und kein Tool erreicht einen Provider.

Weiter

• Review in Studio: derselbe Workflow, von einem Menschen gesteuert.
• verbatra studio: jedes Flag und der Startvertrag.
• Übersetzungssicherheit: das Integritäts-Gate, durch das jede Bearbeitung und jede Neuübersetzung läuft.