Next ‘26 Developer Keynote: Debugging Agents At Scale

1. Einführung

In diesem Codelab erfahren Sie, wie Sie KI-Agents debuggen, die in Google Cloud ausgeführt werden. Sie stellen einen Simulator-Agenten in der Agent Runtime bereit, verwenden Cloud Observability, um Probleme zu erkennen, und nutzen Gemini Cloud Assist und die Antigravity IDE, um Fehler in Echtzeit zu beheben.

In dieser Demo gehen wir davon aus, dass wir dem Simulator-Agenten gerade ADK EventCompaction hinzugefügt haben. So kann der Simulator seinen Workflow regelmäßig mit Gemini zusammenfassen. Dadurch wird der gesamte Kontext, der bei jedem Zug an das Modell gesendet wird, reduziert, was die Antwortqualität verbessert und die Gesamtkosten senkt. Wir werden jedoch feststellen, dass es einen Fehler in unserer EventCompactionConfig gibt, der zu Fehlern im Agent führt. In diesem Codelab wird beschrieben, wie wir ein solches Problem finden und schnell beheben können.

Aufgaben

• Stellen Sie den Marathon Simulator-Agenten in der Laufzeit für KI-Agenten bereit.
• Richten Sie eine Cloud Monitoring-Benachrichtigung ein, um Agent-Fehler zu erkennen.
• Untersuchen Sie Fehler mit Cloud Trace und Gemini Cloud Assist.
• Die Ursache des Problems ermitteln und den Agenten mit Antigravity und MCP patchen.

Hinweis: Gemini Cloud Assist befindet sich derzeit in der privaten Vorschau. Sie müssen nicht auf der Zulassungsliste stehen, um dieses Codelab mit Cloud Assist auszuführen. Alle Cloud Assist-Schritte sind auf #8 (Optional): Cloud Assist-Prüfungen verwenden beschränkt. Überspringen Sie diese Seite, wenn Sie noch nicht auf Cloud Assist zugreifen können.

Voraussetzungen

• Ein Webbrowser wie Chrome.
• Ein Google-Konto
• Antigravity (unterstützt Mac, Linux und Windows)
• Python 3.13 und höher.
• uv (Python-Paketmanager)

Geschätzte Dauer:45 Minuten

Geschätzte Kosten:weniger als 5 $

2. Hinweis

Google Cloud-Projekt erstellen

1. Wählen Sie in der Google Cloud Console ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein.

Umgebung einrichten

Öffnen Sie Antigravity und melden Sie sich an. Öffnen Sie dann ein Terminal, indem Sie cmd-shift-P (oder ctrl-shift-P) drücken und dann „Create New Terminal“ eingeben.

1. Authentifizieren Sie sich über das Terminal bei Google Cloud:

gcloud auth login
gcloud auth application-default login

2. Legen Sie Ihre Projekt-ID fest:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

APIs aktivieren

Führen Sie den folgenden Befehl aus, um die erforderlichen Google Cloud APIs zu aktivieren:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

Wenn Sie auf der Zulassungsliste für Gemini Cloud Assist (Private Preview) stehen, aktivieren Sie diese zusätzlichen APIs:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. Simulator-Agent einrichten

In diesem Schritt klonen Sie das Demorepository und konfigurieren die Umgebungsvariablen für den Simulator-Agent.

Repository klonen

Klonen Sie das next-26-keynotes-Repository und wechseln Sie in das Demoverzeichnis:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

Umgebungsvariablen konfigurieren

Der Simulator-Agent verwendet eine .env-Datei für die Konfiguration.

Suchen Sie die Datei sample.env auf der linken Seite des Antigravity-Fensters (Explorer):

Öffnen Sie sample.env und aktualisieren Sie das Feld GCP_PROJECT_ID mit Ihrer tatsächlichen Google Cloud-Projekt-ID. Die Datei sollte in etwa so aussehen:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

Wir aktivieren OpenTelemetry-Integrationen, um detaillierte Traces der Tool-Aufrufe und des Reasoning-Ablaufs des KI-Agents zu erfassen.

4. Simulator-Agent in der Laufzeit für KI-Agenten bereitstellen

Jetzt stellen Sie den KI-Agenten mit dem Agent Development Kit (ADK) in der Agent Runtime bereit.

Abhängigkeiten installieren

uv sync

In der Laufzeit für KI-Agenten bereitstellen

1. Führen Sie den Befehl adk deploy aus. In diesem Schritt wird Ihr KI-Agent verpackt und in Google Cloud (Agent Runtime) bereitgestellt.

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Die Ausführung kann bis zu 5 Minuten dauern. Die Ausgabe sollte in etwa so aussehen:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

Notieren Sie sich die generierte Agent Runtime-ID. Sie benötigen ihn später.

2. Öffnen Sie in einem Webbrowser die Agent Runtime-Konsole. simulator_agent sollte in der Laufzeit für KI-Agenten ausgeführt werden und die Erfassung von Telemetriedaten sollte aktiviert sein.

5. Benachrichtigungsrichtlinie einrichten

Um Agent Runtime-Fehler automatisch zu erkennen, erstellen Sie in der Google Cloud Console eine logbasierte Benachrichtigung.

1. Rufen Sie die Cloud Monitoring-Konsole – Benachrichtigungen auf.

2. Klicken Sie auf Benachrichtigungskanäle bearbeiten. Scrollen Sie nach unten zum Typ E-Mail und erstellen Sie einen E-Mail-Benachrichtigungskanal, der an Ihre private E-Mail-Adresse gesendet wird. Klicken Sie auf Speichern.

3. Kehren Sie zum Dashboard „Benachrichtigungen“ zurück und klicken Sie auf Richtlinie erstellen.
4. Klicken Sie rechts auf dem Bildschirm auf Logbasierten Alert erstellen.

5. Sie werden zum Log-Explorer weitergeleitet. Fügen Sie die folgende Log-Abfrage ein und ersetzen Sie durch Ihre Projekt-ID.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

Mit dieser Log-Abfrage wird in Ihrem Agent Runtime-Agent nach Error-Logs gesucht. „ReasoningEngine“ ist der zugrunde liegende API-Name für Agent Runtime.

6. Klicken Sie auf Abfrage ausführen. Es werden noch keine Logs angezeigt. Das ist normal.
7. Klicken Sie in der Ergebnissymbolleiste auf Aktionen und dann auf Logbenachrichtigung erstellen.

8. Konfigurieren Sie die logbasierte Benachrichtigung. Geben Sie der Benachrichtigung einen Namen und legen Sie den Schweregrad auf Fehler fest.

9. Klicken Sie für den Abschnitt „Benachrichtigungshäufigkeit festlegen“ auf Weiter (behalten Sie die Standardeinstellungen bei).

10. Legen Sie für Wer soll benachrichtigt werden? fest, dass der Alarm den gerade eingerichteten E-Mail-Benachrichtigungskanal auslösen soll (z. B. My Email).
11. Klicken Sie auf Speichern.

6. Vorfall auslösen

Nachdem der Agent bereitgestellt und überwacht wird, versuchen wir, die Marathonsimulation so aufzurufen, dass ein Fehler ausgegeben wird.

1. Rufen Sie in der Google Cloud Console die Agent Runtime-Konsole auf.
2. Klicken Sie auf simulator_agent.
3. Klicken Sie in der oberen Symbolleiste auf Playground. Dadurch wird eine neue Sitzung mit dem ADK-KI-Agenten gestartet.

4. Geben Sie im Sitzungs-Chatfenster Test Simulation ein und drücken Sie die Eingabetaste, um den Prompt zu senden.

Dadurch wird die Marathonsimulation gestartet, bei der Tausende von simulierten Läufern auf der geplanten Strecke verfolgt werden. Sie sollten mehrere Tool-Aufrufe für get_runner_telemetry und analyze_medical_risk sehen, da bei der Simulation mehrere „Zonen“ des Rennens ausgewertet werden.

Nach einigen Minuten sollte der Agent nicht mehr ausgeführt werden und keine Antwort zurückgeben.

5. Innerhalb von etwa einer Minute sollten Sie eine E‑Mail in Ihrem Posteingang erhalten, in der Sie über einen neuen Vorfall im Agent informiert werden.

Klicken Sie auf Vorfall ansehen, um die Cloud Monitoring-Konsole zu öffnen. Fahren Sie mit der nächsten Seite fort, um das Problem in der Konsole zu untersuchen.

7. Vorfall in der Console untersuchen

1. Rufen Sie den Vorfall in der Cloud Monitoring-Konsole auf. Sie sollten Fehlerlogs vom Simulator-Agent sehen.

Aus dieser Ansicht ist nur schwer zu erkennen, an welcher Stelle der Agent fehlgeschlagen ist. Um die zugrunde liegenden Tool-Aufrufe und den Ablauf der Argumentation des Agents zu sehen, untersuchen wir die Traces des Agents.

2. Öffnen Sie die Agent Runtime-Konsole noch einmal. Klicken Sie auf simulator_agent und öffnen Sie dann den Tab Traces (Traces).

3. Klicken Sie in der Liste auf den neuesten Trace. Klicken Sie dann rechts oben auf Zeitachse. Sie sollten eine Ablaufverfolgungsansicht mit einzelnen „Spans“ sehen. Ein Bereich stellt einen Modell- oder Toolaufruf im Workflow des Agents dar.

4. Klicken Sie in der Trace-Ansicht auf den letzten Bereich. Sie sollte rot sein.
5. Klicken Sie auf Stacktrace. Sie sollten Fehlerlogs zu einem Gemini API-Modellaufruf sehen. Konkret handelt es sich um einen 400: Invalid Argument-Fehler. Dies weist auf ein Problem auf Anfrageebene mit einer Nutzlast hin, die der Simulator-Agent an die Gemini API gesendet hat.

8. [Optional] Cloud Assist-Prüfungen zum Debuggen verwenden

Führen Sie diese Schritte nur aus, wenn Sie für Gemini Cloud Assist (Private Preview) auf die Zulassungsliste gesetzt wurden. Andernfalls fahren Sie mit der nächsten Seite fort.

1. Klicken Sie im fehlerhaften Zeitraum auf Logs und Ereignisse. Suchen Sie nach dem Log „Exception“ mit der Glitzer-Schaltfläche daneben. Klicken Sie dann auf Log untersuchen.

2. Dadurch wird eine Cloud Assist-Prüfung über eine Seitenleiste auf der rechten Seite des Bildschirms gestartet. Das Laden dauert etwa 3–5 Minuten.

3. Öffnen Sie die Untersuchung, sobald sie abgeschlossen ist.

4. Zusammenfassung der Prüfung ansehen

5. Scrollen Sie nach unten und sehen Sie sich die Hypothesen an. Gemini Cloud Assist sollte die spezifische Zeile in der agent.py-Datei des Simulator-Agents identifiziert haben, die den Gemini API-Fehler 400 auslöst.

Sehen wir uns den Quellcode des Agents an und verwenden wir Antigravity, um die Ursache des Problems zu finden. Fahren Sie mit der nächsten Seite fort.

9. Antigravity verwenden, um die Ursache des Problems zu ermitteln und es zu beheben

1. Öffnen Sie Antigravity noch einmal.
2. Öffnen Sie rechts oben auf dem Bildschirm Agent Manager.

3. Achten Sie darauf, dass das Modell auf Gemini 3 Flash und den Modus Planung eingestellt ist.

4. Geben Sie den folgenden Prompt ein und drücken Sie die Eingabetaste.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

Antigravity sollte den Code in agent.py prüfen und auf GitHub nach relevanten Problemen suchen:

Die Ursache für den Gemini API-Fehler 400 ist, dass wir das Tokenlimit für den Eingabekontext von Gemini 3 Flash von etwa 1 Million überschreiten. Der Grund dafür ist, dass wir die Ereigniskompaktierung nicht oft genug auslösen, um die umfangreichen Antworten aus den Tool-Aufrufen des Simulator Agents-Tools effektiv zusammenzufassen.

Um dieses Problem zu beheben, sollte Antigravity vorschlagen, dem EventsCompactionConfig einen token_threshold-Parameter hinzuzufügen, um den Kontext bei jedem Aufruf regelmäßig zu komprimieren, sobald eine bestimmte Anzahl von Tokens erreicht ist.

Dies entspricht dem in diesem GitHub-Problem vorgeschlagenen Fix.

Wenden Sie die Korrektur auf agent.py. an.

Prüfen Sie, ob die Ausgabe in etwa so aussieht:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

Wichtig: token_threshold und event_retention_size müssen festgelegt werden.

10. Korrektur neu bereitstellen und validieren

Nachdem wir den token_threshold-Fix auf die EventCompactionConfig des ADK-Agents angewendet haben, können wir den Simulator-Agenten in der Agent Runtime neu bereitstellen.

1. Öffnen Sie Antigravity –> Neues Terminal.
2. Umgebungsvariablen festlegen AGENT_RUNTIME_ID sollte der vollständige Ressourcenname Ihres simulator_agent sein. Sie finden sie in der Agent Runtime Console in der Agent-Liste.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. Stellen Sie den Agent noch einmal bereit:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Der Vorgang dauert einige Minuten. Bei Erfolg sollte Folgendes angezeigt werden:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. Öffnen Sie die Agent Runtime-Konsole. Öffnen Sie simulator_agent noch einmal. Klicken Sie auf Playground.
5. Geben Sie denselben Prompt ein: Test Simulation. Drücken Sie dann die Eingabetaste.
6. Die vollständige Backend-Marathon-Simulation sollte einige Minuten dauern. Sie sollten mehrere Toolaufrufe sehen. Schließlich sollte eine Antwort wie diese angezeigt werden:

Das bedeutet, dass der Simulator erfolgreich ausgeführt wurde. ✅

7. Öffnen Sie die Trace-Ansicht für diese ADK-Sitzung.
8. Sie sollten alle „blauen“ Spannen ohne rote Fehler sehen. Die Gesamtzahl der Tokens der Sitzungen überschreitet das Limit von 1 Million Kontext-Tokens der Gemini API. Das ist in Ordnung, da EventCompaction jetzt oft genug innerhalb jedes Aufrufs ausgeführt wird, um das allgemeine Kontextlimit für einzelne Modellaufrufe nicht zu überschreiten.

🎊 Hurra! Wir haben den Fehler im Simulator-KI-Agenten behoben.

11. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um zu vermeiden, dass Ihrem Google Cloud-Konto Gebühren in Rechnung gestellt werden.

Löschen Sie die Agent Runtime App.

Sie können die Reasoning Engine-Instanz über die Konsole oder mit dem Befehl gcloud löschen (sofern Sie den Ressourcennamen haben). Verwenden Sie der Einfachheit halber die Konsole:

1. Rufen Sie die Seite Laufzeit für KI-Agenten auf.
2. Wählen Sie das simulator_agent aus und klicken Sie rechts auf das Dreipunkt-Menü.
3. Klicken Sie auf Löschen.

Cloud Monitoring-Richtlinie löschen

1. Rufen Sie die Cloud Monitoring-Konsole > Benachrichtigungen auf.
2. Scrollen Sie nach unten zu Richtlinien und klicken Sie dann auf das Dreipunkt-Menü, um die Richtlinie zu löschen.

12. 🎊 Glückwunsch!

Glückwunsch! Sie haben gerade einen KI-Agenten in Google Cloud debuggt.

Das haben Sie gelernt

• KI‑Agenten in Agent Runtime bereitstellen
• Fehler mit Cloud Monitoring-Benachrichtigungen erkennen
• So untersuchen Sie aktive Vorfälle mit Cloud Logging und der Trace-Ansicht der Agent-Laufzeit.
• Gemini Cloud Assist zur Untersuchung von Fehlern verwenden
• Antigravity verwenden, um Agentenfehler zu beheben und zu patchen
• So optimieren Sie die ADK-Ereigniskompaktierung für lange, toollastige Agenten-Turns.

Nächste Schritte

• Weitere Informationen zu Agent Runtime
• Weitere Informationen zum Agent Development Kit
• Weitere Informationen zu Benachrichtigungen in Cloud Monitoring
• Weitere Informationen zu Gemini Cloud Assist