ADK-Agent mit der Agents CLI in Agent Runtime bereitstellen

1. Übersicht

Dieses Lab ist Teil des 5-Day AI Agents: Intensive Vibe Coding Course with Google von Kaggle. Weitere Codelabs und Ressourcen finden Sie auf der Veranstaltungswebsite.

In diesem Codelab wird gezeigt, wie Sie einen ADK 2.0-Agenten von einer lokalen Entwicklungsumgebung in eine produktionsreife Bereitstellung überführen. Sie verwenden agents-cli, um Ihren graphbasierten Workflow zu packen, zu überprüfen und live in der Agent-Laufzeit in Google Cloud zu hosten.

Um diesen Bereitstellungsprozess zu untersuchen, erstellen Sie einen lokalen Prototyp des Ambient Expense Agent (Ambient Expense-Agent) von Grund auf, bevor Sie ihn in der Cloud bereitstellen. Weitere Informationen zum Entwerfen der Kernlogik dieses Agents finden Sie in den grundlegenden Codelabs auf der Kaggle-Event-Website. Der Ambient Expense Agent optimiert die Spesenabrechnung von Mitarbeitern, indem er Standardabrechnungen sofort genehmigt und größere Ausgaben zur Überprüfung durch einen Menschen kennzeichnet. Intern wird ein ADK 2.0-Workflow auf Grundlage von Diagrammen verwendet, um diese automatisierten Genehmigungs- und Risikoanalyseschritte zu koordinieren.

Lerninhalte

• So bereiten Sie Ihr lokales Ambient Expense Agent-Projekt für das Cloud-Hosting vor.
• So erstellen Sie die erforderlichen Bereitstellungsdeskriptoren und Produktions-Wrapper.
• Wie Sie Probeläufe durchführen und Ihren Code direkt in der Laufzeit für KI-Agenten bereitstellen.
• So überwachen Sie die Ausführungstraces Ihres Produktions-Agents mit Cloud Trace.

Voraussetzungen

• Ein aktives Google Cloud-Projekt mit aktivierter Abrechnung.
• Das gcloud SDK ist installiert und authentifiziert.
• Der Paketmanager uv ist installiert.
• Die Google Antigravity IDE ist installiert.

Vorbereitung

In diesem Codelab wird davon ausgegangen, dass Sie mit Folgendem vertraut sind:

• Navigation im System über ein Terminal
• Grundlegende Python-Entwicklungskonzepte.
• Grundlegende Google Cloud-Konzepte.

2. Google Cloud-Umgebung einrichten

Vor der Bereitstellung müssen Sie Ihr Google Cloud-Projekt konfigurieren und die erforderlichen APIs aktivieren.

👉 Prompt Antigravity:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Wenn Antigravity diesen Prompt ausführt, werden die erforderlichen gcloud-Terminalbefehle vorgeschlagen und ausgeführt, um Ihr Projekt zu konfigurieren und die Dienste zu aktivieren. Während der Authentifizierung wird in Antigravity eine Autorisierungs-URL im Terminal angezeigt. Klicken Sie auf den Link, um sich über Ihren Webbrowser anzumelden und den Zugriff zu gewähren. Nachdem Sie sich im Browser angemeldet haben, wird die Ausführung von Antigravity fortgesetzt, um die Umgebungsvariablen Ihres Projekts festzulegen und die erforderlichen APIs zu aktivieren.

Hinweis: Wenn es sich um ein neues Projekt handelt, werden Sie möglicherweise von gcloud aufgefordert, zuerst die Service Usage API zu aktivieren. Folgen Sie dem Link im Terminal, um die API in der Cloud Console zu aktivieren, falls Sie dazu aufgefordert werden.

3. Agents CLI und ADK-Skills einrichten

Damit Antigravity ADK-Agenten gut erstellen und bereitstellen kann, ist das ADK-Skillset erforderlich. Dies sind gebündelte Referenzen für die ADK API, das Projekt-Scaffolding, den agents-cli-Bereitstellungs-Workflow und die Bewertung. Durch die Installation der agents-cli-Toolchain werden diese Skills auch in Ihrem Coding-Agent installiert. So kann der gesamte Lebenszyklus Ihres Agents verwaltet werden – von der lokalen Einrichtung bis zur Bereitstellung in der Cloud.

👉 Kopieren Sie den folgenden Prompt und fügen Sie ihn in Antigravity ein:

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Wenn Antigravity diesen Prompt ausführt, wird uvx google-agents-cli setup im Terminal ausgeführt, um die CLI und die zugehörigen Skills zu installieren. Anschließend wird agents-cli info ausgeführt, um die Installation zu überprüfen, und die neu installierten Domain-Skills (z. B. google-agents-cli-deploy und google-agents-cli-workflow) werden direkt im Chat aufgeführt.

Hinweis für Antigravity-Nutzer:Während dieses Codelabs kann Antigravity Implementierungspläne erstellen oder Pop-ups anzeigen, bevor Befehle ausgeführt oder Code geschrieben wird. Prüfen Sie diese Pläne oder Pop-ups und genehmigen Sie sie, damit Antigravity mit den Aufgaben fortfahren kann.

Tipp zum Kontingent:Wenn Ihr Kontingent während des Tests oder der Entwicklung aufgebraucht ist, wechseln Sie in Antigravity zu einem anderen verfügbaren Modell.

4. Projekt für KI-Agenten erstellen

Nachdem Sie Ihre Cloud-Umgebung konfiguriert und die erforderlichen CLI-Kenntnisse erworben haben, können Sie die lokale Codebasis für Ihren Agenten generieren. In diesem Schritt verwenden Sie Antigravity, um einen voll funktionsfähigen Ambient Expense Agent-Prototyp zu erstellen, der mit ADK 2.0 kompatibel ist.

Hinweis für Nutzer von „5 Days of AI Agents“ auf Kaggle: Wenn Sie dieses Vibecode Ambient Expense Agent Codelab für Tag 4 erfolgreich abgeschlossen haben und lieber Ihren vorhandenen benutzerdefinierten Agent-Code bereitstellen möchten, können Sie diesen Schritt überspringen und mit dem nächsten Schritt fortfahren.

👉 Prompt Antigravity:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Wenn Antigravity diesen Prompt ausführt, werden die neu installierten Scaffolding-Skills verwendet, um agents-cli scaffold create expense-agent --adk im Terminal auszuführen. Anschließend wird der generierte Prototypcode geprüft und angepasst, um sicherzustellen, dass Ihr expense-agent den $100-Schwellenwert für die automatische Genehmigung und den manuellen Überprüfungsablauf im Agent Development Kit (ADK)-Diagramm-Workflow korrekt implementiert.

5. Bereitstellung in der Produktion vorbereiten

Agent Runtime ist ein vollständig verwalteter Google Cloud-Dienst, mit dem Sie KI-Agenten in der Produktion bereitstellen, verwalten und skalieren können. Die Agent Runtime übernimmt die betrieblichen Komplexitäten des Hostings und bietet eine zustandsbehaftete Umgebung mit Funktionen wie Sitzungsverwaltung, Langzeitgedächtnis und sicheren Sandboxen für die Codeausführung.

Warum in Agent Runtime bereitstellen?

Wenn Sie KI-Agents lokal mit Antigravity erstellen, wird Ihr KI-Agent auf Ihrem lokalen Computer für localhost ausgeführt. Lokale Agents eignen sich zwar hervorragend für schnelles Prototyping, werden aber beendet, sobald Sie Ihren Laptop schließen.

Wenn Sie Ihren Agent in der Agent Runtime bereitstellen, wird Ihr Workflow in eine vollständig verwaltete, immer aktive Google Cloud-Umgebung verschoben. So wird ein sicherer, aktiver Backend-Endpunkt eingerichtet, der rund um die Uhr aktiv bleibt. Im nächsten Codelab erstellen Sie ein Web-Frontend, das direkt mit diesem Cloud-Endpunkt verbunden ist und Ihrem Agenten eine öffentliche URL gibt.

Außerdem bietet die Agent Runtime eine dedizierte Infrastruktur, die speziell für KI-Agents optimiert ist, mit integrierten Funktionen wie:

• Verwaltete zustandsorientierte Ausführung:Integrierte Sitzungsverwaltung und langfristige Speicherung des Speichers über mehrere Gesprächsrunden hinweg.
• Sichere Sandbox: Dynamische Tool-Aufrufe und von Agenten generierter Code werden sicher in isolierten Umgebungen ausgeführt.
• Enterprise Observability:Telemetrie-Streaming direkt an Cloud Trace und Cloud Logging ist sofort verfügbar.

Wenn Sie Ihren KI-Agenten in Agent Runtime hosten möchten, müssen Sie Ihr lokales Projektverzeichnis mit Produktionsdeskriptoren, Schemas und Endpunkt-Wrappern erweitern.

👉 Prompt Antigravity:

Scaffold the production deployment files for Agent Runtime.

Wenn Antigravity diesen Prompt ausführt, wird agents-cli scaffold enhance --deployment-target agent_runtime --yes im Stammverzeichnis Ihres Projekts ausgeführt. Mit diesem Befehl wird Ihr Verzeichnis gescannt und automatisch Folgendes generiert:

• app/agent_runtime_app.py: Der Service-Wrapper für die Produktion.
• deployment_metadata.json: Das Layoutschema, das von Agent Runtime zum Hochfahren von Ressourcen verwendet wird.

Ihre zentrale Agentenlogik in app/agent.py bleibt vollständig unberührt und erhalten.

6. Paketierung und lokale Bestätigung

Bevor Sie einen Cloud-Upload starten, sperren Sie Ihre Pakete und führen Sie einen lokalen Probelauf durch, um potenzielle Abhängigkeitskonflikte zu erkennen.

👉 Prompt Antigravity:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Wenn Antigravity diesen Prompt ausführt, wird zuerst uv lock im Terminal ausgeführt, um eine deterministische Sperrdatei zu generieren. So wird sichergestellt, dass in der Cloud einheitliche Bibliotheksversionen verwendet werden. Anschließend wird agents-cli deploy --dry-run ausgeführt, um die Gültigkeit der Konfiguration zu prüfen und eine Vorschau der Bereitstellungsschritte zu erstellen, ohne Cloud-Ressourcen bereitzustellen. Sie können die Dry-Run-Ausgabe im Terminal prüfen, um zu bestätigen, dass alle Dateien und Einstellungen korrekt sind.

7. In Agent Runtime bereitstellen

Stellen Sie Ihren Ambient Expense Agent in der Laufzeit für KI-Agenten bereit.

👉 Prompt Antigravity:

Deploy this agent to Agent Runtime.

Wenn Antigravity diesen Prompt ausführt, wird der Skill google-agents-cli-deploy aktiviert und agents-cli deploy --project YOUR_PROJECT_ID --region us-west1 wird ausgeführt. Das Verpacken, Hochladen und Bereitstellen der Agent-Laufzeit dauert in der Regel 5 bis 10 Minuten. Antigravity überwacht den Bereitstellungsfortschritt im Terminal und zeigt nach Abschluss die URL des Live-Endpunkts an.

💡 Profi-Tipp (Zeitüberschreitungsfenster verwalten): Wenn Sie nicht möchten, dass Ihr Terminal während langer Bereitstellungen gesperrt wird, können Sie Antigravity anweisen, die Bereitstellung asynchron mit dem Flag --no-wait zu starten und den Fortschritt später mit agents-cli deploy --status zu prüfen.

Wenn Sie Probleme beim Bereitstellen Ihres Agents haben, sollten Sie eine andere Region verwenden. Mit dem Google Cloud Region Picker können Sie die beste Region für Ihr Projekt basierend auf Latenz, Preis und CO₂-Bilanz ermitteln.

8. Agent testen

Nachdem Ihr Agent bereitgestellt wurde, können Sie überprüfen, ob er kleine Ausgaben automatisch genehmigt und größere Ausgaben ordnungsgemäß für eine Überprüfung durch einen Menschen markiert.

👉 Antigravity auffordern, die live bereitgestellte Engine zu überprüfen:

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

Hinweis:Wenn Antigravity diesen Test-Prompt für Ihren Live-Endpunkt ausführt und dabei Bereitstellungs- oder Ausführungsfehler auftreten, wird das Problem automatisch behoben, die erforderlichen Codekorrekturen werden angewendet und der Agent wird für Sie neu bereitgestellt.

Alternativ können Sie Ihren Agenten manuell mit der Cloud Console Playground-Vorschau testen. So öffnen Sie den Playground:

1. Wählen Sie in der Google Cloud Console im Navigationsmenü Agent Platform > Deployments aus.
2. Wählen Sie Ihren bereitgestellten Agent aus der Liste der Bereitstellungen aus.
3. Klicken Sie auf den Button Playground, um die interaktive Testoberfläche für den Chat zu öffnen.

👉 So testen Sie die automatische Genehmigung (unter 100 $): Fügen Sie die folgende JSON-Nutzlast in das Chatfeld ein:

{"data": {"amount": 50.0, "submitter": "[e-mail]", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

Sie sollten eine JSON-Antwort mit der Ausgabe des auto_approve-Knotens mit dem Status „approved“ (genehmigt) erhalten.

👉 So testen Sie den Human-in-the-Loop-Ablauf (HITL): Fügen Sie die folgende JSON-Nutzlast ein.

{"data": {"amount": 150.0, "submitter": "[e-mail]", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

Dadurch wird der review_agent ausgelöst, die Warnung ausgegeben und die Ausführung angehalten. Es wird ein RequestInput (Human-in-the-loop) mit der Aufforderung zur Genehmigung zurückgegeben.

9. Produktions-KI-Agenten überwachen und beobachten

Mit Agent Runtime wird die Telemetrie automatisch eingerichtet. Für jede Interaktion, jeden Modellaufruf und jede Toolausführung werden Echtzeitlogs und ‑spans in Ihr Projekt gestreamt.

1. Traces prüfen: Öffnen Sie die Cloud Trace Console, um Karten für Live-Transaktionen, Modelllatenzen und Tool-Ausführungsschritte zu prüfen.
2. Audit-Logs: Mit Cloud Logging können Sie die Standardausgabe und Diagnosestacktraces in Echtzeit prüfen.

3. Zusammengefasste Analysen: Wenn das Flag --bq-analytics beim Scaffolding aktiviert wurde, können Sie Ihre Logs in BigQuery mit SQL abfragen, um Genehmigungsraten und Trends bei Konversationsrunden aufzurufen.

Die folgende SQL-Abfrage enthält ein Beispiel für die Berechnung von Genehmigungsraten. Sie können Antigravity auffordern, diese Abfrage für Ihr spezifisches Projekt und BigQuery-Dataset anzupassen:

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. Optional: Registrierung in der Agent Registry überprüfen

Damit andere Dienste, Entwickler oder KI-Agents in Ihrer Organisation Ihren Ausgaben-KI-Agenten sicher finden und verwenden können, muss er in der Agent Registry (Gemini Enterprise) registriert sein.

Da Sie Ihren Agenten in der Laufzeit für KI-Agenten bereitgestellt haben, wird er automatisch in der Agent Registry registriert. Alle zukünftigen Aktualisierungen oder Löschungen Ihres KI-Agenten in der Agent Runtime werden automatisch auch mit der Agent Registry synchronisiert.

👉 Antigravity auffordern, die automatische Registrierung Ihres KI-Agenten zu bestätigen:

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Wenn Antigravity diesen Prompt ausführt, wird agents-cli publish gemini-enterprise --list im Terminal ausgeführt. Dadurch wird die Agent Registry abgefragt und alle registrierten Gemini Enterprise-Agents in Ihrem Projekt werden aufgelistet. So können Sie bestätigen, dass Ihr Ambient Expense Agent aktiv und in Ihrer gesamten Organisation auffindbar ist.

11. Bereinigen

Teilnehmer des Kaggle-Kurses: Wenn Sie dieses Lab im Rahmen des 5-Day AI Agents-Kurses von Kaggle durchführen und planen, mit dem nächsten Lab (Vibecode and Deploy a Frontend for an ADK Agent) fortzufahren, um den Frontend-Client und die Pub/Sub-Integration zu erstellen, löschen Sie Ihren bereitgestellten Agenten nicht. Sie benötigen diese aktive Cloud-Infrastruktur für das nächste Lab.

Damit Ihrem Google Cloud-Konto keine laufenden Gebühren in Rechnung gestellt werden, müssen Sie die bereitgestellten Ressourcen herunterfahren und bereinigen, wenn Sie fertig sind.

👉 Prompt Antigravity:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Wenn Antigravity diesen Prompt ausführt, wird der gesamte Prozess zum Bereinigen von Ressourcen automatisiert:

1. Bereitgestellten Agenten löschen: Die Remote-Agent-Laufzeit-ID wird aus deployment_metadata.json gelesen und die aktive Engine-Instanz wird programmatisch aus Vertex AI gelöscht.
2. Clean up Local Workspace (Lokalen Arbeitsbereich bereinigen): Dadurch wird die alte deployment_metadata.json-Datei aus dem Stammverzeichnis Ihres Projekts entfernt.
3. Artifact Registry bereinigen: Mit diesem Befehl wird gcloud artifacts docker images delete ausgeführt, um die erstellten Container-Images aus Artifact Registry zu entfernen und Cloud-Speicherplatz freizugeben.

12. Glückwunsch

Glückwunsch! Sie haben einen Ambient Expense Agent in Produktionsqualität in Google Cloud bereitgestellt und überprüft.

Das haben Sie gelernt

• Google Cloud-Einrichtung: Konfigurierte Projektanmeldedaten und aktivierte erforderliche Plattform-APIs.
• Tools und Kompetenzen: agents-cli wurde installiert und ADK-Begleit-Skills wurden in Antigravity geladen.
• Produktions-Scaffolding: Generiertes Agent Runtime-Scaffolding für einen ADK 2.0-Agenten.
• Lokale Überprüfung: Deterministische Lockfiles (uv lock) wurden erstellt und Testläufe wurden ausgeführt.
• Cloud-Bereitstellung: Ihr KI-Agent wird in der verwalteten Infrastruktur der Laufzeit für KI-Agenten gehostet.
• Observability & Analytics: Ausführung in Cloud Trace nachverfolgt und Telemetrie in BigQuery analysiert.
• Enterprise Discovery: Bestätigte automatische Registrierung in der Unternehmens-Agent Registry.

Wie geht es weiter?

• BigQuery-Analysen durchführen: Sie können die Telemetrielogs Ihres Agenten in BigQuery abfragen, um Genehmigungsraten und Trends bei Konversationsrunden im Zeitverlauf zu analysieren.
• Vibe to Live-Codelab: Verwenden Sie Google Antigravity, um einen Frontend-Client in Cloud Run zu entwickeln und ihn direkt mit Ihrem Live-Agent-Laufzeit-Backend-Endpunkt zu verbinden.

Kaggle-Auszeichnung „5-Day AI Agents“ erhalten 🎉

Haben Sie dieses Lab im Rahmen des 5-Day AI Agents: Intensive Vibe Coding Course with Google von Kaggle absolviert? So fordern Sie Ihr Abzeichen für die erfolgreiche Teilnahme an:

5-Day AI Agents Badge

Verweise

• Dokumentation zum Agent Development Kit (ADK)
• Gemini Enterprise Agent Platform-Laufzeiten
• Referenzleitfaden für die Agents CLI (agents-cli)
• Übersicht über die Gemini Enterprise Agent Registry
• Google Cloud Trace-Dokumentation