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 środowisku wykonawczym agenta, 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 łączne koszty. Ale dowiemy się, że w naszym pliku 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 środowisku wykonawczym agentów.
• 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: usługa Gemini Cloud Assist jest obecnie dostępna 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 poziomu 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 Google Cloud API, 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 (wersja zapoznawcza), 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 przez agenta i jego procesu rozumowania.

4. Wdrażanie agenta symulatora w środowisku wykonawczym agentów

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

Instalowanie zależności

uv sync

Wdrażanie w środowisku wykonawczym agentów

1. Uruchom polecenie adk deploy. Ten krok pakuje agenta i wdraża 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 środowiska wykonawczego agenta. Będą Ci potrzebne później.

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

5. Konfigurowanie zasady tworzenia alertów

Aby automatycznie wykrywać błędy środowiska wykonawczego agenta, 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 środowiska wykonawczego agentów, gdzie ReasoningEngine to nazwa interfejsu API środowiska wykonawczego agentów.

6. Kliknij Uruchom zapytanie. Nie zobaczysz jeszcze żadnych dzienników – to normalne.
7. Na pasku narzędzi wyników kliknij Działania, a potem 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

Agent został wdrożony i jest monitorowany, więc spróbujmy wywołać symulację maratonu w taki sposób, aby wygenerować błąd.

1. W konsoli Google Cloud otwórz konsolę Środowisko wykonawcze agenta.
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 pokonuje 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 zwracać odpowiedzi.

5. Po upływie minuty lub dwóch 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 od agenta symulatora.

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

2. Ponownie otwórz konsolę środowiska wykonawczego agentów. 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 śladu kliknij ostatni zakres. Powinien być czerwony.
5. Kliknij Stacktrace. Powinny wyświetlić się logi błędów dotyczące wywołania modelu Gemini API. W szczególności błąd 400: Invalid Argument. Sygnalizuje to problem na poziomie żądania z ładunkiem, który agent symulujący 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 zakresie, w którym wystąpił błąd, 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 może potrwać od 3 do 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 Planowanie.

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 1 miliona. Dzieje się tak, ponieważ nie wywołujemy funkcji EventCompaction wystarczająco często, aby skutecznie podsumowywać ogromne odpowiedzi z wywołań narzędzi przez agentów symulacji.

Aby to naprawić, Antigravity powinien zaproponować dodanie parametru token_threshold do 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 weryfikowanie poprawki

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

1. Otwórz Antigravity –> New Terminal (Nowy terminal).
2. Ustaw zmienne środowiskowe. W miejsce AGENT_RUNTIME_ID należy wstawić pełną nazwę zasobu simulator_agent. Znajdziesz go w konsoli środowiska wykonawczego agenta – 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ę środowiska wykonawczego agentów. 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 „niebieskie” zakresy bez czerwonych błędów. Zwróć uwagę, że łączna liczba tokenów w sesjach przekracza limit 1 miliona tokenów kontekstu w interfejsie Gemini API. 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 laboratorium.

Usuwanie aplikacji środowiska wykonawczego agenta

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ę Środowisko wykonawcze agentów.
2. Kliknij simulator_agent –> 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 trzema kropkami, aby usunąć zasady.

12. 🎊 Gratulacje!

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

Czego się dowiedziałeś(-aś)

• Jak wdrażać agentów w środowisku wykonawczym agentów.
• 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 i naprawiania błędów agenta.
• Jak dostroić kompresję zdarzeń ADK, aby obsługiwać długotrwałe tury agenta z dużą liczbą narzędzi.

Dalsze kroki

• Dowiedz się więcej o środowisku wykonawczym agentów.
• 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.