google/adk-js: Agenten in TypeScript statt in Konfigurationsdateien

Ein Agent ist eine exportierte Konstante, kein YAML-Baum

Viele Agenten-Frameworks verlagern die Logik in Deklarationsdateien. Das lässt sich leicht versionieren, aber schlecht debuggen: Wenn ein Tool falsch aufgerufen wird, steht der Fehler in einer Konfiguration, nicht in einer Zeile Code, die man mit einem Breakpoint versehen könnte. adk-js geht den umgekehrten Weg. Das README beschreibt das Projekt als code-first: Verhalten, Orchestrierung und Tool-Nutzung werden direkt in TypeScript definiert, was laut README robustes Debugging, Versionierung und Deployment ermöglichen soll.

Adressiert sind damit Entwicklerinnen und Entwickler, die ohnehin in Node.js oder im Browser arbeiten und keine zweite Sprachwelt für Agenten aufmachen wollen. Das Quick-Start-Beispiel ist entsprechend knapp: Eine Datei `agent.ts` exportiert `rootAgent` als Instanz von `LlmAgent` mit den Feldern `name`, `description`, `model`, `instruction` und `tools`. Wer schon einmal eine Funktion mit Typannotation geschrieben hat, versteht dieses Modell in wenigen Minuten. Der Preis dafür ist, dass jede Änderung an der Agentenlogik ein Code-Review und ein neues Deployment ist. Für schnell wechselnde Prompts ist das schwerfälliger als eine Konfigurationsdatei, die man im Betrieb austauscht.

Modellaufruf, Werkzeugauswahl und Weiterleitung

Der sichtbare Mechanismus ist eine Schleife: Das Modell bekommt Instruktion und Nutzereingabe, entscheidet über einen Werkzeugaufruf, das Ergebnis geht zurück ins Modell, und am Ende steht eine Antwort. Das README zeigt das nicht als Diagramm, aber die Bausteine benennen genau diese Stationen. `LlmAgent` ist der Knoten, der das Modell aufruft. `tools` ist die Liste der Werkzeuge, die er erreichen darf, im Beispiel `GOOGLE_SEARCH`.

Für mehrere Agenten nennt das README vier Kompositionsformen: sequenziell, parallel, Schleife und geroutet. Dazu kommt die Delegation an entfernte Agenten über das A2A-Protokoll. Das ist der architektonisch interessanteste Teil, weil er die Grenze zwischen Prozessen zieht: Ein Router-Agent muss die Fachlogik des Zielagenten nicht kennen, nur dessen Schnittstelle. Wie ein solcher Verbund konkret verdrahtet wird, steht nicht im README, sondern nur hinter dem Verweis auf die Dokumentation unter adk.dev. Wer diesen Weg plant, muss dort nachlesen.

Die Tool-Seite ist zweigeteilt. Eingebaut sind Google Search, Google Maps, Vertex AI Search und URL-Kontext, also Dienste aus dem Google-Umfeld. Offen ist die Anbindung über MCP-Server und das Verpacken beliebiger Funktionen als Tool. Für Parametertypen unterstützt das Projekt Zod in den Versionen 3 und 4 mit Typinferenz zur Kompilierzeit. Das ist mehr als Kosmetik: Ein falsch benanntes Argument fällt beim Bauen auf, nicht erst im Gespräch mit dem Modell.

Installation, API-Key und der Stolperstein mit npx adk

Voraussetzung ist Node.js 20.19 oder neuer. Installiert wird in zwei Paketen, getrennt nach Laufzeit und Werkzeug:

npm install @google/adk npm install -D @google/adk-devtools

Die Authentifizierung läuft über eine `.env`-Datei neben dem Agenten. Für den API-Key-Zugang schreibt das README den Schlüssel `GOOGLE_GENAI_API_KEY`. Für Vertex AI stattdessen `GOOGLE_GENAI_USE_VERTEXAI=1` zusammen mit `GOOGLE_CLOUD_PROJECT` und `GOOGLE_CLOUD_LOCATION`, dazu `gcloud auth application-default login`.

Zwei Befehle decken die lokale Arbeit ab: `npx @google/adk-devtools run agent.ts` startet die interaktive Kommandozeile, `npx @google/adk-devtools web` die Entwickleroberfläche zum Testen und Debuggen. Für das Deployment nennt das README `adk deploy cloud_run`, ohne Parameter oder Beispiele. Wer diesen Befehl nutzen will, ist auf die Dokumentation angewiesen.

Der wichtigste Hinweis im README betrifft die Schreibweise: Immer den vollen Paketnamen angeben. Ist `@google/adk-devtools` nicht installiert, lädt ein bloßes `npx adk` stillschweigend ein fremdes Paket gleichen Namens aus der öffentlichen Registry und führt es aus. Das ist keine theoretische Warnung, sondern ein konkreter Fall, in dem ein Tippfehler oder eine vergessene Dev-Abhängigkeit fremden Code auf dem Rechner startet.

Zod, Bundles und was die Typsicherheit nicht abdeckt

Das Paket liefert ESM, CommonJS und Web-Bundles, sodass derselbe Agentencode in Node.js oder im Browser laufen kann. In der Praxis ist das eine Einschränkung wert: Läuft der Agent im Browser, liegt der Modellaufruf beim Client, und der API-Key müsste dorthin gelangen. Das README behandelt diesen Punkt nicht. Wer die Browser-Variante ernsthaft erwägt, braucht eine eigene Antwort auf die Frage, wo der Schlüssel bleibt und wer die Kosten trägt.

Zod-Schemas und Typinferenz prüfen die Form der Tool-Parameter. Sie prüfen nicht, ob das Modell das richtige Werkzeug wählt, ob die Instruktion zum Ziel führt oder ob eine Antwort stimmt. Genau dafür gibt es die Entwickleroberfläche und das im Beschreibungstext genannte Evaluieren. Wie eine Evaluierung aussieht, welche Dateien sie erwartet und wie Ergebnisse gemeldet werden, geht aus dem vorliegenden Material nicht hervor. Das ist die größte Lücke zwischen Anspruch und belegter Funktionalität.

Wenn ein anderes Modell im Mittelpunkt stehen soll

Ein naheliegender Vergleich ist LangChain in der JavaScript-Variante. Der Unterschied liegt nicht im Umfang, sondern im Ausgangspunkt. LangChain ist als Sammlung von Abstraktionen über viele Modellanbieter gebaut. Ein Modellwechsel ist dort ein ausgetauschtes Objekt, und der Rest der Kette bleibt gleich. adk-js ist umgekehrt aufgestellt: Modell- und Werkzeugbeispiele zielen auf Gemini und die Google-Dienste, und die eingebauten Werkzeuge heißen Google Search, Google Maps und Vertex AI Search. Ob sich ein anderer Anbieter überhaupt anbinden lässt, sagt das README nicht.

Daraus folgt die Abgrenzung. Steht ein bestimmtes Nicht-Google-Modell im Zentrum des Projekts, ist adk-js das falsche Werkzeug, und der Wechsel zu einem anbieterübergreifenden Rahmen ist billiger als ein Umbau. Steht Gemini oder Vertex AI fest, spart adk-js die Abstraktionsschicht, die man sonst mitpflegen müsste. Dass die Agentenstruktur aus gewöhnlichen TypeScript-Objekten besteht, macht diesen Wechsel später zumindest nachvollziehbar: Ein Agent ist eine Konstante, kein verstecktes Laufzeitsystem.

Apache-2.0, drei Versionierungsschienen und die Pflegekosten

Lizenziert ist das Projekt unter Apache-2.0. Diese Lizenz erlaubt kommerzielle Nutzung, Veränderung und Weitergabe, verlangt aber, dass Lizenz- und Urheberrechtshinweise erhalten bleiben und Änderungen gekennzeichnet werden. Wer das Paket unverändert per npm einbindet, hat damit wenig Berührungspunkte. Wer Quellcode kopiert und anpasst, sollte die Hinweise mitführen. Das ist eine Einordnung, keine Rechtsberatung.

Die Versionsverwaltung ist der praktisch wichtigere Punkt. Die letzten Veröffentlichungen tragen die Namen `main-v2.0.0`, `integrations-v2.0.0` und `devtools-v2.0.0`, alle vom selben Tag. Daraus folgt: Es gibt mindestens drei Schienen, die getrennt versioniert werden. Eine Aktualisierung von `@google/adk-devtools` kann also unabhängig von `@google/adk` erfolgen, und die Versionsnummern müssen nicht übereinstimmen. Wer beide Pakete im Projekt hält, sollte sie nicht als Einheit behandeln.

Das Repository ist nicht archiviert, der letzte Push datiert auf den 10. September 2026. Eine Aussage über Release-Kadenz oder Support-Zeiträume lässt sich daraus nicht ableiten. Für ein Projekt, das Produktionscode trägt, bleibt das ein offener Punkt: Wer adk-js einführt, bindet sich an ein Toolkit mit drei Versionsschienen, dessen Update-Politik aus dem vorliegenden Material nicht hervorgeht. Ein Blick in die Release Notes vor der ersten Festlegung ist deshalb keine Formalie.

Redaktionelles Fazit

Sinnvoll ist adk-js für Teams, die Gemini oder Vertex AI einsetzen, ohnehin in TypeScript arbeiten und Agentenlogik versionieren wollen statt sie in JSON zu konfigurieren. Ungeeignet ist es, wenn ein anderes Modell als Gemini im Kern stehen soll: Die Beispiele und die eingebauten Tools sind auf Google-Dienste zugeschnitten, ein Modellwechsel ist nicht dokumentiert. Wer den Code lesen will, bevor er ihn ausführt, sollte sich zuerst `agent.ts` und `rootAgent` in den Samples ansehen und prüfen, ob `npm install @google/adk` die erwartete Version liefert.

Offizielle Quellen

1. google/adk-js on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases