Wdrażanie agenta ADK w Agent Runtime za pomocą interfejsu wiersza poleceń Agents

1. Przegląd

Te ćwiczenia są częścią 5-dniowego intensywnego kursu programowania agentów AI z użyciem Vibecode i Google na Kaggle. Dodatkowe ćwiczenia i materiały znajdziesz na stronie wydarzenia.

W tych ćwiczeniach przeniesiesz agenta ADK 2.0 z lokalnego środowiska programistycznego do wdrożenia produkcyjnego. Użyjesz agents-cli, aby spakować, zweryfikować i hostować przepływ pracy oparty na grafie w Agent Runtime w Google Cloud.

Aby poznać ten proces wdrażania, najpierw utworzysz lokalny prototyp agenta do obsługi wydatków od podstaw, a potem wdrożysz go w chmurze. (Więcej informacji o projektowaniu logiki podstawowej tego agenta znajdziesz w podstawowych ćwiczeniach na stronie wydarzenia na Kaggle). Agent do obsługi wydatków usprawnia raportowanie wydatków pracowników, natychmiast zatwierdzając standardowe roszczenia i oznaczając większe wydatki do sprawdzenia przez człowieka. W tle używa przepływu pracy opartego na grafie ADK 2.0 do koordynowania tych automatycznych zatwierdzeń i analizy ryzyka.

Czego się nauczysz

• Jak przygotować lokalny projekt agenta do obsługi wydatków do hostowania w chmurze.
• Jak utworzyć niezbędne deskryptory wdrożenia i otoczki produkcyjne.
• Jak przeprowadzać uruchomienia próbne i wdrażać kod bezpośrednio w Agent Runtime.
• Jak monitorować ślady wykonania agenta produkcyjnego za pomocą Cloud Trace.

Czego potrzebujesz

• Aktywny projekt w chmurze Google Cloud z włączonymi rozliczeniami.
• Zainstalowany i uwierzytelniony pakiet SDK gcloud.
• Zainstalowany menedżer pakietów uv.
• Zainstalowane Google Antigravity IDE.

Wymagania wstępne

W tych ćwiczeniach zakłada się, że znasz:

• poruszanie się po systemie za pomocą terminala,
• podstawowe pojęcia dotyczące programowania w Pythonie,
• podstawowe pojęcia dotyczące Google Cloud.

2. Konfigurowanie środowiska Google Cloud

Przed wdrożeniem musisz skonfigurować swój projekt w chmurze Google Cloud i włączyć niezbędne interfejsy API.

👉 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).

Gdy Antigravity wykona ten prompt, zaproponuje i uruchomi niezbędne polecenia terminala gcloud, aby skonfigurować projekt i włączyć usługi. Podczas uwierzytelniania Antigravity wyświetli w terminalu adres URL autoryzacji. Kliknij link, aby zalogować się w przeglądarce i przyznać dostęp. Gdy zalogujesz się w przeglądarce, Antigravity wznowi wykonywanie, aby ustawić zmienne środowiskowe projektu i włączyć wymagane interfejsy API.

Uwaga: jeśli jest to nowy projekt, gcloud może najpierw poprosić o włączenie interfejsu Service Usage API. Jeśli pojawi się prośba, kliknij link podany w terminalu, aby włączyć go w konsoli Cloud.

3. Konfigurowanie interfejsu wiersza poleceń agentów i umiejętności ADK

Aby Antigravity mogło tworzyć i wdrażać agenty ADK, potrzebuje zestawu umiejętności ADK. Są to połączone odniesienia do interfejsu ADK API, tworzenia szkieletu projektu, przepływu pracy wdrażania agents-cli i oceny. Zainstalowanie łańcucha narzędzi agents-cli powoduje też zainstalowanie tych umiejętności w agencie kodowania, co umożliwia mu zarządzanie pełnym cyklem życia agenta – od lokalnego tworzenia szkieletu po wdrożenie w chmurze.

👉 Skopiuj i wklej ten prompt do Antigravity:

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.

Gdy Antigravity wykona ten prompt, uruchomi w terminalu polecenie uvx google-agents-cli setup, aby zainstalować interfejs wiersza poleceń i powiązane z nim umiejętności. Następnie uruchomi polecenie agents-cli info, aby sprawdzić instalację, i wyświetli w czacie nowo zainstalowane umiejętności domeny (np. google-agents-cli-deploy i google-agents-cli-workflow).

Uwaga dla użytkowników Antigravity: podczas tych ćwiczeń Antigravity może generować plany implementacji lub wyświetlać wyskakujące okienka przed wykonaniem poleceń lub napisaniem kodu. Aby umożliwić Antigravity kontynuowanie zadań, sprawdź i zatwierdź te plany lub wyskakujące okienka.

Wskazówka dotycząca limitów: jeśli podczas testowania lub programowania wyczerpiesz limit, przełącz model w Antigravity na inny dostępny model.

4. Tworzenie projektu agenta

Gdy środowisko chmurowe jest skonfigurowane, a umiejętności interfejsu wiersza poleceń zainstalowane, możesz wygenerować lokalną bazę kodu agenta. W tym kroku użyjesz Antigravity, aby utworzyć szkielet w pełni funkcjonalnego prototypu agenta do obsługi wydatków zgodnego z ADK 2.0.

Uwaga dla uczestników 5-dniowego kursu agentów AI na Kaggle: jeśli udało Ci się ukończyć ćwiczenia z Vibecode dotyczące agenta do obsługi wydatków w dniu 4 i wolisz wdrożyć istniejącą bazę kodu agenta niestandardowego, możesz pominąć ten krok tworzenia szkieletu i przejść do następnego kroku.

👉 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.

Gdy Antigravity wykona ten prompt, użyje nowo zainstalowanych umiejętności tworzenia szkieletu, aby uruchomić w terminalu polecenie agents-cli scaffold create expense-agent --adk. Następnie sprawdzi i dostosuje wygenerowany kod prototypu, aby mieć pewność, że expense-agent prawidłowo implementuje próg automatycznego zatwierdzania $100 i przepływ weryfikacji z udziałem człowieka w przepływie pracy grafu pakietu Agent Development Kit (ADK).

5. Przygotowanie do wdrożenia produkcyjnego

Środowisko wykonawcze agentów to w pełni zarządzana usługa Google Cloud, która umożliwia wdrażanie agentów AI w środowisku produkcyjnym, zarządzanie nimi i ich skalowanie. Środowisko wykonawcze agentów obsługuje złożone operacje związane z hostingiem, oferując środowisko stanowe z funkcjami takimi jak zarządzanie sesjami, pamięć długotrwała i bezpieczne piaskownice do wykonywania kodu.

Dlaczego warto wdrożyć w środowisku wykonawczym agentów?

Gdy tworzysz agenty lokalnie za pomocą Antigravity, agent działa na komputerze lokalnym w stosunku do localhost. Chociaż jest to świetne rozwiązanie do szybkiego tworzenia prototypów, agenty lokalne przestają działać, gdy zamkniesz laptopa.

Wdrożenie agenta w środowisku Agent Runtime przenosi przepływ pracy do w pełni zarządzanego, zawsze dostępnego środowiska Google Cloud. Ustanawia to bezpieczny, aktywny punkt końcowy backendu, który pozostaje aktywny przez całą dobę. W następnych ćwiczeniach utworzysz frontend, który będzie łączyć się bezpośrednio z tym punktem końcowym w chmurze, co zapewni agentowi publiczny adres URL.

Ponadto Agent Runtime zapewnia dedykowaną infrastrukturę zoptymalizowaną specjalnie pod kątem agentów AI, oferując wbudowane funkcje takie jak:

• Zarządzane wykonywanie stanowe: wbudowane zarządzanie sesjami i utrwalanie pamięci długotrwałej w kolejnych turach rozmowy.
• Bezpieczna piaskownica: bezpieczne wykonywanie dynamicznych wywołań narzędzi i kodu wygenerowanego przez agenta w izolowanych środowiskach.
• Widoczność w przedsiębiorstwie: gotowe do użycia przesyłanie danych telemetrycznych bezpośrednio do Cloud Trace i Cloud Logging.

Aby hostować agenta w środowisku wykonawczym agentów, musisz rozszerzyć lokalny katalog projektu o deskryptory produkcyjne, schematy i otoczki punktów końcowych.

👉 Prompt Antigravity:

Scaffold the production deployment files for Agent Runtime.

Gdy Antigravity wykona ten prompt, uruchomi w katalogu głównym projektu polecenie agents-cli scaffold enhance --deployment-target agent_runtime --yes. To polecenie skanuje katalog i automatycznie generuje:

• app/agent_runtime_app.py: otoczka usługi klasy produkcyjnej.
• deployment_metadata.json: schemat układu używany przez Agent Runtime do uruchamiania zasobów.

Logika podstawowa agenta w app/agent.py pozostaje całkowicie nienaruszona i zachowana.

6. Pakowanie i weryfikacja lokalna

Zanim rozpoczniesz przesyłanie do chmury, zablokuj pakiety i uruchom lokalny test, aby zidentyfikować potencjalne konflikty zależności.

👉 Prompt Antigravity:

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

Gdy Antigravity wykona ten prompt, najpierw uruchomi w terminalu polecenie uv lock, aby wygenerować deterministyczny plik blokady, co zapewni spójne wersje bibliotek w chmurze. Następnie wykona polecenie agents-cli deploy --dry-run, aby sprawdzić prawidłowość konfiguracji i wyświetlić podgląd kroków wdrożenia bez udostępniania zasobów w chmurze. Możesz sprawdzić wynik testu w terminalu, aby potwierdzić, że wszystkie pliki i ustawienia są prawidłowe.

7. Wdrażanie w środowisku Agent Runtime

Wdróż agenta do obsługi wydatków w Agent Runtime.

👉 Prompt Antigravity:

Deploy this agent to Agent Runtime.

Gdy Antigravity wykona ten prompt, aktywuje umiejętność google-agents-cli-deploy i uruchomi polecenie agents-cli deploy --project YOUR_PROJECT_ID --region us-west1. Proces pakowania, przesyłania i udostępniania Agent Runtime trwa zwykle 5–10 minut. Antigravity będzie monitorować postęp wdrażania w terminalu, a po zakończeniu wyświetli adres URL punktu końcowego na żywo.

💡 Wskazówka dla profesjonalistów (zarządzanie oknami limitu czasu): jeśli nie chcesz blokować terminala podczas długich wdrożeń, możesz poinstruować Antigravity, aby używało flagi --no-wait do asynchronicznego rozpoczęcia wdrożenia, a później sprawdzić postęp za pomocą polecenia agents-cli deploy --status.

Jeśli masz problemy z wdrożeniem agenta, spróbuj użyć innego regionu. Narzędzie do wybierania regionu Google Cloud może pomóc Ci określić najlepszy region dla Twojego projektu na podstawie opóźnienia, ceny i śladu węglowego.

8. Testowanie agenta

Po wdrożeniu agenta możesz sprawdzić, czy automatycznie zatwierdza małe wydatki i prawidłowo oznacza większe wydatki do weryfikacji przez człowieka.

👉 Poproś Antigravity o sprawdzenie wdrożonego silnika na żywo:

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.

Uwaga: gdy Antigravity uruchomi ten prompt testowy w punkcie końcowym na żywo, a napotka błędy wdrożenia lub wykonania, automatycznie spróbuje rozwiązać problem, zastosować niezbędne poprawki kodu i ponownie wdrożyć agenta.

Możesz też przetestować agenta ręcznie za pomocą podglądu w piaskownicy konsoli Cloud. Aby otworzyć piaskownicę:

1. W konsoli Google Cloud w menu nawigacyjnym wybierz Agent Platform > Wdrożenia.
2. Na liście wdrożeń wybierz wdrożonego agenta.
3. Kliknij przycisk Piaskownica , aby otworzyć interaktywny interfejs czatu testowego.

👉 Aby przetestować automatyczne zatwierdzanie (poniżej 100 USD), wklej ten ładunek JSON w polu czatu:

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

Powinna zostać zwrócona odpowiedź JSON z wynikiem węzła auto_approve ze stanem „zatwierdzono”.

👉 Aby przetestować przepływ weryfikacji przez człowieka, wklej ten ładunek JSON.

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

Spowoduje to uruchomienie review_agent, wyemitowanie ostrzeżenia i wstrzymanie wykonania, co spowoduje wyświetlenie RequestInput (weryfikacja przez człowieka) z prośbą o zatwierdzenie.

9. Monitorowanie i obserwowanie agenta produkcyjnego

W środowisku wykonawczym agentów dane telemetryczne są automatycznie przesyłane. Każda interakcja, wywołanie modelu i wykonanie narzędzia przesyła logi i zakresy w czasie rzeczywistym do Twojego projektu.

1. Sprawdzanie śladów: otwórz konsolę Cloud Trace, aby sprawdzić mapy transakcji na żywo, opóźnienia modelu i kroki wykonania narzędzia.
2. Logi kontrolne: użyj Cloud Logging, aby sprawdzić standardowe dane wyjściowe i ślady stosu diagnostycznego w czasie rzeczywistym.

3. Agregowanie danych analitycznych: jeśli podczas tworzenia szkieletu włączono flagę --bq-analytics, możesz wysyłać zapytania do logów w BigQuery za pomocą SQL, aby wyświetlać współczynniki zatwierdzeń i trendy w turach rozmowy.

Ten przykład zapytania SQL pokazuje, jak obliczyć współczynniki zatwierdzeń. Możesz poprosić Antigravity o dostosowanie tego zapytania do konkretnego projektu i zbioru danych BigQuery:

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. (Opcjonalnie) Sprawdzanie rejestracji w rejestrze agentów

Aby umożliwić innym usługom, deweloperom lub agentom w Twojej organizacji bezpieczne wykrywanie i korzystanie z agenta do obsługi wydatków, musi on być zarejestrowany w rejestrze agentów (Gemini Enterprise).

Ponieważ agent został wdrożony w Agent Runtime, jest automatycznie rejestrowany w rejestrze agentów. Wszystkie przyszłe aktualizacje lub usunięcia agenta w Agent Runtime będą automatycznie synchronizowane z rejestrem agentów.

👉 Poproś Antigravity o sprawdzenie automatycznej rejestracji agenta:

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

Gdy Antigravity wykona ten prompt, uruchomi w terminalu polecenie agents-cli publish gemini-enterprise --list. Spowoduje to wysłanie zapytania do rejestru agentów i wyświetlenie listy wszystkich zarejestrowanych agentów Gemini Enterprise w Twoim projekcie, co pozwoli Ci potwierdzić, że agent do obsługi wydatków jest aktywny i dostępny w całej organizacji.

11. Zwalnianie miejsca

Uczestnicy kursu na Kaggle: jeśli wykonujesz te ćwiczenia w ramach kursu 5-dniowy kurs agentów AI na Kaggle i planujesz przejść do następnych ćwiczeń (Vibecode i wdrażanie frontendu dla agenta ADK), aby utworzyć klienta frontendu i integrację Pub/Sub, nie usuwaj wdrożonego agenta. Będziesz potrzebować tej aktywnej infrastruktury w chmurze do następnych ćwiczeń.

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, po zakończeniu musisz wyłączyć i zwolnić miejsce w wdrożonych zasobach.

👉 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.

Gdy Antigravity wykona ten prompt, zautomatyzuje cały proces czyszczenia zasobów:

1. Usuwanie wdrożonego agenta: odczytuje deployment_metadata.json, aby uzyskać zdalny identyfikator środowiska wykonawczego agentów, a następnie programowo usuwa instancję silnika na żywo z Vertex AI.
2. Zwalnianie miejsca w lokalnym obszarze roboczym: usuwa nieaktualny plik deployment_metadata.json z katalogu głównego projektu.
3. Czyszczenie Artifact Registry: wykonuje polecenie gcloud artifacts docker images delete, aby usunąć utworzone obrazy kontenerów z Artifact Registry, co zwalnia miejsce na dane w chmurze.

12. Gratulacje

Gratulacje! Udało Ci się wdrożyć i zweryfikować agenta do obsługi wydatków klasy produkcyjnej w Google Cloud.

Czego się nauczysz

• Konfigurowanie Google Cloud: skonfigurowano dane logowania do projektu i włączono wymagane interfejsy API platformy.
• Narzędzia i umiejętności: zainstalowano agents-cli i załadowano umiejętności towarzyszące ADK do Antigravity.
• Scaffolding produkcyjne: wygenerowano scaffolding środowiska Agent Runtime dla agenta ADK 2.0.
• Weryfikacja lokalna: utworzono deterministyczne pliki blokady (uv lock) i wykonano testy.
• Wdrożenie w chmurze: hostowano agenta na żywo w zarządzanej infrastrukturze Agent Runtime.
• Dostrzegalność i analityka: śledzono wykonanie w Cloud Trace i analizowano dane telemetryczne w BigQuery.
• Wykrywanie w przedsiębiorstwie: sprawdzono automatyczną rejestrację w rejestrze agentów w przedsiębiorstwie.

Co dalej?

• Przeprowadzanie analizy w BigQuery: wysyłaj zapytania do logów telemetrycznych agenta w BigQuery, aby analizować współczynniki zatwierdzeń i trendy w turach rozmowy w czasie.
• Ćwiczenia z Vibecode i wdrażania frontendu: użyj Google Antigravity, aby utworzyć klienta frontendu w Cloud Run i połączyć go bezpośrednio z punktem końcowym backendu środowiska wykonawczego agentów na żywo.

Otrzymaj plakietkę 5-dniowego kursu agentów AI na Kaggle 🎉

Czy te ćwiczenia są częścią 5-dniowego intensywnego kursu programowania agentów AI z użyciem Vibecode i Google na Kaggle? Odbierz plakietkę potwierdzającą ukończenie:

Otrzymaj plakietkę 5-dniowego kursu agentów AI

Odniesienia

• Dokumentacja pakietu Agent Development Kit (ADK)
• Środowiska wykonawcze Gemini Enterprise Agent Platform
• Przewodnik po interfejsie wiersza poleceń agentów (agents-cli)
• Omówienie rejestru agentów Gemini Enterprise
• Dokumentacja Google Cloud Trace