Sistem AI agen tunggal menggunakan ADK dan Cloud Run

Dokumen ini memberikan arsitektur referensi untuk membantu Anda mendesain sistem AI agen tunggal di Google Cloud. Sistem agen tunggal dalam arsitektur ini dibangun menggunakan Agent Development Kit (ADK) dan di-deploy di Cloud Run. Anda juga dapat men-deploy agen di Vertex AI Agent Engine atau Google Kubernetes Engine (GKE). Arsitektur ini menggunakan Model Context Protocol (MCP), yang memungkinkan agen mengakses dan memproses informasi dari berbagai sumber sehingga dapat memberikan insight yang kaya konteks.

Dokumen ini ditujukan untuk arsitek, developer, dan administrator aplikasi AI. Dokumen ini mengasumsikan bahwa Anda memiliki pemahaman dasar tentang konsep AI, machine learning (ML), dan model bahasa besar (LLM). Dokumen ini juga mengasumsikan bahwa Anda memiliki pemahaman dasar tentang agen dan model AI. Dokumen ini tidak memberikan panduan khusus untuk mendesain dan membuat kode agen AI.

Bagian Deployment dalam dokumen ini mencantumkan contoh kode yang dapat Anda gunakan untuk mempelajari cara membangun dan men-deploy sistem AI agen tunggal.

Arsitektur

Diagram berikut menunjukkan arsitektur untuk sistem AI agen tunggal yang di-deploy di Cloud Run:

Arsitektur satu agen yang di-deploy di Cloud Run.

Komponen arsitektur

Arsitektur contoh terdiri dari komponen berikut:

Komponen Deskripsi
Frontend Pengguna berinteraksi dengan agen melalui frontend, seperti antarmuka chat, yang berjalan sebagai layanan Cloud Run serverless.
Agen Agen menerima permintaan pengguna, menafsirkan maksud pengguna, memilih alat yang sesuai, lalu mensintesis informasi untuk menjawab kueri.
Runtime agen Agen dibuat menggunakan ADK dan di-deploy sebagai layanan Cloud Run serverless. Anda juga dapat men-deploy agen di Vertex AI Agent Engine atau sebagai aplikasi dalam container di GKE. Untuk mengetahui informasi tentang cara memilih runtime agen, lihat Memilih komponen arsitektur AI agentik Anda.
ADK ADK menyediakan alat dan framework untuk mengembangkan, menguji, dan men-deploy agen. ADK mengabstraksi kompleksitas pembuatan agen dan memungkinkan developer AI berfokus pada logika dan kemampuan agen. Saat mengembangkan agen menggunakan ADK, Anda dapat mengonfigurasi agen untuk mengakses dan menggunakan alat bawaan seperti Google Penelusuran.
Model AI dan runtime model Untuk penayangan inferensi, agen dalam arsitektur contoh ini menggunakan model AI Gemini di Vertex AI.
MCP Toolbox MCP Toolbox for Databases menyediakan alat khusus database untuk agen. Modul ini dapat menangani kompleksitas seperti penggabungan koneksi dan autentikasi.
Klien, server, dan alat MCP MCP memfasilitasi akses ke alat dengan menstandardisasi interaksi antara agen dan alat. Untuk setiap pasangan agen-alat, klien MCP mengirimkan permintaan ke server MCP yang digunakan agen untuk mengakses alat seperti sistem file atau API. Misalnya, alat eksternal seperti StackOverflow LangChain Tool dan alat Google Penelusuran dapat memberikan data dan perujukan.
Kemampuan observasi Agen dipantau menggunakan Google Cloud Observability untuk logging, pemantauan, dan tracing.

Alur agentic

Contoh sistem agen tunggal dalam arsitektur sebelumnya memiliki alur berikut:

  1. Pengguna memasukkan perintah melalui frontend, seperti antarmuka chat, yang berjalan sebagai layanan Cloud Run serverless.
  2. Frontend meneruskan perintah ke agen.
  3. Agen menggunakan model AI untuk menalar perintah pengguna dan mensintesis respons:
    • Model AI menentukan alat mana yang akan digunakan untuk mengumpulkan informasi kontekstual atau melakukan tugas.
    • Agen melakukan panggilan alat dan menambahkan respons ke konteksnya.
    • Agen melakukan perujukan dan validasi perantara.

Produk yang digunakan

Arsitektur referensi ini menggunakan produk dan alat open source berikut: Google Cloud

Kasus penggunaan

Bagian ini menjelaskan kemungkinan kasus penggunaan untuk arsitektur yang dijelaskan dalam dokumen ini.

Triage laporan bug otomatis

Anda dapat menyesuaikan arsitektur referensi ini untuk mengotomatiskan triase laporan bug yang masuk: memahami masalah, menelusuri duplikat, mengumpulkan konteks teknis yang relevan, lalu membuat bug dalam sistem. Agen yang didukung AI dapat bertindak sebagai asisten cerdas yang dapat melakukan penyelidikan awal, sehingga pakar manusia dapat berfokus pada pemecahan masalah yang lebih kompleks.

Untuk kasus penggunaan ini, arsitektur memberikan manfaat berikut:

  • Waktu penyelesaian yang lebih cepat: Agen mengotomatiskan riset awal dan pengumpulan konteks, yang dapat mengurangi waktu yang diperlukan untuk menetapkan dan menyelesaikan tiket bug secara signifikan.
  • Peningkatan akurasi dan konsistensi: Agen dapat secara sistematis menelusuri beberapa sumber data (database internal, repositori kode, dan web publik). Kemampuan ini memberikan analisis yang lebih komprehensif dan konsisten daripada yang mungkin dilakukan oleh triase manual.
  • Mengurangi beban kerja manual: Agen dapat mengalihkan tugas triase berulang dari tim dukungan IT dan engineering, sehingga mereka dapat berfokus pada pekerjaan yang lebih bernilai tinggi.

Arsitektur ini ideal untuk organisasi mana pun yang mengembangkan software dan ingin meningkatkan efisiensi serta efektivitas proses penyelesaian bug-nya. Untuk mengetahui informasi dan opsi deployment selengkapnya, lihat Software Bug Assistant - ADK Python Sample Agent dan Tools Make an Agent: From Zero to Assistant with ADK.

Layanan pelanggan

Anda dapat menyesuaikan arsitektur referensi ini untuk membantu memberikan pengalaman belanja yang lancar dan dipersonalisasi bagi pelanggan. Agen yang didukung AI dapat memberikan layanan pelanggan, merekomendasikan produk, mengelola pesanan, dan menjadwalkan layanan, sehingga perwakilan manusia dapat berfokus pada tugas lain.

Untuk kasus penggunaan ini, arsitektur memberikan manfaat berikut:

  • Penjualan tambahan dan promosi: Agen dapat membantu meningkatkan penjualan dengan menyarankan produk, layanan, dan promosi. Saran agen didasarkan pada pesanan pelanggan saat ini dan penjualan yang relevan, histori pesanan pelanggan, dan item yang ada di keranjang mereka.

  • Pengelolaan pesanan dan penjadwalan: Agen dapat meningkatkan efisiensi dan mengurangi hambatan pelanggan dengan mengelola isi keranjang belanja pelanggan dan memfasilitasi penjadwalan mandiri untuk layanan.

  • Mengurangi beban kerja manual: Agen menangani pertanyaan umum, pesanan, dan penjadwalan, sehingga agen layanan pelanggan manusia dapat berfokus pada masalah pelanggan yang lebih kompleks.

Arsitektur ini ideal untuk organisasi retail yang ingin meningkatkan pengalaman pelanggan, meningkatkan penjualan, dan menyederhanakan pengelolaan pesanan dan penjadwalan. Untuk mengetahui informasi dan opsi deployment selengkapnya, lihat Agen Layanan Pelanggan Cymbal Home & Garden.

Perkiraan deret waktu

Anda dapat menyesuaikan arsitektur referensi ini untuk membantu memprediksi hasil, seperti perkiraan permintaan, prediksi pola traffic, atau analisis dan prediksi kegagalan mesin. Agen yang didukung AI dapat menganalisis data real-time, tren historis, dan acara mendatang. Agen dapat menggunakan analisis ini untuk memperkirakan hasil selama jangka waktu tertentu. Prakiraan ini dapat membantu Anda membuat rencana dan mengurangi waktu yang dihabiskan oleh analis data manusia.

Kasus penggunaan ini dapat menguntungkan organisasi dalam banyak skenario, seperti berikut:

  • Pengelolaan inventaris: Dengan menggunakan analisis lanjutan yang dikombinasikan dengan data penjualan historis dan tren pasar, agen dapat membantu Anda merencanakan pesanan pengisian ulang stok sehingga Anda dapat bersiap menghadapi lonjakan atau penurunan permintaan pelanggan.
  • Rute perjalanan: Agen dapat membantu menghemat waktu dan mengurangi biaya perjalanan bagi penyedia layanan dan pengiriman dengan menganalisis pola lalu lintas real-time dan historis beserta peristiwa seperti pembangunan atau penutupan jalan.
  • Menghindari pemadaman layanan: Agen dapat membantu Anda menghindari potensi gangguan layanan dengan membantu mengidentifikasi akar penyebab pemadaman layanan sebelumnya. Hal ini juga dapat membantu memprediksi potensi kegagalan di masa mendatang sehingga Anda dapat memitigasi masalah sebelum menjadi masalah yang lebih besar.

Arsitektur ini ideal untuk organisasi mana pun yang perlu beradaptasi dengan perubahan pola berdasarkan tren yang sudah ada. Cara ini juga ideal untuk organisasi yang pelanggannya dapat memperoleh manfaat dari insight proaktif yang membantu mereka membuat rencana untuk masa depan. Untuk mengetahui informasi dan opsi deployment selengkapnya, lihat Agen Peramalan Deret Waktu dengan ADK dan MCP Toolbox Google.

Pengambilan dokumen

Anda dapat menyesuaikan arsitektur referensi ini untuk menggunakan Vertex AI RAG Engine dan membuat agen untuk mengelola pengambilan data kontekstual. Agen pengambilan dokumen dapat mengambil data yang relevan dari sekumpulan dokumen pilihan untuk memberikan jawaban faktual dengan kutipan ke materi sumber.

Dengan agen pengambilan dokumen, Anda dapat membantu memastikan bahwa pelanggan dan pengguna internal mendapatkan respons yang tepat dan sesuai konteks atas kueri mereka. Penerapan ini dapat membantu mengurangi kesalahan dan ketidakakuratan dengan membantu memastikan bahwa jawaban didasarkan pada informasi yang Anda validasi.

Arsitektur pengambilan dokumen sangat ideal untuk pusat informasi tentang kebijakan dan proses, infrastruktur teknis, kemampuan produk, dan dokumentasi berbasis fakta lainnya. Untuk mengetahui informasi tentang cara mengembangkan agen pengambilan dokumen yang didukung retrieval-augmented generation (RAG), lihat Agen Pengambilan Dokumentasi.

Alternatif desain

Bagian ini menyajikan pendekatan desain alternatif yang dapat Anda pertimbangkan untuk deployment agen AI di Google Cloud.

Runtime agen

Dalam arsitektur yang dijelaskan dalam dokumen ini, agen dan alatnya di-deploy di Cloud Run. Anda juga dapat menggunakan GKE atau Vertex AI Agent Engine sebagai runtime alternatif. Untuk mengetahui informasi tentang cara memilih runtime agen, lihat Runtime agen di "Memilih komponen arsitektur AI agentik Anda".

Runtime model AI

Dalam arsitektur yang dijelaskan dalam dokumen ini, runtime model AI adalah Vertex AI. Anda juga dapat menggunakan Cloud Run atau GKE sebagai runtime alternatif. Untuk mengetahui informasi tentang cara memilih runtime model, lihat Runtime model di "Pilih komponen arsitektur AI agentik Anda".

Pertimbangan desain

Bagian ini memberikan panduan untuk membantu Anda menggunakan arsitektur referensi ini guna mengembangkan arsitektur yang memenuhi persyaratan spesifik Anda dalam hal keamanan, keandalan, biaya, efisiensi operasional, dan performa.

Desain sistem

Bagian ini memberikan panduan untuk membantu Anda memilih wilayah Google Cloud untuk deployment dan memilih produk serta alat Google Cloud yang sesuai.

Pemilihan wilayah

Saat memilih Google Cloud region untuk aplikasi AI Anda, pertimbangkan faktor-faktor berikut:

Untuk memilih lokasi Google Cloud yang sesuai untuk aplikasi Anda, gunakan alat berikut:

  • Google Cloud Pemilih Region: Alat berbasis web interaktif untuk memilih region Google Cloud yang optimal untuk aplikasi dan data Anda berdasarkan faktor seperti jejak karbon, biaya, dan latensi.
  • Cloud Location Finder API: API publik yang menyediakan cara terprogram untuk menemukan lokasi deployment di Google Cloud, Google Distributed Cloud, dan penyedia cloud lainnya.

Desain agen

Bagian ini memberikan rekomendasi umum untuk mendesain agen AI. Panduan mendetail tentang penulisan kode dan logika agen berada di luar cakupan dokumen ini.

Fokus desain Rekomendasi
Definisi dan desain agen
  • Tentukan dengan jelas sasaran bisnis sistem AI agentik dan tugas yang dilakukan setiap agen.
  • Pilih pola desain agen yang paling sesuai dengan kebutuhan Anda.
  • Gunakan ADK untuk membuat, men-deploy, dan mengelola arsitektur agen Anda secara efisien.
Interaksi agen
  • Merancang agen yang berinteraksi dengan manusia dalam arsitektur untuk mendukung interaksi bahasa alami.
  • Pastikan setiap agen mengomunikasikan tindakan dan statusnya dengan jelas kepada klien dependennya.
  • Merancang agen untuk mendeteksi dan menangani kueri yang ambigu dan interaksi yang bernuansa.
Konteks, alat, dan data
  • Pastikan agen memiliki konteks yang cukup untuk melacak interaksi multi-turn dan parameter sesi.
  • Jelaskan dengan jelas tujuan, argumen, dan penggunaan alat yang dapat digunakan agen.
  • Pastikan respons agen didasarkan pada sumber data yang andal untuk mengurangi halusinasi.
  • Menerapkan logika untuk menangani situasi tidak cocok, seperti saat perintah di luar topik.

Penyimpanan memori dan sesi

Contoh arsitektur yang ditampilkan dalam dokumen ini tidak mencakup penyimpanan sesi atau memori. Dalam lingkungan produksi, Anda dapat meningkatkan kualitas respons dan menambahkan personalisasi dengan mengintegrasikan status dan memori ke dalam agen Anda.

  • Sesi: Sesi adalah rangkaian percakapan antara pengguna dan agen, dari interaksi awal hingga akhir dialog.
  • Status: Status adalah data yang digunakan dan dikumpulkan oleh agen dalam sesi tertentu. Data status yang dikumpulkan mencakup histori pesan yang dipertukarkan oleh pengguna dan agen, hasil panggilan alat apa pun, dan variabel lain yang diperlukan agen untuk memahami konteks percakapan.

ADK dapat melacak sesi dalam memori jangka pendek menggunakan objek Session dan atribut state. ADK juga mendukung memori jangka panjang di seluruh sesi dengan pengguna yang sama, termasuk melalui Bank Memori. Untuk menyimpan status sesi, Anda juga dapat menggunakan layanan seperti Memorystore untuk Redis.

Untuk mengetahui informasi tentang opsi memori agen, lihat Memilih komponen arsitektur AI agentik.

Keamanan

Bagian ini menjelaskan pertimbangan dan rekomendasi desain untuk mendesain topologi di Google Cloud yang memenuhi persyaratan keamanan workload Anda.

Komponen Pertimbangan dan rekomendasi desain
Agen

Agen AI menimbulkan risiko keamanan unik dan kritis tertentu yang mungkin tidak dapat dimitigasi secara memadai oleh praktik keamanan deterministik konvensional. Google merekomendasikan pendekatan yang menggabungkan kekuatan kontrol keamanan deterministik dengan pertahanan dinamis berbasis penalaran. Pendekatan ini didasarkan pada tiga prinsip inti: pengawasan manusia, otonomi agen yang ditentukan dengan cermat, dan kemampuan observasi. Berikut adalah rekomendasi spesifik yang selaras dengan prinsip inti ini.

Pengawasan manusia: Sistem AI agentik terkadang dapat gagal atau tidak berfungsi seperti yang diharapkan. Misalnya, model mungkin membuat konten yang tidak akurat atau agen mungkin memilih alat yang tidak sesuai. Dalam sistem AI agentic yang penting bagi bisnis, sertakan alur human-in-the-loop agar supervisor manusia dapat memantau, mengganti, dan menjeda agen. Misalnya, pengguna manusia dapat meninjau output agen, menyetujui atau menolak output, dan memberikan panduan lebih lanjut untuk memperbaiki kesalahan atau membuat keputusan strategis. Pendekatan ini menggabungkan efisiensi sistem AI agentic dengan pemikiran kritis dan keahlian domain pengguna manusia.

Kontrol akses untuk agen: Konfigurasi izin agen menggunakan kontrol Identity and Access Management (IAM). Hanya berikan izin yang diperlukan kepada setiap agen untuk melakukan tugasnya dan berkomunikasi dengan alat dan agen lain. Pendekatan ini membantu meminimalkan potensi dampak pelanggaran keamanan, karena agen yang disusupi akan memiliki akses terbatas ke bagian lain sistem. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan identitas dan izin untuk agen Anda dan Mengelola akses untuk agen yang di-deploy.

Pemantauan: Pantau perilaku agen menggunakan kemampuan pelacakan komprehensif yang memberi Anda visibilitas tentang setiap tindakan yang dilakukan agen, termasuk proses penalaran, pemilihan alat, dan jalur eksekusi. Untuk mengetahui informasi selengkapnya, lihat Logging agen di Vertex AI Agent Engine dan Logging di ADK.

Untuk mengetahui informasi selengkapnya tentang pengamanan agen AI, lihat Keselamatan dan Keamanan untuk Agen AI.
Vertex AI

Tanggung jawab bersama: Keamanan adalah tanggung jawab bersama. Vertex AI mengamankan infrastruktur yang mendasarinya dan menyediakan alat serta kontrol keamanan untuk membantu Anda melindungi data, kode, dan model Anda. Anda bertanggung jawab untuk mengonfigurasi layanan dengan benar, mengelola kontrol akses, dan mengamankan aplikasi Anda. Untuk mengetahui informasi selengkapnya, lihat Tanggung jawab bersama Vertex AI.

Kontrol keamanan: Vertex AI mendukung Google Cloud kontrol keamanan yang dapat Anda gunakan untuk memenuhi persyaratan residensi data, kunci enkripsi yang dikelola pelanggan (CMEK), keamanan jaringan menggunakan Kontrol Layanan VPC, dan Transparansi Akses. Untuk mengetahui informasi selengkapnya, lihat dokumentasi berikut:

Keamanan: Model AI dapat menghasilkan respons berbahaya, terkadang sebagai respons terhadap perintah berbahaya.

  • Untuk meningkatkan keamanan dan mengurangi potensi penyalahgunaan sistem AI agentik, Anda dapat mengonfigurasi filter konten untuk bertindak sebagai penghalang terhadap input dan respons berbahaya. Untuk informasi selengkapnya, lihat Filter keamanan dan konten.
  • Untuk memeriksa dan menyanitasi permintaan dan respons inferensi terhadap ancaman seperti injeksi perintah dan konten berbahaya, Anda dapat menggunakan Model Armor. Model Armor membantu Anda mencegah input berbahaya, memverifikasi keamanan konten, melindungi data sensitif, mematuhi kepatuhan, dan menerapkan kebijakan keamanan secara konsisten.

Akses model: Anda dapat menyiapkan kebijakan organisasi untuk membatasi jenis dan versi model AI yang dapat digunakan dalam project Google Cloud . Untuk mengetahui informasi selengkapnya, lihat Mengontrol akses ke model Model Garden.

Perlindungan data: Untuk menemukan dan melakukan de-identifikasi data sensitif dalam perintah dan respons serta dalam data log, gunakan Cloud Data Loss Prevention API. Untuk mengetahui informasi selengkapnya, tonton video ini: Melindungi data sensitif di aplikasi AI.

MCP Saat Anda mengonfigurasi agen untuk menggunakan MCP, pastikan akses ke data dan alat eksternal diizinkan, terapkan kontrol privasi seperti enkripsi, terapkan filter untuk melindungi data sensitif, dan pantau interaksi agen. Untuk mengetahui informasi selengkapnya, lihat MCP dan Keamanan.
A2A

Keamanan transportasi: Protokol A2A mewajibkan HTTPS untuk semua komunikasi A2A di lingkungan produksi dan merekomendasikan Transport Layer Security (TLS) versi 1.2 atau yang lebih baru.

Autentikasi: Protokol A2A mendelegasikan autentikasi ke mekanisme web standar seperti header HTTP dan ke standar seperti OAuth2 dan OpenID Connect. Setiap agen mengiklankan persyaratan autentikasi di Kartu Agennya. Untuk mengetahui informasi selengkapnya, lihat Autentikasi A2A.

Cloud Run

Keamanan ingress (untuk layanan frontend): Untuk mengontrol akses ke aplikasi, nonaktifkan URL run.app default dari layanan Cloud Run frontend dan siapkan Load Balancer Aplikasi eksternal regional. Selain melakukan load balancing traffic masuk ke aplikasi, load balancer menangani pengelolaan sertifikat SSL. Untuk perlindungan tambahan, Anda dapat menggunakan kebijakan keamanan Google Cloud Armor untuk menyediakan pemfilteran permintaan, perlindungan DDoS, dan pembatasan kecepatan untuk layanan.

Autentikasi pengguna:

  • Pengguna di dalam organisasi Anda: Untuk mengautentikasi akses pengguna internal ke layanan Cloud Run frontend, gunakan Identity-Aware Proxy (IAP). Saat pengguna mencoba mengakses resource yang diamankan oleh IAP, IAP akan melakukan pemeriksaan autentikasi dan otorisasi.
  • Pengguna di luar organisasi Anda: Untuk mengautentikasi akses pengguna eksternal ke layanan frontend, gunakan Identity Platform atau Firebase Authentication. Untuk mengelola akses pengguna eksternal, konfigurasi aplikasi Anda untuk menangani alur login dan membuat panggilan API terautentikasi ke layanan Cloud Run.

Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi pengguna.

Keamanan image container: Untuk memastikan bahwa hanya image container resmi yang di-deploy ke Cloud Run, Anda dapat menggunakan Otorisasi Biner. Untuk mengidentifikasi dan memitigasi risiko keamanan dalam image container, gunakan Artifact Analysis untuk menjalankan pemindaian kerentanan secara otomatis. Untuk informasi selengkapnya, lihat Ringkasan pemindaian container.

Residensi data: Cloud Run membantu Anda memenuhi persyaratan residensi data. Fungsi Cloud Run Anda berjalan dalam region yang dipilih.

Untuk panduan selengkapnya tentang keamanan container, lihat Tips pengembangan Cloud Run umum.

Semua produk dalam arsitektur

Enkripsi data: Secara default, Google Cloud mengenkripsi data dalam penyimpanan menggunakan Google-owned and Google-managed encryption keys. Untuk melindungi data agen Anda menggunakan kunci enkripsi yang Anda kontrol, Anda dapat menggunakan CMEK yang Anda buat dan kelola di Cloud KMS. Untuk mengetahui informasi tentang Google Cloud layanan yang kompatibel dengan Cloud KMS, lihat Layanan yang kompatibel.

Memitigasi risiko pemindahan data yang tidak sah: Untuk mengurangi risiko pemindahan data yang tidak sah, buat perimeter Kontrol Layanan VPC di seputar infrastruktur. Kontrol Layanan VPC mendukung semua layanan Google Cloud yang digunakan oleh arsitektur referensi ini.

Kontrol akses: Saat Anda mengonfigurasi izin untuk resource dalam topologi, ikuti prinsip hak istimewa terendah.

Keamanan lingkungan cloud: Gunakan alat di Security Command Center untuk mendeteksi kerentanan, mengidentifikasi dan memitigasi ancaman, menentukan dan men-deploy postur keamanan, serta mengekspor data untuk analisis lebih lanjut.

Pengoptimalan setelah deployment: Setelah men-deploy aplikasi di Google Cloud, dapatkan rekomendasi untuk lebih mengoptimalkan keamanan dengan menggunakan Active Assist. Tinjau rekomendasi dan terapkan sesuai kebutuhan lingkungan Anda. Untuk informasi selengkapnya, lihat Menemukan rekomendasi di Active Assist.

Rekomendasi keamanan lainnya

Keandalan

Bagian ini menjelaskan pertimbangan dan rekomendasi desain untuk membangun dan mengoperasikan infrastruktur yang andal untuk deployment Anda di Google Cloud.

Komponen Pertimbangan dan rekomendasi desain
Agen

Simulasikan kegagalan: Sebelum men-deploy sistem AI agentik ke produksi, validasikan dengan menyimulasikan lingkungan produksi. Mengidentifikasi dan memperbaiki masalah serta perilaku yang tidak terduga.

Menskalakan secara horizontal: Untuk membantu memastikan ketersediaan tinggi dan fault tolerance, jalankan beberapa instance aplikasi agen Anda di belakang load balancer. Pendekatan ini juga dapat membantu mengurangi latensi dan waktu tunggu habis dengan mendistribusikan permintaan di seluruh instance. Beberapa runtime agen menangani load balancing untuk Anda secara otomatis, seperti dengan penskalaan otomatis instance di layanan Cloud Run.

Pulihkan dari gangguan: Untuk membantu memastikan bahwa agen dapat menangani mulai ulang dengan baik dan mempertahankan konteks, pisahkan status dari runtime. Untuk menerapkan aplikasi agen stateless seperti itu, gunakan penyimpanan data eksternal seperti database atau cache terdistribusi. Misalnya, Anda dapat menggunakan Memory Bank, Memorystore for Redis, atau layanan database seperti Cloud SQL.

Menangani error: Untuk memungkinkan diagnosis dan pemecahan masalah error, terapkan mekanisme logging, penanganan pengecualian, dan coba lagi.

Vertex AI

Pengelolaan kuota: Vertex AI mendukung kuota bersama dinamis (DSQ) untuk model Gemini. DSQ membantu mengelola permintaan bayar sesuai penggunaan secara fleksibel, dan menghilangkan kebutuhan untuk mengelola kuota secara manual atau meminta penambahan kuota. DSQ mengalokasikan resource yang tersedia secara dinamis untuk model dan region tertentu di seluruh pelanggan aktif. Dengan DSQ, tidak ada batas kuota yang telah ditentukan sebelumnya untuk setiap pelanggan.

Perencanaan kapasitas: Jika jumlah permintaan ke model melebihi kapasitas yang dialokasikan, kode error 429 akan ditampilkan. Untuk workload yang penting bagi bisnis dan memerlukan throughput tinggi yang konsisten, Anda dapat memesan throughput menggunakan Throughput yang Disediakan.

Ketersediaan endpoint model: Jika data dapat dibagikan di beberapa wilayah atau negara, Anda dapat menggunakan endpoint global untuk model.

Cloud Run

Ketahanan terhadap gangguan infrastruktur: Cloud Run adalah layanan regional. Layanan ini menyimpan data secara sinkron di beberapa zona dalam satu region dan secara otomatis melakukan load balancing traffic di seluruh zona. Jika terjadi pemadaman layanan zona, Cloud Run akan terus berjalan dan data tidak akan hilang. Jika terjadi pemadaman layanan di suatu region, layanan akan berhenti berjalan hingga Google menyelesaikan pemadaman layanan tersebut.

Penskalaan horizontal: Layanan Cloud Run menangani penskalaan otomatis instance untuk Anda. Penskalaan otomatis membantu memastikan bahwa instance dapat menangani semua permintaan, peristiwa, dan pemanfaatan CPU yang masuk yang diperlukan untuk memastikan ketersediaan tinggi.

Semua produk dalam arsitektur

Pengoptimalan pasca-deployment: Setelah Anda men-deploy aplikasi di Google Cloud, dapatkan rekomendasi untuk lebih mengoptimalkan keamanan dengan menggunakan Active Assist. Tinjau rekomendasi dan terapkan sesuai kebutuhan untuk lingkungan Anda. Untuk informasi selengkapnya, lihat Menemukan rekomendasi di Active Assist.

Untuk prinsip dan rekomendasi keandalan yang khusus untuk workload AI dan ML, lihat Perspektif AI dan ML: Keandalan dalam Well-Architected Framework.

Operasi

Bagian ini menjelaskan faktor-faktor yang harus dipertimbangkan saat Anda menggunakan arsitektur referensi ini untuk mendesain topologi yang dapat Anda operasikan secara efisien. Google Cloud

Komponen Pertimbangan dan rekomendasi desain
Agen

Proses debug dan analisis: Terapkan pencatatan ke log terstruktur dalam aplikasi agen Anda. Logging dan pelacakan memungkinkan Anda merekam informasi penting dalam format terstruktur, seperti alat yang dipanggil, input dan output agen, serta latensi setiap langkah.

Vertex AI

Pemantauan menggunakan log: Secara default, log agen yang ditulis ke aliran stdout dan stderr dirutekan ke Cloud Logging. Untuk logging lanjutan, Anda dapat mengintegrasikan logger Python dengan Logging. Jika Anda memerlukan kontrol penuh atas logging dan log terstruktur, gunakan klien Logging. Untuk mengetahui informasi selengkapnya, lihat Mencatat aktivitas agen dan Mencatat aktivitas di ADK.

Evaluasi berkelanjutan: Lakukan evaluasi kualitatif secara rutin terhadap output agen dan arah atau langkah-langkah yang dilakukan agen untuk menghasilkan output. Untuk menerapkan evaluasi agen, Anda dapat menggunakan layanan evaluasi AI generatif atau metode evaluasi yang didukung ADK.

Cloud Run

Kesehatan dan performa: Pantau layanan Cloud Run Anda menggunakan Google Cloud Observability. Siapkan pemberitahuan di Cloud Monitoring untuk memberi tahu Anda tentang potensi masalah, seperti peningkatan rasio error, latensi tinggi, atau penggunaan resource yang tidak normal.

Database

Kesehatan dan performa: Pantau database Anda dengan menggunakan Google Cloud Observability. Siapkan pemberitahuan di Monitoring untuk memberi tahu Anda tentang potensi masalah, seperti peningkatan rasio error, latensi tinggi, atau penggunaan resource yang tidak normal.

MCP

Alat database: Untuk mengelola alat database secara efisien bagi agen AI Anda dan memastikan bahwa agen menangani kompleksitas seperti penggabungan koneksi dan autentikasi secara aman, gunakan MCP Toolbox for Databases. Direktori ini menyediakan lokasi terpusat untuk menyimpan dan memperbarui alat database. Anda dapat membagikan alat di seluruh agen dan memperbarui alat tanpa men-deploy ulang agen. Toolbox ini mencakup berbagai alat untuk database seperti AlloyDB untuk PostgreSQL dan untuk database pihak ketiga seperti MongoDB. Google Cloud

Model AI generatif: Untuk mengizinkan agen AI menggunakan model AI generatif Google seperti Imagen dan Veo, Anda dapat menggunakan Server MCP untuk Google Cloud API media generatif.

Produk dan alat keamanan Google: Agar agen AI Anda dapat mengakses produk dan alat keamanan Google seperti Google Security Operations, Google Threat Intelligence, dan Security Command Center, gunakan server MCP untuk produk keamanan Google.

Semua produk Google Cloud dalam arsitektur

Pelacakan: Terus mengumpulkan dan menganalisis data pelacakan menggunakan Trace. Data rekaman aktivitas memungkinkan Anda mengidentifikasi dan mendiagnosis masalah latensi dengan cepat dalam alur kerja agen yang kompleks. Anda dapat melakukan analisis mendalam melalui visualisasi di halaman penjelajah rekaman aktivitas Google Cloud console. Untuk mengetahui informasi selengkapnya, lihat Melacak agen.

Untuk mengetahui prinsip dan rekomendasi keunggulan operasional yang khusus untuk workload AI dan ML, lihat Perspektif AI dan ML: Keunggulan operasional dalam Framework yang Dirancang dengan Baik.

Pengoptimalan biaya

Bagian ini memberikan panduan untuk mengoptimalkan biaya penyiapan dan pengoperasian topologi Google Cloud yang Anda buat menggunakan arsitektur referensi ini.

Komponen Pertimbangan dan rekomendasi desain
Vertex AI

Analisis dan pengelolaan biaya: Untuk menganalisis dan mengelola biaya Vertex AI, sebaiknya Anda membuat metrik dasar untuk kueri per detik (QPS) dan token per detik (TPS). Kemudian, pantau metrik ini setelah deployment. Dasar pengukuran juga membantu perencanaan kapasitas. Misalnya, garis dasar membantu Anda menentukan kapan Throughput yang Disediakan mungkin diperlukan.

Pemilihan model: Model yang Anda pilih untuk aplikasi AI secara langsung memengaruhi biaya dan performa. Untuk mengidentifikasi model yang memberikan keseimbangan optimal antara performa dan biaya untuk kasus penggunaan spesifik Anda, uji model secara iteratif. Sebaiknya mulai dengan model yang paling hemat biaya dan secara bertahap beralih ke opsi yang lebih canggih.

Perintah yang hemat biaya: Panjang perintah (input) dan respons yang dihasilkan (output) secara langsung memengaruhi performa dan biaya. Tulis perintah yang singkat, langsung, dan memberikan konteks yang memadai. Desain perintah Anda untuk mendapatkan respons yang ringkas dari model. Misalnya, sertakan frasa seperti "ringkas dalam 2 kalimat" atau "sebutkan 3 poin utama". Untuk mengetahui informasi selengkapnya, lihat praktik terbaik untuk desain perintah.

Context caching: Untuk mengurangi biaya permintaan yang berisi konten berulang dengan jumlah token input yang tinggi, gunakan context caching.

Permintaan batch: Jika relevan, pertimbangkan prediksi batch. Permintaan batch menimbulkan biaya yang lebih rendah daripada permintaan standar.
Cloud Run

Alokasi resource: Saat membuat layanan Cloud Run, Anda dapat menentukan jumlah memori dan CPU yang akan dialokasikan. Mulai dengan alokasi CPU dan memori default. Amati penggunaan dan biaya resource dari waktu ke waktu, dan sesuaikan alokasi sesuai kebutuhan. Untuk mengetahui informasi selengkapnya, lihat dokumentasi berikut:

Pengoptimalan tarif: Jika dapat memprediksi persyaratan CPU dan memori, Anda dapat menghemat uang dengan diskon abonemen (DA).
Semua produk dalam arsitektur Pengoptimalan setelah deployment: Setelah men-deploy aplikasi di Google Cloud, dapatkan rekomendasi untuk lebih mengoptimalkan biaya dengan menggunakan Active Assist. Tinjau rekomendasi dan terapkan rekomendasi tersebut sesuai dengan lingkungan Anda. Untuk mengetahui informasi selengkapnya, lihat Menemukan rekomendasi di Active Assist.

Untuk memperkirakan biaya resource Google Cloud , gunakan Google Cloud Kalkulator Harga.

Untuk prinsip dan rekomendasi pengoptimalan biaya yang khusus untuk workload AI dan ML, lihat Perspektif AI dan ML: Pengoptimalan biaya dalam Well-Architected Framework.

Pengoptimalan performa

Bagian ini menjelaskan pertimbangan dan rekomendasi desain untuk merancang topologi di Google Cloud yang memenuhi persyaratan performa beban kerja Anda.

Komponen Pertimbangan dan rekomendasi desain
Agen

Pemilihan model: Saat memilih model untuk sistem AI agentic Anda, pertimbangkan kemampuan yang diperlukan untuk tugas yang perlu dilakukan oleh agen.

Pengoptimalan perintah: Untuk meningkatkan dan mengoptimalkan performa perintah dengan cepat dalam skala besar dan menghilangkan kebutuhan untuk penulisan ulang manual, gunakan Pengoptimal perintah Vertex AI. Pengoptimal membantu Anda menyesuaikan perintah secara efisien di berbagai model.
Vertex AI

Pemilihan model: Model yang Anda pilih untuk aplikasi AI secara langsung memengaruhi biaya dan performa. Untuk mengidentifikasi model yang memberikan keseimbangan optimal antara performa dan biaya untuk kasus penggunaan spesifik Anda, uji model secara iteratif. Sebaiknya mulai dengan model yang paling hemat biaya dan secara bertahap beralih ke opsi yang lebih canggih.

Rekayasa perintah: Panjang perintah (input) dan respons yang dihasilkan (output) secara langsung memengaruhi performa dan biaya. Tulis perintah yang singkat, langsung, dan memberikan konteks yang memadai. Desain perintah Anda untuk mendapatkan respons yang ringkas dari model. Misalnya, sertakan frasa seperti "ringkas dalam 2 kalimat" atau "buat daftar 3 poin penting". Untuk mengetahui informasi selengkapnya, lihat praktik terbaik untuk desain perintah.

Context caching: Untuk mengurangi latensi permintaan yang berisi konten berulang dengan jumlah token input yang tinggi, gunakan context caching.
Cloud Run

Alokasi resource: Bergantung pada persyaratan performa, konfigurasikan memori dan CPU yang akan dialokasikan ke layanan Cloud Run. Untuk mengetahui informasi selengkapnya, lihat dokumentasi berikut:

Untuk panduan pengoptimalan performa selengkapnya, lihat Tips pengembangan umum Cloud Run.
Semua produk dalam arsitektur Pengoptimalan setelah deployment: Setelah men-deploy aplikasi di Google Cloud, dapatkan rekomendasi untuk mengoptimalkan performa lebih lanjut dengan menggunakan Active Assist. Tinjau rekomendasi dan terapkan rekomendasi tersebut sesuai dengan lingkungan Anda. Untuk mengetahui informasi selengkapnya, lihat Menemukan rekomendasi di Active Assist.

Untuk prinsip dan rekomendasi pengoptimalan performa yang khusus untuk workload AI dan ML, lihat Perspektif AI dan ML: Pengoptimalan performa dalam Well-Architected Framework.

Deployment

Deployment otomatis untuk arsitektur referensi ini tidak tersedia. Gunakan contoh kode berikut untuk membantu Anda membangun arsitektur agen tunggal:

Untuk contoh kode guna mulai menggunakan ADK bersama dengan server MCP, lihat Alat MCP.

Untuk contoh sistem AI satu agen tambahan, Anda dapat menggunakan contoh kode berikut. Contoh kode ini adalah titik awal yang berfungsi penuh untuk pembelajaran dan eksperimen. Untuk pengoperasian yang optimal di lingkungan produksi, Anda harus menyesuaikan kode berdasarkan persyaratan bisnis dan teknis tertentu.

  • Belanja yang dipersonalisasi: Memberikan rekomendasi produk yang dipersonalisasi untuk merek, penjual, atau marketplace online tertentu.
  • Pengelolaan insiden: Validasi token dan identitas pengguna akhir per permintaan menggunakan propagasi identitas dinamis.
  • Pemrosesan pesanan: Memproses dan menyimpan pesanan serta mengatur konfirmasi email dengan peninjauan manual bersyarat untuk jumlah pesanan tertentu.
  • Data engineering: Mengembangkan pipeline Dataform, memecahkan masalah pipeline, dan mengelola data engineering dari kueri SQL yang kompleks hingga transformasi data dan dependensi data.
  • Pengambilan dokumentasi: Gunakan RAG untuk membuat kueri dokumen yang Anda upload ke Vertex AI RAG Engine dan dapatkan jawaban dengan kutipan ke dokumentasi dan kode.

Langkah berikutnya

Kontributor