1. Wprowadzenie
Przegląd
W tym module dowiesz się, jak bezpiecznie wdrożyć wywoływanie oparte na zdarzeniach agenta ADK wdrożonego w Cloud Run za pomocą usług Eventarc i Pub/Sub. Najczęściej agent jest wywoływany bezpośrednio przez użytkownika lub innego agenta. Gdy jednak agent jest integrowany z istniejącymi przepływami pracy opartymi na zdarzeniach, bezpośrednie wywołanie wymaga zmian w dotychczasowym oprogramowaniu. Wywoływanie agenta na podstawie zdarzenia umożliwia włączenie agenta do istniejących przepływów pracy bez wprowadzania w nich zmian.
Jakie zadania wykonasz
W tym module utworzysz aplikację agentową ZooKeeper z agentem AI, która korzysta z kilku narzędzi do dostarczania informacji o zwierzętach w fikcyjnym zoo.
Aplikację ZooKeeper wdrożysz jako usługę w Cloud Run, czyli w pełni zarządzanej platformie obliczeniowej bezserwerowej, która uruchamia bezstanowe kontenery w infrastrukturze Google. Następnie skonfigurujesz aktywator Eventarc, który będzie wywoływać punkt końcowy usługi, aby asynchronicznie obsługiwać wiadomości publikowane w temacie Pub/Sub. Zadbaj o to, aby wdrożenie było zgodne ze sprawdzonymi metodami, w tym używaj wyznaczonych kont usługi IAM, przyznawaj dostęp z najmniejszymi uprawnieniami i minimalizuj potencjalną powierzchnię ataku, udostępniając punkt końcowy aplikacji ZooKeeper tylko usłudze Eventarc. Zrobisz to za pomocą Cloud Shell i konsoli Google Cloud. Będziesz używać bibliotek ADK i Cloud SDK dla Pythona. Aby sprawdzić to zachowanie, użyj interfejsu wiersza poleceń gcloud.
Czego się nauczysz
- Wdróż agenta ADK w Google Cloud Run.
- Zintegruj aktywator Eventarc z agentem ADK działającym w Google Cloud Run.
- Zabezpiecz wdrożenie i integrację z Eventarc, stosując zasadę jak najmniejszych uprawnień dostępu za pomocą Google Cloud IAM.
- publikować i pobierać wiadomości w Pub/Sub.
- Ogranicz publiczną ekspozycję aplikacji wdrożonej w Google Cloud Run.
Czego potrzebujesz
- Przeglądarka Chrome†
- Osobiste konto Google‡
- projekt Google Cloud połączony z aktywnym kontem rozliczeniowym;
Pamiętaj, że Twoje konto musi mieć dostęp do uprawnień w projekcie, który umożliwia udostępnianie zasobów i konfigurowanie dostępu do nich.
† Wrażenia użytkownika korzystającego z innych przeglądarek mogą się różnić od tych opisanych w laboratorium.
‡ Korzystanie z konta firmowego lub szkolnego może ograniczać możliwość wykonywania niektórych operacji opisanych w tym module.
2. Konfigurowanie środowiska
Aby zapewnić w tym module w pełni funkcjonalne środowisko programistyczne, użyjemy Google Cloud Shell, które ma wstępnie zainstalowane wszystkie niezbędne narzędzia. Postępuj zgodnie z instrukcjami, aby skonfigurować środowisko.
Jeśli nie masz konta Google, utwórz je.
Instrukcje konfiguracji
- Zaloguj się w Google Cloud Console za pomocą konta Google.
- 👉 Otwórz selektor projektów na górnym pasku nawigacyjnym (może wyświetlać komunikat „Wybierz projekt” lub nazwę istniejącego projektu) albo kliknij skrót klawiszowy
Ctrl+Oi wybierz istniejący projekt lub utwórz nowy.Utworzenie nowego projektu zajmie kilka sekund. Poczekaj, aż będzie gotowy, i wybierz go za pomocą selektora projektów.
- 👉 U góry konsoli Google Cloud kliknij ikonę Cloud Shell. (oznaczony czerwonym prostokątem):
jeśli pojawi się prośba, kliknij **Autoryzuj** w wyskakującym okienku, aby zezwolić Cloud Shell na używanie danych logowania Twojego konta.
- 👉💻 Sprawdź, czy interfejs wiersza poleceń gcloud jest skonfigurowany do korzystania z wybranego (lub utworzonego) projektu. Aby sprawdzić skonfigurowany identyfikator projektu, uruchom to polecenie:
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]to identyfikator wybranego lub utworzonego projektu.👉💻 Jeśli widzisz inną wartość, uruchom to polecenie, aby skonfigurować identyfikator projektu jako domyślny identyfikator projektu dla poleceń gcloud CLI:gcloud config set project [YOUR_PROJECT_ID]gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 Skonfiguruj lokalizację, w której będą udostępniane zasoby, oraz identyfikator i numer projektu w zmiennych środowiskowych:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Włącz interfejsy API Google wymagane w tym laboratorium.
gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
3. Wdrażanie przykładowej aplikacji ZooKeeper
Poniższe kroki umożliwiają udostępnienie i skonfigurowanie zasobów, w tym wdrożenie aplikacji AI opartej na agentach.
Konfigurowanie zasobów Pub/Sub
Utworzysz 2 tematy Pub/Sub. Jeden będzie używany przez usługę zewnętrzną do wysyłania zdarzeń do aplikacji AI opartej na agentach. Drugi do publikowania przez aplikację wyników przetwarzania zdarzeń.
- 👉💻 Utwórz temat Pub/Sub, który będzie używany do wywoływania aplikacji AI opartej na agentach:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Utwórz temat Pub/Sub, w którym aplikacja może publikować odpowiedzi:
gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
Konfigurowanie kont usług i zasad uprawnień na poziomie projektu
Utworzysz 2 konta usługi, aby ograniczyć zakres dostępu usługi Cloud Run i wyzwalacza Eventarc do minimum zgodnie z zasadą jak najmniejszych uprawnień. Usługa Cloud Run wymaga uprawnień do zapisywania logów i śladów, wywoływania modelu LLM Gemini w Google Vertex AI oraz publikowania wyników w temacie Pub/Sub. Minimalny dostęp wyzwalacza Eventarc wymaga uprawnień do wywoływania usługi Cloud Run ZooKeeper i dostępu do Pub/Sub w celu odczytywania opublikowanych zdarzeń. Te instrukcje pomogą Ci przyznać kontu usługi wywołania uprawnienia niezbędne do podawania się za usługę systemową Pub/Sub. Po utworzeniu zasobu aktywatora Eventarc uruchom polecenie, które przyznaje rolę roles/run.invoker, aby umożliwić kontu usługi aktywatora wywoływanie usługi Cloud Run.
- 👉💻 Utwórz konto usługi dla usługi Cloud Run:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Przyznaj kontu usługi uprawnienia do zapisywania logów i śladów oraz używania modeli Gemini w Vertex AI:
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 Przyznaj kontu usługi uprawnienia do publikowania wiadomości w temacie „agent_responses”:
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Utwórz konto usługi dla aktywatora Eventarc:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Przyznaj systemowemu kontu usługi Pub/Sub uprawnienia do wysyłania uwierzytelnionych żądań push:
gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
Wdrażanie aplikacji ZooKeeper w Cloud Run
Kod aplikacji demonstracyjnej pobierzesz z GitHub. i wdrożyć kod w Cloud Run.
- 👉💻 Pobierz aplikację AI opartą na agentach:
mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 Wdróż aplikację AI opartą na agentach w Cloud Run:
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
Konfigurowanie aktywatora Eventarc
Po przygotowaniu wszystkich zasobów (tematów Pub/Sub, kont usługi IAM i usługi Cloud Run) możesz skonfigurować zasób aktywatora Eventarc. Utworzysz zasób aktywatora Eventarc i przyznasz uprawnienia do wywoływania usługi Cloud Run na koncie usługi aktywatora.
- 👉💻 Utwórz aktywator Eventarc:
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 Przyznaj uprawnienia kontu usługi aktywatora do wywoływania usługi Cloud Run:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Sprawdź, jak działa rozwiązanie
Sprawdź teraz, co zostało wdrożone. Ten diagram pokazuje wszystkie zasoby i ich wzajemne interakcje. Za pomocą interfejsu wiersza poleceń gcloud opublikujesz wiadomość w temacie „invoke_agent”. Symuluje to zdarzenie, które usługa innej firmy rejestruje w usłudze przesyłania wiadomości, aby wywołać aplikację AI opartą na agentach.
Wdrożenie jest zabezpieczone zgodnie z zasadą jak najmniejszych uprawnień. Usługa Cloud Run wymusza uwierzytelnianie (patrz argument --no-allow-unauthenticated w kroku 9 w poprzedniej sekcji). Usługę mogą wywoływać tylko tożsamości z rolą roles/run.invoker lub podobnymi uprawnieniami. Ta rola jest przyznawana tylko kontu usługi wyzwalacza Eventarc. Podobnie dostęp do tematu „invoke_agent” jest ograniczony do minimum, aby uniemożliwić nieautoryzowane publikowanie zdarzeń. Nadal można wywoływać agenta ZooKeepera bezpośrednio, pomijając publikowanie w temacie Pub/Sub. W sekcji 6 dowiesz się, jak ukryć punkt końcowy aplikacji przed dostępem publicznym.
Uruchamianie przepływu pracy
Będziesz symulować zdarzenie zewnętrzne, publikując w ZooKeeper pytanie w języku naturalnym.
👉💻 Aby opublikować wiadomość w temacie Pub/Sub, użyj tego polecenia:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
W rzeczywistości informacje o wydarzeniu będą prawdopodobnie mniej czytelne. Aby je przetworzyć, aplikacja AI oparta na agentach musi mieć szczegółowe instrukcje dotyczące formatu wydarzenia, danych i tego, co agent powinien zrobić z informacjami o wydarzeniu.
Możesz sprawdzić, czy agent otrzymał zdarzenie, przetworzył żądanie i opublikował odpowiedź w temacie „agent_responses”. Aby odczytać odpowiedź, użyjesz subskrypcji „agent_responses” (w tym samouczku używamy tego samego identyfikatora zarówno w przypadku tematu, jak i subskrypcji odpowiedzi).
👉💻 Aby odczytać odpowiedź agenta z subskrypcji Pub/Sub, użyj tego polecenia:
gcloud pubsub subscriptions pull agent_responses --auto-ack
Dane wyjściowe będą zawierać tabelę z metadanymi wiadomości i ładunkiem zawierającym odpowiedź, że w zoo jest 33 gatunki zwierząt. Flaga --auto-ack automatycznie potwierdza wiadomość po jej pobraniu, więc nie zostanie ona ponownie dostarczona.
Jak to działa
Aby wyświetlić kod źródłowy aplikacji AI opartej na agentach, otwórz edytor Cloud Shell i wyświetl pliki w folderze ~/zoo-keeper-lab. Kod źródłowy możesz też wyświetlić na GitHub.
- Plik main.py zawiera podstawową aplikację internetową FastAPI z jednym modułem obsługi, który przetwarza zdarzenia Eventarc.
- Plik processor.py analizuje wiadomość zdarzenia, aby pobrać identyfikator użytkownika i żądanie. Następnie tworzy nową sesję w programie uruchamiającym ADK i wywołuje agenta Zookeepera, aby przetworzyć żądanie. Odpowiedź agenta jest publikowana w temacie Pub/Sub „agent_responses”.
- W podfolderze zookeeper_agent znajduje się kod źródłowy agenta pakietu ADK. Aby korzystać z agenta za pomocą interfejsu wiersza poleceń ADK, możesz uruchomić polecenie
adk run zookeeper_agentw folderze głównym aplikacji.
Jak go rozwiązać
Jeśli któreś z poprzednich poleceń się nie powiedzie, dokładnie przeczytaj komunikat o błędzie. Jeśli wdrożenie w Cloud Run nie powiedzie się, pierwszym krokiem będzie ustalenie, na którym etapie procesu wystąpił błąd.
- Jeśli dane wyjściowe polecenia „gcloud run deploy...” wskazują, że kompilacja nie powiodła się, w danych wyjściowych znajdź adres URL dzienników kompilacji i otwórz go w osobnym oknie.
- Jeśli dane wyjściowe zawierają komunikat „service failed to start” (nie udało się uruchomić usługi) lub podobny, oznacza to, że usługa została wdrożona, ale jej wykonanie nie przeszło testu stanu. W takim przypadku otwórz eksplorator logów lub zapoznaj się z poleceniem gcloud CLI w następnym akapicie. Przejrzyj logi, aby znaleźć główną przyczynę niepowodzenia.
Co zrobić, jeśli opublikujesz wiadomość w Pub/Sub, ale agent nie odpowie lub odpowiedź będzie wyglądać dziwnie?
👉💻 Aby odczytać dzienniki aplikacji opublikowane podczas ostatniego wykonania, użyj tego polecenia:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
Dzienniki śledzą wykonanie i zgłaszają błędy, takie jak nieprawidłowy lub nieczytelny ładunek wiadomości, nieprawidłowa odpowiedź modelu Gemini, nieprawidłowe ustawienia środowiska i inne możliwe problemy.
5. Wzmacnianie zabezpieczeń wdrożenia
Wdrożona usługa Cloud Run udostępnia publiczny punkt końcowy, który może być wywoływany przez każdego użytkownika internetu. Chociaż punkt końcowy jest chroniony przed nieautoryzowanym wywołaniem i dokładnie weryfikuje strukturę żądania, nadal pozostawia ten wektor ataku, który umożliwia ataki typu DoS i DoW. Ponieważ jedyna ścieżka wywołania usługi w obecnej architekturze prowadzi przez aktywator Eventarc, usługa nie musi udostępniać swojego punktu końcowego w internecie.
👉💻 Zamknij ten wektor ataku, ograniczając wywołania usługi tylko do ograniczonej kolekcji źródeł, w tym aktywatorów Eventarc:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Jeśli teraz spróbujesz wywołać adres URL usługi na komputerze lokalnym, pojawi się błąd „404 – nie znaleziono strony”.
👉💻 Użyj polecenia curl, aby wysłać żądanie do punktu końcowego usługi:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Zobaczysz dane wyjściowe podobne do tych:
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
Po tej zmianie nie będzie już można wywoływać usługi ZooKeeper bezpośrednio przez wywołanie punktu końcowego usługi Cloud Run, chyba że wywołanie zostanie wykonane z sieci VPC w tym samym projekcie, sieci VPC współdzielonej, do której Twoja wersja jest skonfigurowana do wysyłania ruchu, lub hosta, który jest częścią obszaru usługi VPC.
6. Podsumowanie
Gratulacje! Udało Ci się skonfigurować środowisko do asynchronicznego wywoływania aplikacji AI opartej na agentach, która jest aktywowana przez przychodzące zdarzenia.
Czyszczenie danych
Pamiętaj, że zachowanie udostępnionych zasobów może wiązać się z opłatami na koncie rozliczeniowym. Jeśli nie planujesz używać tego środowiska do kolejnych eksperymentów i chcesz uniknąć przyszłych opłat, zalecamy usunięcie zasobów utworzonych podczas tego ćwiczenia z programowania.
Możesz to zrobić na 2 sposoby:
Metoda 1. Zamknięcie projektu
Zamknięcie (usunięcie) projektu powoduje zwolnienie wszystkich jego zasobów i danych oraz odłączenie konta rozliczeniowego. Dzięki temu unikniesz dalszych opłat za zasoby lub dane użyte w tym samouczku. Aby zamknąć projekt, użyj tego polecenia:
gcloud projects delete $(gcloud config get-value project) --quiet
Metoda 2: usuwanie zasobów w projekcie
Usunięcie usługi Cloud Run chroni przed dalszymi opłatami za korzystanie z platformy bezserwerowej. Pamiętaj, że ta metoda nie usuwa całkowicie wszystkich danych wygenerowanych podczas ćwiczenia, takich jak dzienniki Cloud Build i aplikacji, obrazy kontenerów itp. Aby usunąć usługę, uruchom to polecenie:
gcloud run services delete zookeeper-agent --region=${LOCATION}
Definicja aktywatora Eventarc i tematy Pub/Sub nie generują kosztów zarządzania (więcej informacji znajdziesz w cenniku Eventarc i cenniku Pub/Sub).
Dowiedz się więcej o wyłączaniu projektu.
Co dalej?
- Więcej informacji o kodzie znajdziesz w wersji demonstracyjnej na GitHub.
- Zapoznaj się z architekturą, która koordynuje dostęp do różnych systemów przedsiębiorstwa
- Dowiedz się, jak aktywować Cloud Run za pomocą aktywatorów Eventarc.
- Więcej informacji o ADK