1. Pengantar
Ringkasan
Lab ini menunjukkan cara menerapkan pemanggilan berbasis peristiwa agen ADK yang di-deploy di Cloud Run secara aman menggunakan layanan Eventarc dan Pub/Sub. Agen biasanya dipanggil langsung oleh pengguna atau agen lain. Namun, saat agen diintegrasikan ke dalam alur kerja berbasis peristiwa yang ada, melakukan panggilan langsung memerlukan perubahan pada software yang ada. Memicu pemanggilan agen berdasarkan peristiwa memungkinkan penggabungan agen ke dalam alur kerja yang ada tanpa mengubah alur kerja.
Yang akan Anda lakukan
Di lab ini, Anda akan membuat aplikasi agentik ZooKeeper yang memiliki agen AI dan menggunakan beberapa alat untuk memberikan informasi tentang hewan di kebun binatang imajiner.
Anda akan men-deploy aplikasi ZooKeeper sebagai layanan ke Cloud Run, yang merupakan platform komputasi serverless terkelola sepenuhnya yang menjalankan container stateless di infrastruktur Google. Kemudian, Anda akan menyiapkan pemicu Eventarc yang akan memanggil endpoint layanan untuk menangani pesan yang dipublikasikan ke topik Pub/Sub secara asinkron. Anda akan memastikan bahwa deployment mengikuti praktik terbaik, termasuk menggunakan akun layanan IAM yang ditetapkan, memberikan akses dengan hak istimewa terendah, dan meminimalkan potensi permukaan serangan dengan hanya mengekspos endpoint aplikasi ZooKeeper ke Eventarc. Anda akan melakukannya dengan bantuan Cloud Shell dan konsol Cloud. Anda akan menggunakan library ADK dan Cloud SDK untuk Python. Untuk memeriksa perilaku, Anda akan menggunakan gcloud CLI.
Yang akan Anda pelajari
- Deploy agen ADK Anda ke Google Cloud Run.
- Integrasikan pemicu Eventarc dengan agen ADK yang berjalan di Google Cloud Run.
- Amankan deployment dan integrasi Anda dengan Eventarc menggunakan prinsip akses hak istimewa terendah dengan bantuan Google Cloud IAM.
- Memublikasikan dan menarik pesan ke dan dari Pub/Sub.
- Minimalkan eksposur publik aplikasi Anda yang di-deploy ke Google Cloud Run.
Yang Anda butuhkan
- Browser web Chrome †
- Akun Google pribadi ‡
- Project Google Cloud yang ditautkan ke akun penagihan aktif
Perhatikan bahwa akun Anda harus memiliki akses IAM ke project yang memungkinkan Anda menyediakan resource dan mengonfigurasi akses IAM ke resource ini.
† Pengalaman pengguna saat menggunakan browser lain mungkin berbeda dengan yang dijelaskan di lab.
‡ Penggunaan akun perusahaan atau sekolah mungkin terbatas dalam melakukan beberapa operasi yang dijelaskan dalam lab.
2. Penyiapan lingkungan
Untuk memastikan lingkungan pengembangan yang berfungsi penuh untuk lab, Anda akan menggunakan Google Cloud Shell yang telah menginstal semua alat yang diperlukan sebelumnya. Ikuti petunjuk untuk menyiapkan lingkungan.
Jika Anda tidak memiliki Akun Google, buat Akun Google.
Petunjuk penyiapan
- Gunakan Akun Google Anda untuk login ke Konsol Google Cloud.
- 👉 Buka pemilih project di panel navigasi atas (mungkin bertuliskan "Pilih project" atau menampilkan nama project yang ada) atau klik pintasan keyboard
Ctrl+Odan pilih project yang ada atau buat project baru.Pembuatan project baru akan memerlukan waktu beberapa detik. Tunggu hingga project siap dan pilih menggunakan pemilih project.
- 👉 Klik ikon Cloud Shell di bagian atas konsol Google Cloud. (ditandai dengan persegi panjang merah):
Jika diminta, klik **Authorize** di kotak dialog pop-up untuk menyetujui Cloud Shell menggunakan kredensial akun Anda.
- 👉💻 Pastikan gcloud CLI dikonfigurasi untuk menggunakan project yang Anda pilih (atau buat). Jalankan perintah berikut untuk memeriksa project ID yang dikonfigurasi:
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]adalah ID project yang Anda pilih atau buat.👉💻 Jika Anda melihat nilai lain, jalankan perintah berikut untuk mengonfigurasi ID project Anda sebagai ID project default untuk perintah 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'
- 👉💻 Siapkan lokasi untuk penyediaan resource serta ID dan nomor project Anda dalam variabel lingkungan:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Aktifkan Google API yang diperlukan untuk lab ini.
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. Men-deploy aplikasi demo ZooKeeper
Langkah-langkah berikut menyediakan dan mengonfigurasi resource, termasuk deployment aplikasi AI agentik.
Menyiapkan resource Pub/Sub
Anda akan membuat dua topik Pub/Sub. Salah satunya akan digunakan oleh layanan pihak ketiga untuk mengirim peristiwa ke aplikasi AI agentik Anda. Satu lagi untuk aplikasi memublikasikan hasil pemrosesan peristiwa.
- 👉💻 Buat topik Pub/Sub yang digunakan untuk memicu aplikasi AI agentik:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Buat topik Pub/Sub tempat aplikasi dapat memposting responsnya:
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
Menyiapkan akun layanan dan kebijakan IAM tingkat project
Anda akan membuat dua akun layanan untuk membatasi cakupan akses layanan Cloud Run dan pemicu Eventarc ke minimum dengan mengikuti prinsip akses hak istimewa terendah. Layanan Cloud Run memerlukan izin untuk menulis log dan rekaman aktivitas, memanggil LLM Gemini di Google Vertex AI, dan memposting hasil ke topik Pub/Sub. Akses minimum pemicu Eventarc memerlukan izin untuk memanggil layanan ZooKeeper Cloud Run dan mengakses Pub/Sub untuk membaca peristiwa yang diposting. Petunjuk ini memandu Anda memberikan izin yang diperlukan kepada akun layanan pemicu untuk meniru identitas layanan sistem Pub/Sub. Setelah membuat resource pemicu Eventarc, Anda akan menjalankan perintah yang memberikan peran roles/run.invoker untuk mengizinkan akun layanan pemicu memanggil layanan Cloud Run.
- 👉💻 Buat akun layanan untuk layanan Cloud Run:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Beri akun layanan izin untuk menulis log dan rekaman aktivitas serta menggunakan model Gemini di 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 - 👉💻 Beri akun layanan izin untuk memposting pesan ke topik 'agent_responses':
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Buat akun layanan untuk pemicu Eventarc:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Beri akun layanan sistem Pub/Sub izin untuk membuat permintaan push yang diautentikasi:
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"
Men-deploy aplikasi ZooKeeper ke Cloud Run
Anda akan mendownload kode aplikasi demo dari GitHub. Lalu, deploy kode ke Cloud Run.
- 👉💻 Download aplikasi AI agentic:
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/ - 👉💻 Deploy aplikasi AI agentic ke 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}"
Mengonfigurasi pemicu Eventarc
Setelah menyiapkan semua resource (topik Pub/Sub, akun layanan IAM, dan layanan Cloud Run), saatnya menyiapkan resource pemicu Eventarc. Anda akan membuat resource pemicu Eventarc dan memberikan izin untuk memanggil layanan Cloud Run ke akun layanan pemicu.
- 👉💻 Buat pemicu 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}" - 👉💻 Beri izin ke akun layanan pemicu untuk memanggil layanan Cloud Run:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Meninjau cara kerja solusi
Sekarang tinjau apa yang baru saja Anda deploy. Diagram berikut mencerminkan semua resource dan cara berinteraksinya satu sama lain. Anda akan menggunakan gcloud CLI untuk memublikasikan pesan ke topik 'invoke_agent'. Tindakan ini akan menyimulasikan peristiwa yang dicatat oleh layanan pihak ketiga ke layanan pesan untuk memanggil aplikasi AI agentik.
Deployment diamankan dengan mengikuti akses hak istimewa terendah. Layanan Cloud Run menerapkan autentikasi (lihat argumen --no-allow-unauthenticated di langkah #9 di bagian sebelumnya). Hanya identitas dengan peran/run.invoker atau izin serupa yang dapat memanggil layanan. Peran ini hanya diberikan ke akun layanan pemicu Eventarc. Demikian pula, akses ke topik 'invoke_agent' diminimalkan untuk melarang publikasi peristiwa tanpa izin. Agen ZooKeeper masih dapat dipanggil secara langsung dengan melewati postingan ke topik Pub/Sub. Lihat bagian 6 untuk mempelajari cara menyembunyikan endpoint aplikasi dari akses publik.
Jalankan alur kerja
Anda akan meniru peristiwa eksternal dengan memublikasikan pertanyaan dalam bahasa alami ke ZooKeeper.
👉💻 Gunakan perintah berikut untuk memposting pesan ke topik Pub/Sub:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
Pada kenyataannya, informasi acara mungkin memiliki bentuk yang kurang mudah dibaca. Untuk memprosesnya, aplikasi AI agentik akan memerlukan petunjuk mendetail mengenai format acara, data, dan tindakan yang harus dilakukan agen dengan informasi acara tersebut.
Anda dapat memeriksa apakah agen menerima peristiwa, memproses permintaan, dan memposting respons ke topik 'agent_responses'. Untuk membaca respons, Anda akan menggunakan langganan 'agent_responses' (codelab menggunakan ID yang sama untuk topik dan langganan respons).
👉💻 Gunakan perintah berikut untuk membaca respons agen dari langganan Pub/Sub:
gcloud pubsub subscriptions pull agent_responses --auto-ack
Output akan mencetak tabel dengan metadata pesan dan payload yang berisi jawaban bahwa ada 33 spesies di kebun binatang. Flag --auto-ack otomatis mengonfirmasi pesan setelah ditarik, sehingga tidak akan dikirimkan lagi.
Cara kerjanya
Lihat kode sumber aplikasi AI agentik dengan membuka Cloud Shell Editor dan melihat file di folder ~/zoo-keeper-lab. Anda juga dapat melihat kode sumber di GitHub.
- main.py menerapkan aplikasi web FastAPI dasar dengan satu pengendali yang memproses peristiwa Eventarc.
- processor.py mengurai pesan peristiwa untuk mengambil ID pengguna dan permintaan. Kemudian, ADK runner akan membuat sesi baru dan memanggil agen Zookeeper untuk memproses permintaan. Respons dari agen diposting ke topik Pub/Sub 'agent_responses'.
- Subfolder zookeeper_agent menghosting kode sumber agen ADK. Anda dapat menjalankan perintah
adk run zookeeper_agentdari folder root aplikasi untuk berinteraksi dengan agen menggunakan adk CLI.
Cara memecahkan masalah
Jika salah satu perintah sebelumnya gagal, baca pesan error dengan cermat. Jika deployment ke Cloud Run gagal, langkah pertama adalah menentukan pada tahap proses mana kegagalan terjadi.
- Jika output perintah "gcloud run deploy..." melaporkan bahwa build gagal, lihat URL log build di output dan buka di jendela terpisah.
- Jika output menampilkan pesan seperti "service failed to start" atau yang serupa, artinya layanan di-deploy, tetapi kemudian gagal dalam pemeriksaan kondisi. Dalam hal ini, buka Logs Explorer atau lihat paragraf berikut untuk perintah gcloud CLI. Baca log untuk menemukan penyebab utama kegagalan.
Bagaimana jika Anda memposting pesan ke Pub/Sub, tetapi agen tidak merespons atau responsnya terlihat aneh?
👉💻 Gunakan perintah berikut untuk membaca log aplikasi yang diposting dari eksekusi terbaru:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
Log melacak eksekusi dan melaporkan error seperti payload pesan yang salah atau tidak dapat diuraikan, respons tidak valid dari model Gemini, setelan lingkungan yang tidak valid, dan kemungkinan masalah lainnya.
5. Memperketat keamanan deployment
Layanan Cloud Run yang Anda deploy mengekspos endpoint publik yang dapat dipanggil oleh siapa saja di internet. Meskipun endpoint dilindungi dari pemanggilan yang tidak sah dan memvalidasi struktur permintaan secara ketat, endpoint masih meninggalkan vektor serangan ini yang memungkinkan serangan penolakan layanan dan penolakan dompet. Karena satu-satunya jalur pemanggilan untuk layanan dalam desain saat ini adalah melalui pemicu Eventarc, layanan tidak perlu mengekspos endpointnya ke internet.
👉💻 Tutup vektor serangan ini dengan membatasi panggilan ke layanan agar hanya berasal dari kumpulan sumber terbatas, termasuk pemicu Eventarc:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Sekarang, jika Anda mencoba memanggil URL layanan dari mesin lokal, Anda akan mendapatkan error "404 Page not found".
👉💻 Gunakan curl untuk mengirim permintaan ke endpoint layanan:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Anda akan melihat output yang mirip dengan berikut ini:
<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>
Setelah perubahan ini, ZooKeeper tidak dapat lagi dipanggil secara langsung dengan memanggil endpoint layanan Cloud Run, kecuali jika Anda melakukan panggilan dari VPC dalam project yang sama, jaringan VPC Bersama yang revisinya dikonfigurasi untuk mengirim traffic ke atau host yang merupakan bagian dari perimeter Kontrol Layanan VPC.
6. Ringkasan
Selamat! Anda telah berhasil menyiapkan lingkungan untuk memanggil aplikasi AI agentik secara asinkron yang dipicu oleh peristiwa masuk.
Pembersihan
Perhatikan bahwa mempertahankan resource yang Anda sediakan dapat menimbulkan biaya pada akun penagihan Anda. Jika Anda tidak berencana menggunakan lingkungan ini untuk eksperimen lainnya dan untuk menghindari biaya mendatang, sebaiknya hapus resource yang dibuat selama codelab ini.
Ada dua metode untuk melakukannya:
Metode 1: Menutup project
Menonaktifkan (menghapus) project akan melepaskan semua resource dan data project serta membatalkan tautan akun penagihan. Dengan menggunakan metode ini, biaya lebih lanjut tidak akan dikenakan untuk resource atau data apa pun yang digunakan untuk codelab ini. Gunakan perintah berikut untuk mematikan project:
gcloud projects delete $(gcloud config get-value project) --quiet
Metode 2: Menghapus resource dalam project
Menghapus layanan Cloud Run akan melindungi Anda dari biaya lebih lanjut untuk penggunaan platform serverless. Perhatikan bahwa metode ini tidak sepenuhnya menghapus semua data yang dihasilkan selama codelab seperti log aplikasi dan Cloud Build, image container, dll. Jalankan perintah berikut untuk menghapus layanan:
gcloud run services delete zookeeper-agent --region=${LOCATION}
Definisi pemicu Eventarc dan topik Pub/Sub tidak menimbulkan biaya pengelolaan (lihat harga Eventarc dan harga Pub/Sub untuk mengetahui detail selengkapnya).
Pelajari lebih lanjut cara menghentikan project.
Langkah berikutnya
- Pelajari kode lebih lanjut dengan meninjau demo di GitHub.
- Meninjau arsitektur yang mengatur akses ke sistem perusahaan yang berbeda-beda
- Pelajari cara memicu Cloud Run menggunakan pemicu Eventarc
- Pelajari ADK lebih lanjut