Next ‘26 Developer Keynote: Debugging Agents At Scale

1. Wprowadzenie

Z tego ćwiczenia dowiesz się, jak debugować agentów AI działających w Google Cloud. Wdrożysz agenta symulatora w Agent Runtime, użyjesz Cloud Observability do wykrywania problemów oraz Gemini Cloud Assist i Antigravity IDE do znajdowania przyczyn błędów i ich naprawiania w czasie rzeczywistym.

Założeniem tej wersji demonstracyjnej jest to, że właśnie dodaliśmy do agenta symulatora ADK EventCompaction. Dzięki temu symulator może okresowo podsumowywać swój przepływ pracy za pomocą Gemini, co zmniejsza całkowity kontekst wysyłany do modelu w każdej turze, a tym samym poprawia jakość odpowiedzi i obniża całkowite koszty. Okazuje się jednak, że w naszej konfiguracji EventCompactionConfig jest błąd, który powoduje problemy z agentem. W tym laboratorium dowiesz się, jak znaleźć tego typu problem i szybko go rozwiązać.

Jakie zadania wykonasz

• Wdróż agenta symulatora maratonu w Agent Runtime.
• Skonfiguruj alert Cloud Monitoring, aby wykrywać błędy agenta.
• Analizuj błędy za pomocą Cloud Trace i Gemini Cloud Assist.
• Znajdź przyczynę problemu i zastosuj poprawkę do agenta za pomocą Antigravity i MCP.

Uwaga: Gemini Cloud Assist jest obecnie dostępny w prywatnej wersji testowej. Aby wykonać ten samouczek, nie musisz być na liście dozwolonych w przypadku Cloud Assist. Wszystkie kroki Cloud Assist są odseparowane od kroku 8 (opcjonalnie): Korzystanie z analiz Cloud Assist – pomiń tę stronę, jeśli nie masz jeszcze dostępu do Cloud Assist.

Czego potrzebujesz

• przeglądarka, np. Chrome;
• konto Google,
• Antigravity (obsługuje systemy macOS, Linux i Windows)
• Python 3.13 lub nowszy.
• uv (system zarządzania pakietami Pythona)

Szacowany czas trwania: 45 minut

Szacowany koszt: mniej niż 5 USD

2. Zanim zaczniesz

Tworzenie projektu Google Cloud

1. W konsoli Google Cloud wybierz lub utwórz projekt w chmurze Google Cloud.
2. Sprawdź, czy w projekcie Cloud włączone są płatności.

Konfigurowanie środowiska

Otwórz Antigravity i zaloguj się. Następnie otwórz Terminal, naciskając cmd-shift-P (lub ctrl-shift-P), a potem wpisując „Create New Terminal” (Utwórz nowy terminal).

1. Uwierzytelnij się w Google Cloud z terminala:

gcloud auth login
gcloud auth application-default login

2. Ustaw identyfikator projektu:

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

Włącz interfejsy API

Aby włączyć wymagane interfejsy API Google Cloud, uruchom to polecenie:

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

Jeśli jesteś na liście dozwolonych w przypadku Gemini Cloud Assist (prywatna wersja testowa), włącz te dodatkowe interfejsy API:

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

3. Konfigurowanie agenta symulatora

W tym kroku sklonujesz repozytorium demonstracyjne i skonfigurujesz zmienne środowiskowe dla agenta symulatora.

Klonowanie repozytorium

Sklonuj repozytorium next-26-keynotes i przejdź do katalogu demo:

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

Konfigurowanie zmiennych środowiskowych

Agent symulatora używa do konfiguracji pliku .env.

Znajdź plik sample.env po lewej stronie okna Antigravity (Eksplorator):

Otwórz sample.env i zaktualizuj pole GCP_PROJECT_ID, wpisując w nim rzeczywisty identyfikator projektu Google Cloud. Plik powinien wyglądać podobnie do tego:

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

Włączamy integracje OpenTelemetry, aby rejestrować szczegółowe ślady wywołań narzędzi i procesu rozumowania agenta.

4. Wdrażanie agenta symulatora w Agent Runtime

Teraz wdrożysz agenta w Agent Runtime za pomocą pakietu Agent Development Kit (ADK).

Instalowanie zależności

uv sync

Wdrażanie w środowisku Agent Runtime

1. Uruchom polecenie adk deploy. Ten krok spakuje agenta i wdroży go w Google Cloud (Agent Runtime).

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

Może to potrwać do 5 minut. Powinny się pojawić dane wyjściowe podobne do tych:

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

Zapisz wygenerowany identyfikator Agent Runtime. Będą one potrzebne później.

2. W przeglądarce otwórz konsolę Agent Runtime. Powinna być widoczna usługa simulator_agent działająca w środowisku Agent Runtime z włączonym zbieraniem danych telemetrycznych.

5. Konfigurowanie zasady tworzenia alertów

Aby automatycznie wykrywać błędy Agent Runtime, w konsoli Google Cloud utworzysz alert oparty na logach.

1. Otwórz konsolę Cloud Monitoring – Alerty.

2. Kliknij Edytuj kanały powiadomień. Przewiń w dół do typu E-mail, a następnie utwórz kanał powiadomień e-mail, który będzie wysyłać powiadomienia na Twój osobisty adres e-mail. Kliknij Zapisz.

3. Wróć do panelu Alerty i kliknij Utwórz zasadę.
4. Po prawej stronie ekranu kliknij Utwórz alert oparty na logach.

5. Przekierujemy Cię do eksploratora logów. Wklej to zapytanie do dziennika, zastępując fragment identyfikatorem projektu.

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

To zapytanie do logów wyszukuje logi błędów w agencie Agent Runtime, gdzie ReasoningEngine to nazwa interfejsu API Agent Runtime.

6. Kliknij Uruchom zapytanie. Nie zobaczysz jeszcze żadnych dzienników – to normalne.
7. Na pasku narzędzi wyników kliknij Działania, a następnie Utwórz alert dotyczący logów.

8. skonfigurować alert oparty na logach, Nadaj alertowi dowolną nazwę, a następnie ustaw poziom ważności na Błąd.

9. Kliknij Dalej, aby przejść do sekcji „Ustaw częstotliwość powiadomień” (zachowaj ustawienia domyślne).

10. W sekcji Kto ma otrzymywać powiadomienia? skonfiguruj alert tak, aby wywoływał utworzony przez Ciebie kanał powiadomień e-mail (np. My Email).
11. Kliknij Zapisz.

6. Wywoływanie incydentu

Teraz, gdy agent jest wdrożony i monitorowany, spróbujmy wywołać symulację maratonu w taki sposób, aby wygenerować błąd.

1. W konsoli Google Cloud otwórz konsolę Agent Runtime.
2. Kliknij simulator_agent.
3. Na górnym pasku narzędzi kliknij Playground (Plac zabaw). Spowoduje to rozpoczęcie nowej sesji z agentem pakietu ADK.

4. W oknie czatu sesji wpisz Test Simulation i naciśnij Enter, aby wysłać prompta.

Spowoduje to rozpoczęcie symulacji maratonu, w której tysiące wirtualnych biegaczy pokonają zaplanowaną trasę. Powinno być widocznych kilka wywołań narzędzi do get_runner_telemetry i analyze_medical_risk, ponieważ symulacja ocenia wiele „stref” wyścigu.

Po kilku minutach agent powinien przestać działać i nie zwrócić żadnej odpowiedzi.

5. Po upływie około minuty w skrzynce odbiorczej powinien pojawić się e-mail z powiadomieniem o nowym incydencie w agencie.

Kliknij Wyświetl incydent, aby otworzyć konsolę Cloud Monitoring. Przejdź do następnej strony, aby zbadać problem w konsoli.

7. Zbadaj incydent w konsoli

1. Wyświetl incydent w konsoli Cloud Monitoring. Powinny być widoczne logi błędów pochodzące z agenta symulatora.

Z tego widoku trudno dokładnie określić, w którym momencie wystąpił błąd agenta. Aby zobaczyć wywołania narzędzi i proces rozumowania agenta, sprawdzimy jego logi czasu.

2. Ponownie otwórz konsolę Agent Runtime. Kliknij simulator_agent, a potem otwórz kartę Ślady.

3. Kliknij na liście najnowszy ślad. Następnie w prawym górnym rogu kliknij Oś czasu. Powinien wyświetlić się widok śledzenia z poszczególnymi „zakresami”. Jeden zakres reprezentuje wywołanie modelu lub narzędzia w procesie pracy agenta.

4. W widoku śledzenia kliknij ostatni zakres. Powinien być czerwony.
5. Kliknij Stacktrace. Powinny wyświetlić się logi błędów dotyczące wywołania modelu Gemini API. Chodzi o błąd 400: Invalid Argument. Sygnalizuje to problem na poziomie żądania z ładunkiem, który symulator wysłał do interfejsu Gemini API.

8. [Opcjonalnie] Debugowanie za pomocą analiz Cloud Assist

Wykonaj te czynności tylko wtedy, gdy masz dostęp do Gemini Cloud Assist (wersja prywatna). W przeciwnym razie przejdź do następnej strony.

1. W przypadku nieudanego zakresu kliknij Dzienniki i zdarzenia. Znajdź dziennik „Wyjątek” z przyciskiem z gwiazdką obok. Następnie kliknij Sprawdź log.

2. Spowoduje to rozpoczęcie analizy za pomocą Cloud Assist w panelu bocznym po prawej stronie ekranu. Wczytanie zajmie około 3–5 minut.

3. Po zakończeniu otwórz dochodzenie.

4. Wyświetl podsumowanie analizy zagrożeń.

5. Przewiń w dół i wyświetl hipotezy. Gemini Cloud Assist powinien wskazać konkretny wiersz w pliku agent.py agenta symulatora, który powoduje błąd 400 interfejsu Gemini API.

Przyjrzyjmy się bliżej temu problemowi, otwierając kod źródłowy agenta i używając narzędzia Antigravity do znalezienia jego głównej przyczyny. Przejdź do następnej strony.

9. Używanie narzędzia Antigravity do wykrywania i usuwania przyczyn problemów

1. Ponownie otwórz Antigravity.
2. W prawym górnym rogu ekranu otwórz Menedżera agentów.

3. Sprawdź, czy model jest ustawiony na Gemini 3 Flash i tryb planowania.

4. Wpisz ten prompt i naciśnij Enter.

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.    

Powinna pojawić się usługa Antigravity, która analizuje kod w agent.py i wyszukuje w GitHubie powiązane problemy:

Główną przyczyną błędu 400 w Gemini API jest przekroczenie limitu tokenów kontekstu wejściowego Gemini 3 Flash, który wynosi około miliona. Dzieje się tak, ponieważ nie wywołujemy funkcji EventCompaction wystarczająco często, aby skutecznie podsumowywać ogromne odpowiedzi z wywołań narzędzi w narzędziu Simulator Agents.

Aby rozwiązać ten problem, Antigravity powinien zaproponować dodanie parametru token_threshold do parametru EventsCompactionConfig, aby okresowo kompresować kontekst w ramach każdego wywołania po osiągnięciu określonej liczby tokenów.

Jest to zgodne z rozwiązaniem sugerowanym w tym zgłoszeniu na GitHubie.

Zastosuj poprawkę do agent.py.

Sprawdź, czy widzisz coś podobnego do tego:

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,
    ),
)

Ważne jest, aby ustawić wartości token_threshold i event_retention_size.

10. Ponowne wdrażanie i weryfikacja poprawki

Po zastosowaniu token_threshold poprawki do EventCompactionConfig agenta ADK możemy ponownie wdrożyć agenta symulatora w środowisku Agent Runtime.

1. Otwórz Antigravity –> New Terminal (Nowy terminal).
2. Ustaw zmienne środowiskowe. W miejsce AGENT_RUNTIME_ID wstaw pełną nazwę zasobu simulator_agent. Znajdziesz go w konsoli Agent Runtime – na liście agentów.

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

3. Ponownie wdróż agenta:

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

Wykonanie tych poleceń zajmie kilka minut. Po pomyślnym zakończeniu operacji zobaczysz:

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

4. Otwórz konsolę Agent Runtime. Ponownie otwórz simulator_agent. Kliknij Playground.
5. Wpisz ten sam prompt: Test Simulation, a potem naciśnij Enter.
6. Pełna symulacja backendu Marathon powinna potrwać kilka minut. Powinno się pojawić kilka wywołań narzędzi. W końcu powinna pojawić się odpowiedź podobna do tej:

Oznacza to, że symulator został uruchomiony. ✅

7. Otwórz widok śledzenia dla tej sesji ADK.
8. Powinny być widoczne wszystkie zakresy „niebieskie” bez błędów oznaczonych na czerwono. Zwróć uwagę, że łączna liczba tokenów w sesjach przekracza limit tokenów kontekstu interfejsu Gemini API wynoszący 1 milion. To w porządku, ponieważ teraz funkcja EventCompaction jest uruchamiana wystarczająco często w ramach każdego wywołania, aby uniknąć przekroczenia ogólnego limitu kontekstu dla poszczególnych wywołań modelu.

🎊 Hurra! Naprawiliśmy błąd w agencie symulatora.

11. Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami, usuń zasoby utworzone podczas tego ćwiczenia.

Usuwanie aplikacji Agent Runtime

Instancję Reasoning Engine możesz usunąć w konsoli lub za pomocą polecenia gcloud (jeśli masz nazwę zasobu). Aby uprościć proces, użyj konsoli:

1. Otwórz stronę Agent Runtime.
2. Kliknij simulator_agent –> kliknij przycisk z trzema kropkami po prawej stronie.
3. Kliknij Usuń.

Usuwanie zasady Cloud Monitoring

1. Otwórz konsolę Cloud Monitoring –> Alerty.
2. Przewiń w dół do sekcji Zasady, a następnie kliknij przycisk z 3 kropkami, aby usunąć zasady.

12. 🎊 Gratulacje!

Gratulacje! Udało Ci się debugować agenta AI w Google Cloud.

Czego się nauczysz

• Jak wdrażać agenty w Agent Runtime.
• Jak wykrywać błędy za pomocą alertów Cloud Monitoring.
• Jak analizować aktywne incydenty za pomocą Cloud Logging i widoku śledzenia środowiska wykonawczego agenta.
• Jak analizować błędy za pomocą Gemini Cloud Assist.
• Jak używać Antigravity do znajdowania przyczyn błędów agenta i ich naprawiania.
• Jak dostroić kompresję zdarzeń ADK, aby obsługiwać długotrwałe interakcje agenta z użyciem wielu narzędzi.

Dalsze kroki

• Dowiedz się więcej o Agent Runtime.
• Dowiedz się więcej o zestawie Agent Development Kit.
• Dowiedz się więcej o alertach w Cloud Monitoring.
• Dowiedz się więcej o Gemini Cloud Assist.