Men-deploy agen ADK ke Agent Runtime menggunakan Agents CLI

1. Ringkasan

Lab ini adalah bagian dari 5-Day AI Agents: Intensive Vibe Coding Course with Google di Kaggle. Anda dapat menemukan codelab dan resource tambahan yang tersedia di situs acara.

Dalam codelab ini, Anda akan mentransisikan agen ADK 2.0 dari lingkungan pengembangan lokal ke deployment tingkat produksi. Anda akan menggunakan agents-cli untuk mengemas, memverifikasi, dan menghosting alur kerja berbasis grafik secara langsung di Agent Runtime di Google Cloud.

Untuk mempelajari proses deployment ini, Anda akan membuat prototipe lokal Ambient Expense Agent dari awal sebelum men-deploy-nya ke cloud. (Untuk mempelajari lebih lanjut cara mendesain logika inti agen ini, lihat codelab dasar di situs acara Kaggle). Ambient Expense Agent menyederhanakan pelaporan pengeluaran karyawan dengan langsung menyetujui klaim standar sekaligus menandai pengeluaran yang lebih besar untuk ditinjau oleh manusia. Di balik layar, layanan ini menggunakan alur kerja berbasis grafik ADK 2.0 untuk mengoordinasikan langkah-langkah persetujuan otomatis dan analisis risiko ini.

Yang akan Anda pelajari

• Cara menyiapkan project Ambient Expense Agent lokal untuk hosting cloud.
• Cara membuat kerangka deskriptor deployment dan wrapper produksi yang diperlukan.
• Cara melakukan uji coba dan men-deploy kode langsung ke Agent Runtime.
• Cara memantau trace eksekusi agen produksi menggunakan Cloud Trace.

Yang akan Anda butuhkan

• Project Google Cloud aktif dengan penagihan yang diaktifkan.
• gcloud SDK terinstal dan terautentikasi.
• Pengelola paket uv terinstal.
• IDE Google Antigravity terinstal.

Prasyarat

Codelab ini mengasumsikan bahwa Anda sudah terbiasa dengan:

• Menavigasi sistem menggunakan terminal.
• Konsep pengembangan Python dasar.
• Konsep dasar Google Cloud.

2. Menyiapkan Lingkungan Google Cloud

Sebelum men-deploy, Anda harus mengonfigurasi project Google Cloud dan mengaktifkan API yang diperlukan.

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

Saat Antigravity menjalankan perintah ini, Antigravity akan mengusulkan dan menjalankan perintah terminal gcloud yang diperlukan untuk mengonfigurasi project Anda dan mengaktifkan layanan. Selama langkah autentikasi, Antigravity akan menampilkan URL otorisasi di terminal. Klik link untuk login melalui browser web dan memberikan akses. Setelah Anda menyelesaikan login browser, Antigravity akan melanjutkan eksekusi untuk menetapkan variabel lingkungan project Anda dan mengaktifkan API yang diperlukan.

Catatan: Jika ini adalah project baru, gcloud mungkin akan meminta Anda untuk mengaktifkan Service Usage API terlebih dahulu. Ikuti link yang disediakan di terminal untuk mengaktifkannya di Konsol Cloud jika diminta.

3. Menyiapkan CLI Agen &Keterampilan ADK

Agar Antigravity dapat membangun dan men-deploy agen ADK dengan baik, Antigravity memerlukan kumpulan keterampilan ADK. Kumpulan keterampilan ini adalah referensi gabungan untuk ADK API, kerangka project, alur kerja deployment agents-cli, dan evaluasi. Menginstal toolchain agents-cli juga akan menginstal keterampilan ini ke dalam agen coding Anda, sehingga agen coding Anda dapat mengelola siklus proses lengkap agen Anda, mulai dari kerangka lokal hingga deployment cloud.

👉 Salin dan tempel perintah berikut ke 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.

Saat Antigravity menjalankan perintah ini, Antigravity akan menjalankan uvx google-agents-cli setup di terminal untuk menginstal CLI dan keterampilan pendampingnya. Kemudian, Antigravity akan menjalankan agents-cli info untuk memverifikasi penginstalan dan mencantumkan keterampilan domain yang baru diinstal (seperti google-agents-cli-deploy dan google-agents-cli-workflow) langsung di chat.

Catatan untuk pengguna Antigravity: Selama codelab ini, Antigravity dapat membuat rencana penerapan atau menampilkan pop-up sebelum menjalankan perintah atau menulis kode. Pastikan untuk meninjau dan menyetujui rencana atau pop-up ini agar Antigravity dapat melanjutkan tugas.

Tips Kuota: Jika kuota Anda habis selama pengujian atau pengembangan, ganti model di Antigravity ke model lain yang tersedia.

4. Membuat project agen

Setelah lingkungan cloud Anda dikonfigurasi dan keterampilan CLI Anda diinstal, Anda siap membuat codebase lokal untuk agen Anda. Pada langkah ini, Anda akan menggunakan Antigravity untuk membuat kerangka prototipe Ambient Expense Agent yang berfungsi penuh dan kompatibel dengan ADK 2.0.

Catatan untuk Pengguna Kaggle 5 days of AI Agents: Jika Anda berhasil menyelesaikan Codelab Ambient Expense Agent Vibecode ini untuk Hari ke-4 dan lebih memilih untuk men-deploy codebase agen kustom yang ada, Anda dapat melewati langkah pembuatan kerangka ini dan melanjutkan ke langkah berikutnya.

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

Saat Antigravity menjalankan perintah ini, Antigravity akan memanfaatkan keterampilan pembuatan kerangka yang baru diinstal untuk menjalankan agents-cli scaffold create expense-agent --adk di terminal. Kemudian, Antigravity akan memverifikasi dan menyesuaikan kode prototipe yang dibuat untuk memastikan expense-agent Anda menerapkan alur peninjauan otomatis dan manusia dalam loop dengan benar dalam alur kerja grafik Agent Development Kit (ADK).$100

5. Mempersiapkan Deployment Produksi

Agent Runtime adalah layanan Google Cloud yang terkelola sepenuhnya yang memungkinkan Anda men-deploy, mengelola, dan menskalakan agen AI dalam produksi. Agent Runtime menangani kompleksitas operasional hosting, menawarkan lingkungan stateful dengan fitur seperti pengelolaan sesi, memori jangka panjang, dan sandbox eksekusi kode yang aman.

Mengapa Harus Men-deploy ke Agent Runtime?

Saat membangun agen secara lokal dengan Antigravity, agen Anda akan berjalan di mesin lokal Anda terhadap localhost. Meskipun bagus untuk pembuatan prototipe yang cepat, agen lokal akan berhenti berjalan saat Anda menutup laptop.

Men-deploy agen Anda ke Agent Runtime akan memindahkan alur kerja Anda ke lingkungan Google Cloud yang terkelola sepenuhnya dan selalu aktif. Hal ini akan membuat endpoint backend langsung yang aman dan tetap aktif 24/7. Di codelab berikutnya, Anda akan membangun frontend web yang terhubung langsung ke endpoint cloud ini, sehingga agen Anda akan memiliki URL publik.

Selain itu, Agent Runtime menyediakan infrastruktur khusus yang dioptimalkan secara khusus untuk agen AI—menawarkan kemampuan bawaan seperti:

• Eksekusi Stateful Terkelola: Pengelolaan sesi bawaan dan persistensi memori jangka panjang di seluruh percakapan.
• Sandbox yang Aman: Menjalankan panggilan alat dinamis dan kode yang dibuat agen dengan aman di lingkungan yang terisolasi.
• Kemampuan Observasi Perusahaan: Streaming telemetri siap pakai langsung ke Cloud Trace dan Cloud Logging.

Untuk menghosting agen Anda di Agent Runtime, Anda harus meningkatkan direktori project lokal dengan deskriptor produksi, skema, dan wrapper endpoint.

👉 Perintah Antigravity:

Scaffold the production deployment files for Agent Runtime.

Saat Antigravity menjalankan perintah ini, Antigravity akan menjalankan agents-cli scaffold enhance --deployment-target agent_runtime --yes di root project Anda. Perintah ini akan memindai direktori Anda dan otomatis membuat:

• app/agent_runtime_app.py: Wrapper layanan tingkat produksi.
• deployment_metadata.json: Skema tata letak yang digunakan oleh Agent Runtime untuk menjalankan resource.

Logika inti agen Anda di app/agent.py akan tetap utuh dan dipertahankan.

6. Pengemasan dan Verifikasi Lokal

Sebelum memulai upload cloud, kunci paket Anda dan jalankan uji coba lokal untuk mengidentifikasi potensi konflik dependensi.

👉 Perintah Antigravity:

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

Saat Antigravity menjalankan perintah ini, Antigravity akan menjalankan uv lock di terminal terlebih dahulu untuk membuat file kunci deterministik, sehingga memastikan versi library yang konsisten di cloud. Kemudian, Antigravity akan menjalankan agents-cli deploy --dry-run untuk memverifikasi validitas konfigurasi dan melihat pratinjau langkah-langkah deployment tanpa menyediakan resource cloud. Anda dapat meninjau output uji coba di terminal untuk mengonfirmasi bahwa semua file dan setelan sudah benar.

7. Men-deploy ke Agent Runtime

Deploy Ambient Expense Agent Anda ke Agent Runtime.

👉 Perintah Antigravity:

Deploy this agent to Agent Runtime.

Saat Antigravity menjalankan perintah ini, Antigravity akan mengaktifkan keterampilan google-agents-cli-deploy dan menjalankan agents-cli deploy --project YOUR_PROJECT_ID --region us-west1. Proses pengemasan, upload, dan penyediaan Agent Runtime biasanya memerlukan waktu 5–10 menit. Antigravity akan memantau progres deployment di terminal, dan setelah selesai, Antigravity akan menampilkan URL endpoint langsung Anda.

💡 Tips Profesional (Mengelola Jendela Batas Waktu): Jika Anda tidak ingin mengunci terminal selama deployment yang panjang, Anda dapat menginstruksikan Antigravity untuk menggunakan flag --no-wait guna memulai deployment secara asinkron, dan memeriksa progres nanti menggunakan agents-cli deploy --status.

Jika Anda mengalami masalah saat men-deploy agen, pertimbangkan untuk menggunakan region lain. Alat Pemilih Region Google Cloud dapat membantu Anda menentukan region terbaik untuk project Anda berdasarkan latensi, harga, dan jejak karbon.

8. Menguji Agen Anda

Setelah agen Anda di-deploy, Anda dapat memverifikasi bahwa agen tersebut otomatis menyetujui pengeluaran kecil, dan menandai pengeluaran yang lebih besar dengan benar untuk verifikasi manusia dalam loop.

👉 Perintah Antigravity untuk memverifikasi mesin yang di-deploy langsung:

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.

Catatan: Saat Antigravity menjalankan perintah pengujian ini terhadap endpoint langsung Anda, jika Antigravity menemukan error deployment atau eksekusi, Antigravity akan otomatis mencoba men-debug masalah tersebut, menerapkan perbaikan kode yang diperlukan, dan men-deploy ulang agen untuk Anda.

Atau, Anda dapat menguji agen secara manual menggunakan pratinjau Playground Konsol Cloud. Untuk membuka Playground:

1. Di Konsol Google Cloud, gunakan menu navigasi untuk memilih Agent Platform > Deployments.
2. Pilih agen yang di-deploy dari daftar deployment.
3. Klik tombol Playground untuk membuka antarmuka chat pengujian interaktif.

👉 Untuk menguji Persetujuan Otomatis(<$100), tempel payload JSON berikut ke kotak chat:

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

Anda akan menerima respons JSON yang menampilkan output node auto_approve dengan status "disetujui".

👉 Untuk menguji alur Manusia dalam Loop (HITL), tempel payload JSON berikut.

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

Tindakan ini akan memicu review_agent, mengeluarkan peringatan, lalu menjeda eksekusi, sehingga menghasilkan RequestInput (Manusia dalam loop) yang meminta persetujuan.

9. Memantau dan Mengamati Agen Produksi Anda

Dengan Agent Runtime, telemetri akan otomatis terhubung. Setiap interaksi, panggilan model, dan eksekusi alat akan menstreaming log dan rentang real-time ke project Anda.

1. Memeriksa Trace: Buka Konsol Cloud Trace untuk mengaudit peta transaksi langsung, latensi model, dan langkah-langkah eksekusi alat.
2. Log Audit: Gunakan Cloud Logging untuk memeriksa output standar real-time dan trace stack diagnostik.

3. Analisis Agregat: Jika flag --bq-analytics diaktifkan selama pembuatan kerangka, kueri log Anda di dalam BigQuery menggunakan SQL untuk melihat rasio persetujuan dan tren percakapan.

Kueri SQL berikut memberikan contoh untuk menghitung rasio persetujuan. Anda dapat meminta Antigravity untuk menyesuaikan kueri ini untuk project dan set data BigQuery tertentu:

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. (Opsional) Memverifikasi Pendaftaran di Agent Registry

Agar layanan, developer, atau agen lain di organisasi Anda dapat menemukan dan menggunakan agen pengeluaran Anda dengan aman, agen tersebut harus terdaftar di Agent Registry perusahaan (Gemini Enterprise).

Karena Anda men-deploy agen ke Agent Runtime, agen tersebut akan otomatis terdaftar di Agent Registry. Setiap pembaruan atau penghapusan agen Anda di Agent Runtime pada masa mendatang juga akan otomatis disinkronkan ke Agent Registry.

👉 Perintah Antigravity untuk memverifikasi pendaftaran otomatis agen Anda:

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

Saat Antigravity menjalankan perintah ini, Antigravity akan menjalankan agents-cli publish gemini-enterprise --list di terminal. Tindakan ini akan mengkueri Agent Registry dan mencantumkan semua agen Gemini Enterprise yang terdaftar di project Anda, sehingga Anda dapat mengonfirmasi bahwa Ambient Expense Agent Anda aktif dan dapat ditemukan di seluruh organisasi Anda.

11. Pembersihan

Peserta Kursus Kaggle: Jika Anda menyelesaikan lab ini sebagai bagian dari kursus 5-Day AI Agents Kaggle dan berencana untuk melanjutkan ke lab berikutnya (Vibecode and Deploy a Frontend for an ADK Agent) untuk membangun klien frontend dan integrasi Pub/Sub, jangan hapus agen yang di-deploy. Anda akan memerlukan infrastruktur cloud aktif ini untuk lab berikutnya.

Untuk menghindari biaya berkelanjutan di akun Google Cloud Anda, Anda harus mematikan dan membersihkan resource yang di-deploy setelah selesai.

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

Saat Antigravity menjalankan perintah ini, Antigravity akan mengotomatiskan seluruh proses pembersihan resource:

1. Menghapus Agen yang Di-deploy: Antigravity akan membaca deployment_metadata.json untuk mendapatkan ID Agent Runtime jarak jauh Anda, lalu menghapus instance mesin langsung secara terprogram dari Vertex AI.
2. Membersihkan Ruang Kerja Lokal: Antigravity akan menghapus file deployment_metadata.json yang tidak berlaku dari root project Anda.
3. Membersihkan Artifact Registry: Antigravity akan menjalankan gcloud artifacts docker images delete untuk menghapus image container yang dibuat dari Artifact Registry, sehingga mengosongkan ruang penyimpanan cloud.

12. Selamat

Selamat! Anda telah berhasil men-deploy dan memverifikasi Ambient Expense Agent tingkat produksi di Google Cloud.

Yang telah Anda pelajari

• Penyiapan Google Cloud: Mengonfigurasi kredensial project dan mengaktifkan API platform yang diperlukan.
• Alat &Keterampilan: Menginstal agents-cli dan memuat keterampilan pendamping ADK ke Antigravity.
• Pembuatan Kerangka Produksi: Membuat kerangka Agent Runtime untuk agen ADK 2.0.
• Verifikasi Lokal: Membuat file kunci deterministik (uv lock) dan menjalankan pemeriksaan uji coba.
• Deployment Cloud: Menghosting agen Anda secara langsung di infrastruktur Agent Runtime terkelola.
• Kemampuan Observasi &Analisis: Melacak eksekusi di Cloud Trace dan menganalisis telemetri di BigQuery.
• Penemuan Perusahaan: Memverifikasi pendaftaran otomatis di Agent Registry perusahaan.

Apa Langkah Selanjutnya?

• Melakukan Analisis BigQuery: Kueri log telemetri agen Anda di BigQuery untuk menganalisis rasio persetujuan dan tren percakapan dari waktu ke waktu.
• Codelab Vibe to Live: Gunakan Google Antigravity untuk mengembangkan klien frontend di Cloud Run dan menghubungkannya langsung ke endpoint backend Agent Runtime langsung Anda.

Dapatkan badge Kaggle 5-Day AI Agents 🎉

Menyelesaikan lab ini sebagai bagian dari 5-Day AI Agents: Intensive Vibe Coding Course with Google di Kaggle? Klaim badge penyelesaian Anda:

Dapatkan badge 5-Day AI Agents

Referensi

• Dokumentasi Agent Development Kit (ADK)
• Runtime Gemini Enterprise Agent Platform
• Panduan Referensi CLI Agen (agents-cli)
• Ringkasan Gemini Enterprise Agent Registry
• Dokumentasi Google Cloud Trace