Wie Sie Google AX nutzen: Installation und Entwicklung der Open-Source-Agent-Runtime

Die offizielle Konzeptbeschreibung stellt Task und Workspace als zentrale Begriffe von Google AX heraus (Konzepte im offiziellen Repository). Das ist der entscheidende Hinweis für Ihre Planung:

Symptom: Sie erwarten ein fertiges Agent-Produkt oder eine neue Modell-API.
Schnellster Weg: Behandeln Sie Google AX als Laufzeit zur Organisation von Tasks, Workspaces und Ausführung. Starten Sie mit dem offiziellen Quickstart für eine einzelne Task und prüfen Sie anschließend Sandbox, Netzwerkgrenzen und Beobachtbarkeit, bevor Sie den Betrieb ausweiten.

Dieser Leitfaden richtet sich an Go-Entwickler, die einen eigenen Agent-Task-Runner integrieren möchten.
Er hilft SRE- und Plattformteams, Grenzen von Workspace, Netzwerk und Task-Ausführung zu prüfen.
Technische Verantwortliche können damit einschätzen, ob ein lokaler Rechner oder eine dauerhaft verfügbare Remote-Entwicklungsumgebung besser zum Pilotbetrieb passt.

Zuletzt aktualisiert am 25.09.2026; geprüft anhand des offiziellen AX-Repositories, der dort verlinkten Quickstart-Anleitung und der Dokumentation zu Runner, Sandbox und Netzwerk.

Was Google AX im Betrieb übernimmt

Google AX sollten Sie weder mit dem Agent-Programm noch mit dem zugrunde liegenden Modell gleichsetzen. Die Laufzeit organisiert die Ausführung von Tasks und die zugehörigen Workspaces. Ihr Agent bleibt das Programm, das die gewünschte Arbeit erledigt; das Modell ist eine separate Komponente, die dieses Programm gegebenenfalls verwendet. Die offizielle Konzeptdokumentation ist der geeignete Bezugspunkt, um diese Zuständigkeiten auseinanderzuhalten.

Für Ihre Architekturentscheidung heißt das: AX kann den Rahmen für Task-Ausführung und Workspace-Vorbereitung liefern, aber nicht automatisch die fachliche Logik Ihres Agents, Ihre Modellwahl oder Ihre Sicherheitsrichtlinien ersetzen. Legen Sie deshalb vor dem ersten Test fest, welches Ergebnis der Agent erzeugen soll und welche Eingaben er dafür tatsächlich benötigt.

Auch die Begriffe „isoliert“ und „ausführbar“ sollten Sie nicht vorschnell als Sicherheitsgarantie lesen. Die Existenz einer Runtime oder eines Workspaces beweist für sich genommen nicht, dass ein Prozess nur auf freigegebene Dateien zugreifen oder ausschließlich erlaubte Netzwerkziele erreichen kann. Dafür sind die dokumentierten Sandbox- und Netzwerkeinstellungen sowie die Konfiguration Ihrer konkreten Umgebung maßgeblich.

Vorteile und Grenzen für Ihre Entscheidung

Vorteile

• Sie können die Arbeit entlang von Task, Workspace und Runner strukturieren, statt diese Zuständigkeiten vollständig in eine eigene Ausführungsschicht einzubauen.
• Die offiziellen Dokumente bieten getrennte Bezugspunkte für Konzepte, Runner, Manifeste, Sandbox und Netzwerk.
• Der Einstieg lässt sich zunächst auf eine einzelne Task und einen überschaubaren Workspace begrenzen.

Grenzen

• AX ersetzt weder den Agent-Code noch die Modellintegration oder die fachliche Fehlerbehandlung.
• Die Dokumentation eines Mechanismus belegt nicht automatisch, dass Ihre konkrete Bereitstellung korrekt isoliert ist.
• Parallelbetrieb, Aufbewahrung, Bereinigung und Wiederaufnahme fehlgeschlagener Tasks müssen Sie in Ihrem Betriebsablauf ausdrücklich prüfen.

Vor dem ersten Start: Entwicklungsumgebung und Repository

Beginnen Sie mit dem offiziellen Repository und Quickstart. Prüfen Sie dort die aktuellen Installationsschritte, die verlangten Werkzeuge und die angegebenen Abhängigkeiten, bevor Sie Befehle aus älteren Beispielen übernehmen. Diese Anleitung nennt bewusst keine Go-Mindestversion und keine Ressourcenwerte: Solche Angaben sollten Sie nur verwenden, wenn sie in der aktuellen offiziellen Dokumentation stehen.

Gehen Sie beim Vorbereiten in dieser Reihenfolge vor:

1. Lesen Sie den aktuellen Einstieg im Repository. Notieren Sie die dort genannten Voraussetzungen und Installationsbefehle. Stimmen Sie Ihre lokale Umgebung mit genau diesen Angaben ab, statt eine Version aus einem Drittbeitrag zu übernehmen.
2. Klonen Sie das Repository nach der offiziellen Anleitung. Arbeiten Sie zunächst in einer separaten Entwicklungsumgebung und vermeiden Sie es, die ersten Tests mit produktiven Zugangsdaten auszuführen.
3. Prüfen Sie die Beispielartefakte. Öffnen Sie insbesondere die offizielle Task-Beispieldatei und vergleichen Sie die Felder mit der Beschreibung der Manifest-Felder.
4. Klären Sie die benötigten Laufzeitabhängigkeiten. Installieren Sie nur, was die aktuellen AX-Anweisungen für den gewählten Einstieg verlangen. Wenn ein Beispiel zusätzliche Werkzeuge oder Zugangsdaten benötigt, dokumentieren Sie diese Abhängigkeit separat.
5. Trennen Sie Testdaten von persönlichen und produktiven Daten. Ein Beispieltask braucht keine pauschale Freigabe für Ihr gesamtes Home-Verzeichnis. Stellen Sie nur die Eingaben bereit, die Sie für den konkreten Test benötigen.

Das verhindert einen typischen Fehlstart: Ein Beispiel wirkt zunächst „nicht lauffähig“, obwohl nicht der Runner selbst, sondern eine fehlende Abhängigkeit oder eine anders aufgebaute Manifest-Datei die Ursache ist. Für einen belastbaren Test erfassen Sie deshalb neben dem Ergebnis auch die verwendete Dokumentationsrevision, die lokalen Voraussetzungen und die tatsächlich ausgeführten Schritte. So können Sie einen späteren Fehler von einer Änderung in der Anleitung oder im eigenen Setup unterscheiden.

Erster Task und Workspace-Lebenszyklus

Der Google AX Quickstart sollte Ihnen zeigen, wie eine Task vorbereitet und ausgeführt wird. Halten Sie dabei vier Phasen auseinander: Eingabe definieren, Workspace bereitstellen, Ausführung starten und Ergebnis beziehungsweise Status beobachten. Die offizielle Beispieldatei für Tasks und die Manifest-Dokumentation sind die Referenzen für die konkreten Felder. Verwenden Sie deren aktuelle Feldnamen, statt ein eigenes YAML-Schema zu erfinden.

Wie führen Sie den ersten Agent-Task aus?

Rufen Sie die Befehle in der Reihenfolge auf, die der aktuelle Quickstart vorgibt. Ergänzen Sie nicht ungeprüft Befehle aus älteren Beiträgen: Eine vermeintlich plausible go run-Zeile oder ein frei erfundener AX-Unterbefehl kann ein anderes Verhalten haben als der dokumentierte Einstieg.

Für den ersten Durchlauf empfiehlt sich ein einfacher Test, dessen Ergebnis sich unabhängig beurteilen lässt. Geben Sie der Task eine kleine, unkritische Eingabe und prüfen Sie anschließend:

• Wurde die Task mit den erwarteten Eingaben angenommen?
• Wurde der vorgesehene Workspace vorbereitet?
• Welcher Befehl oder Agent-Prozess wurde tatsächlich ausgeführt?
• Wo erscheinen Status, Fehler und erzeugte Dateien?
• Können Sie erkennen, ob das Ergebnis aus der Task oder aus einer vorangegangenen lokalen Datei stammt?

Notieren Sie die beobachteten Ausgaben, ohne sie als allgemeingültiges AX-Ausgabeformat auszugeben. Die tatsächlich sichtbaren Felder hängen vom durchlaufenen Beispiel und der aktuellen Implementierung ab. Für eine reproduzierbare Fehlersuche vergleichen Sie den Ablauf mit dem offiziellen Quickstart und notieren Sie, an welcher Lifecycle-Phase die Ausführung abweicht.

Wie bereitet AX den Task-Workspace vor?

Behandeln Sie einen Workspace als Teil des Task-Vertrags: Er bestimmt, welche Arbeitsdateien der Prozess vorfindet und wo Ergebnisse entstehen. Er ist aber nicht automatisch eine vollständige Sicherheitsgrenze. Prüfen Sie in der konkreten Ausführung, ob der Workspace neu angelegt, wiederverwendet oder nach Abschluss entfernt wird. Leiten Sie diese Eigenschaften nicht allein aus seinem Namen ab.

Ein einfacher Lifecycle-Test besteht darin, die Eingabedateien vor dem Lauf zu erfassen, die erzeugten Dateien nach dem Lauf zu prüfen und anschließend den Bereinigungsweg nachzuvollziehen. Wiederholen Sie den Test mit einem absichtlich fehlerhaften Task. So sehen Sie, ob auch bei einem Abbruch verwertbare Logs und ein nachvollziehbarer Workspace-Zustand verbleiben. Das ist ein nicht offensichtlicher Betriebsunterschied: Ein erfolgreicher Durchlauf zeigt nicht, ob Ihre Fehlerbehandlung Daten zurücklässt oder eine Wiederaufnahme ermöglicht.

Ein Workspace ist erst dann eine belastbare Grenze, wenn Sie sowohl die Dateisicht des Prozesses als auch die Regeln für Wiederverwendung und Bereinigung überprüft haben. Die bloße Existenz eines Workspace-Objekts reicht dafür nicht.

Eigener Agent am Runner

Der Runner ist der Integrationspunkt, an dem die Task-Ausführung mit Ihrem Agent-Programm zusammenkommt. Die offizielle Runner-Dokumentation beschreibt die dafür vorgesehene Schnittstelle. Verfolgen Sie beim Lesen insbesondere, wie Task und Workspace an die Ausführung übergeben werden, wie der Prozess gestartet wird und welche Beobachtungsmöglichkeiten der Runner bereitstellt.

Beginnen Sie nicht damit, einen vollständigen Produktionsrunner nachzubauen. Erstellen Sie zunächst einen kleinen Adapter um Ihren Agent-Aufruf:

• Der Adapter nimmt die dokumentierte Task entgegen.
• Er prüft, welche Eingaben und Workspace-Informationen vorhanden sind.
• Er startet ausschließlich den für den Test vorgesehenen Prozess.
• Er leitet Status und Fehler an die im Runner vorgesehenen Beobachtungspunkte weiter.
• Er macht den Abschlusszustand für den aufrufenden Ablauf nachvollziehbar.

Die genaue Typisierung, Konstruktoren und Methoden richten Sie nach der aktuellen API im Repository aus. Diese Anleitung ergänzt keine vermeintlichen Go-Typnamen, weil eine erfundene Signatur mehr schadet als ein Verweis auf die tatsächlich gepflegte Runner-Schnittstelle. Legen Sie den Erweiterungspunkt dort an, wo die offizielle Runner-Dokumentation die Ausführung Ihres Programms vorsieht, und testen Sie ihn zunächst mit einer deterministischen Agent-Aktion.

Für die Integration sollte ein Fehler nicht nur als allgemeiner Prozessabbruch erscheinen. Unterscheiden Sie mindestens zwischen ungültiger Task-Eingabe, fehlender Abhängigkeit, Startfehler, Agent-Fehler und Fehler beim Schreiben des Ergebnisses. Prüfen Sie, welche dieser Zustände der Runner selbst sichtbar macht und welche Ihr Adapter protokollieren muss. Diese Trennung erleichtert später die Entscheidung, ob eine Task wiederholt, verworfen oder manuell untersucht werden sollte.

Sandbox, Netzwerk und Beobachtbarkeit vor dem Pilotbetrieb

Die Sicherheitsprüfung ist keine optionale Ergänzung nach erfolgreichem Quickstart. Lesen Sie die AX-Dokumente zu Sandbox-Konfiguration und Netzwerkverhalten und markieren Sie, welche Aussagen dokumentierte AX-Funktionen beschreiben und welche Maßnahmen Sie in Betriebssystem, Container- oder Infrastrukturkonfiguration selbst umsetzen müssen.

Prüfen Sie die folgenden Grenzen einzeln:

• Prozesszugriff: Welche Benutzeridentität führt den Task aus? Welche weiteren Prozesse kann sie starten oder erreichen?
• Dateizugriff: Sieht der Agent nur den zugewiesenen Workspace oder auch andere Verzeichnisse? Können erstellte Dateien nach dem Task außerhalb des vorgesehenen Bereichs verbleiben?
• Netzwerk: Welche ausgehenden Verbindungen sind tatsächlich möglich? Die Beschreibung einer Netzwerkoption ist kein Beleg dafür, dass eine umfassende Sperrliste bereits aktiv ist.
• Zugangsdaten: Werden Geheimnisse in Umgebungsvariablen, Dateien oder anderen Task-Eingaben übergeben? Entfernen Sie nicht benötigte Berechtigungen aus dem Testlauf.
• Beobachtbarkeit: Können Sie Start, Laufzeitfehler, Beendigung und erzeugte Ergebnisse einem konkreten Task zuordnen?
• Fehler und Bereinigung: Bleiben Workspaces nach Abbrüchen zurück, und ist für das Team erkennbar, wer sie sicher entfernen darf?

Prüfen Sie SSH- oder Debug-Zugänge nur, wenn Ihre konkrete Einrichtung sie vorsieht. Aktivieren Sie solche Zugänge nicht pauschal, nur um einen fehlerhaften Lauf bequemer untersuchen zu können. Legen Sie stattdessen fest, wer Zugriff erhält, wie lange er gebraucht wird und wie Sie den Zugang nach der Diagnose wieder schließen. Die offizielle AX-Dokumentation beschreibt die Projektfunktionen; die Entscheidung über Konten, Netzgrenzen, Protokollaufbewahrung und Datenschutz bleibt Teil Ihrer Bereitstellung.

Für Teams, die personenbezogene oder vertrauliche Eingaben verarbeiten, gehört auch die Frage dazu, welche Daten im Workspace und in Logs landen. Verknüpfen Sie die technische Prüfung mit Ihren internen DSGVO-Vorgaben. Die Datenschutzhinweise von Kvmjet können als Orientierung für Fragen zu einer Remote-Umgebung dienen, ersetzen aber keine Prüfung Ihrer eigenen Datenflüsse und Aufbewahrungsregeln.

Vom Einzeltest zum kontrollierten Pilot

Erweitern Sie den Betrieb nicht, solange ein einzelner Task noch nicht zuverlässig nachvollziehbar ist. Ein sinnvoller Übergang besteht aus drei Prüfphasen: erst ein erfolgreicher Einzellauf, dann ein absichtlich fehlerhafter Lauf und schließlich ein begrenzter Test mit mehreren Tasks. Dabei geht es zunächst nicht um Durchsatz, sondern darum, ob Zuordnung, Bereinigung und Fehlerdiagnose auch unter leicht veränderten Bedingungen verständlich bleiben.

Nutzen Sie diese abhakbare Freigabeprüfung, bevor Sie den Pilot ausweiten:

• [ ] Die verwendeten Go- und Repository-Voraussetzungen entsprechen der aktuellen offiziellen Anleitung.
• [ ] Die Task-Felder stammen aus dem offiziellen Beispiel oder der Manifest-Dokumentation.
• [ ] Für jeden Lauf ist erkennbar, welcher Workspace verwendet wurde und wo die Ergebnisse liegen.
• [ ] Der Agent kann nicht auf Dateien zugreifen, die für die Aufgabe nicht freigegeben wurden.
• [ ] Ausgehende Netzwerkverbindungen entsprechen der ausdrücklich festgelegten Richtlinie.
• [ ] Ein absichtlich fehlerhafter Task hinterlässt einen auswertbaren Status und eine nachvollziehbare Bereinigungsmöglichkeit.
• [ ] Logs lassen sich einer Task zuordnen, ohne unnötige Geheimnisse oder persönliche Daten offenzulegen.
• [ ] Ein Wiederholungslauf erzeugt keine unbemerkte Vermischung mit dem vorherigen Workspace.

Wenn Sie diese Punkte nicht abhaken können, bleiben Sie beim Einzeltest und schließen Sie die fehlende Grenze zuerst. Erst danach ist ein begrenzter Parallelversuch sinnvoll. Definieren Sie dafür vorab, wie Sie Tasks stoppen, verwaiste Workspaces finden und Logs nach dem vereinbarten Zeitraum entfernen. Die konkreten Aufbewahrungsfristen und Kapazitätsgrenzen müssen aus Ihrer eigenen Richtlinie oder aus verifizierten Umgebungsdaten kommen; die AX-Beispiele allein liefern dafür keine allgemeingültigen Werte.

Lokale Entwicklung oder Remote-Umgebung?

Für die Wahl der Umgebung zählt nicht, ob AX grundsätzlich „lokal“ oder „in der Cloud“ läuft, sondern ob Ihr Team die Laufzeitbedingungen zuverlässig kontrolliert. Lokal starten Sie meist ohne zusätzliche Infrastruktur, müssen aber die Entwicklungsumgebung und ihre Verfügbarkeit selbst verwalten. Eine Remote-Umgebung kann einen dauerhaft erreichbaren Testplatz bieten, bringt jedoch zusätzliche Anforderungen an Zugang, Datenschutz, Netzwerkfreigaben und Kostenkontrolle mit sich.

Ein Mac ist nicht allein deshalb die richtige Wahl, weil AX eine Agent-Runtime ist. Wenn Ihr Agent, Ihre Tests oder Ihre übrigen Entwicklungswerkzeuge macOS voraussetzen, kann eine entfernte Mac-Umgebung die Tests konsistenter und zugänglich machen. Benötigen Sie keine macOS-spezifischen Werkzeuge und führen Sie nur einen kurzen Go-Test aus, kann ein lokaler Rechner oder eine andere bereits verwaltete Umgebung einfacher sein.

Wenn Sie eine Remote-Umgebung erwägen, klären Sie zuerst, ob der Zugriff zu Ihren Sicherheits- und Datenschutzanforderungen passt. Die Hinweise im Kvmjet-Hilfezentrum unterstützen bei der Prüfung einer passenden Entwicklungsumgebung. Für einen konkreten macOS-Testplatz können Sie außerdem die Angaben zum M4-Knoten in Singapur prüfen; beurteilen Sie Verfügbarkeit und Eignung anhand der dort aktuellen Informationen, nicht anhand einer angenommenen Konfiguration.

Der entscheidende Unterschied zu einem ungeprüften lokalen Setup: Ein Remote-Testplatz kann den Zugriff auf eine definierte Entwicklungsumgebung erleichtern, löst aber weder Sandbox- noch Netzwerkfragen automatisch. Ein einzelner lokaler Rechner ist für den ersten unkritischen Task oft der schnellste Weg; sobald Teamzugriff, längere Tests oder macOS-spezifische Werkzeuge relevant werden, sollten Sie eine verwaltete Remote-Umgebung gegen Ihre Anforderungen abwägen. Wenn genau diese Voraussetzungen vorliegen, kann das Mieten eines Mac über Kvmjet den Pilotbetrieb praktikabler machen. Für kurze, rein Go-basierte Tests ohne besondere Verfügbarkeitsanforderung wäre die Miete dagegen ein zusätzlicher Betriebsaufwand statt eines notwendigen Bestandteils von Google AX.