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.
Wdrożysz aplikację ZooKeeper jako usługę w Cloud Run, czyli w pełni zarządzanej platformie obliczeniowej bez serwera, 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 o najmniejszych uprawnieniach 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 Cloud. Będziesz używać bibliotek ADK i (pakiet) SDK Cloud 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ń 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 laboratorium.
2. Konfigurowanie środowiska
Aby zapewnić w module w pełni funkcjonalne środowisko programistyczne, użyjesz 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 konsoli Google Cloud 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. (oznaczone 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 agentowej aplikacji AI.
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 agentowej AI. Drugi do publikowania przez aplikację wyników przetwarzania zdarzeń.
- 👉💻 Utwórz temat Pub/Sub, który będzie używany do wywoływania aplikacji agentowej AI:
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ługi 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 systemową usługę 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 korzystania z 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ę agentowej AI:
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ę agentowej AI 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 przedstawia wszystkie zasoby i sposoby ich wzajemnego oddziaływania. 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 do przesyłania wiadomości, aby wywołać aplikację agentowej AI.
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 agentowa AI musi mieć szczegółowe instrukcje dotyczące formatu zdarzenia, danych i tego, co agent powinien zrobić z informacjami o zdarzeniu.
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 Codelabs 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 gatunków zwierząt. Flaga --auto-ack automatycznie potwierdza odbiór wiadomości po jej pobraniu, więc nie zostanie ona ponownie dostarczona.
Jak to działa
Wyświetl kod źródłowy aplikacji agentowej AI, otwierając edytor Cloud Shell i wyświetlając 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 1 procedurą obsługi, która 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 ADK CLI, możesz uruchomić polecenie
adk run zookeeper_agentw folderze głównym aplikacji.
Jak rozwiązać problem
Jeśli któreś z poprzednich poleceń się nie powiedzie, dokładnie przeczytaj komunikat o błędzie. Jeśli wdrożenie w Cloud Run się nie powiedzie, pierwszym krokiem będzie ustalenie, na którym etapie procesu wystąpił problem.
- 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 w wyniku pojawi się komunikat w stylu „nie udało się uruchomić usługi”, 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ć logi 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. Punkt końcowy jest chroniony przed nieautoryzowanym wywołaniem i dokładnie weryfikuje strukturę żądania, ale 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ć ZooKeepera 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, ze współdzielonego środowiska VPC, do którego Twoja wersja jest skonfigurowana do wysyłania ruchu, lub z hosta, który jest częścią Ustawień usługi VPC.
6. Podsumowanie
Gratulacje! Udało Ci się skonfigurować środowisko do asynchronicznego wywoływania aplikacji agentowej AI, 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 przeprowadzania kolejnych eksperymentów i chcesz uniknąć przyszłych opłat, zalecamy usunięcie zasobów utworzonych w ramach tego laboratorium.
Możesz to zrobić na 2 sposoby:
Metoda 1. Wyłączanie 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 wyłączyć 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 ćwiczeń, 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