Menyiapkan lingkungan

Sebelum menggunakan Agent Runtime, Anda harus memastikan lingkungan Anda sudah disiapkan. Anda harus memiliki project Google Cloud dengan penagihan yang diaktifkan, memiliki izin yang diperlukan, menyiapkan bucket Cloud Storage, dan menginstal Agent Platform SDK untuk Python. Gunakan topik berikut untuk memastikan Anda siap mulai bekerja dengan Agent Runtime.

Untuk contoh Terraform referensi guna menyederhanakan penyiapan dan deployment lingkungan Agent Runtime, pertimbangkan untuk mempelajari agent-starter-pack.

Siapkan dengan Google Cloud

Anda dapat menyiapkan Google Cloud untuk Agent Runtime dengan membuat project Google Cloud .

Google Cloud project

Setiap project dapat diidentifikasi dengan dua cara: nomor project atau project ID. PROJECT_NUMBER dibuat secara otomatis saat Anda membuat project, sedangkan PROJECT_ID dibuat oleh Anda, atau siapa pun yang membuat project. Untuk menyiapkan project:

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Catatan: Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda tidak memiliki izin ini, minta administrator untuk memberi Anda peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin).

Mendapatkan peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menggunakan Agent Runtime, minta administrator untuk memberi Anda peran IAM Agent Platform User (roles/aiplatform.user) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menyiapkan identitas dan izin untuk agen Anda

Anda memiliki opsi berikut saat menyiapkan identitas dan izin:

• Identitas agen (Direkomendasikan) Gunakan identitas agen Identity Access Management (IAM) untuk menyediakan fitur keamanan dan pengelolaan akses saat menggunakan agen di Agent Runtime. Identitas agen terkait dengan setiap agen. Secara default, agen memiliki peran Agent Platform Agent Default Access (roles/aiplatform.agentDefaultAccess), yang hanya mencakup izin logging dan pemanggilan model dasar di seluruh project, serta peran Agent Platform Agent Context Editor (roles/aiplatform.agentContextEditor), yang membatasi agen untuk hanya mengakses sesi, memori, dan sandbox mereka sendiri.

  Catatan: Beberapa fitur yang dapat diakses oleh peran ini mungkin berada dalam Pratinjau

• Akun layanan: Akun layanan dibagikan di seluruh agen yang Anda deploy ke Agent Runtime. Anda memiliki dua opsi untuk akun layanan:

  • Agen Layanan Default: Secara default, agen menggunakan AI Platform Reasoning Engine Service Agent. Akun layanan yang dikelola Google ini memiliki peran Gemini Enterprise Agent Platform Reasoning Engine Service Agent (roles/aiplatform.reasoningEngineServiceAgent), yang mencakup izin default yang diperlukan untuk agen yang di-deploy.
  • Akun Layanan Kustom: Anda dapat menentukan akun layanan Anda sendiri untuk digunakan agen. Hal ini memberi Anda kontrol yang lebih terperinci atas izin yang diberikan kepada agen.

Identitas agen

Untuk menyiapkan kebijakan IAM sebelum men-deploy agen, Anda dapat membuat identitas agen tanpa men-deploy kode agen. Untuk melakukannya, buat instance Agent Platform hanya dengan kolom identity_type:

remote_app = client.agent_engines.create(
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
      },
)

Setelah membuat instance Agent Platform dengan identitas agen, Anda dapat melakukan hal berikut:

1. Berikan peran tambahan kepada identitas agen sesuai kebutuhan untuk kasus penggunaan Anda.

2. Tambahkan kode agen menggunakan agent_engine.update(...).

Agen Layanan Default

Agen Layanan Mesin Penalaran Platform AI digunakan secara default. Anda dapat melihat daftar lengkap izin default di dokumentasi IAM.

Jika agen Anda memerlukan izin di luar set default, Anda dapat memberikan peran tambahan kepada Agen Layanan ini:

1. Buka halaman IAM, lalu centang kotak "Sertakan pemberian peran yang disediakan Google".

   Buka IAM

2. Temukan akun utama yang cocok dengan [e-mail].

3. Tambahkan peran yang diperlukan ke akun utama dengan mengklik tombol edit, lalu tombol simpan.

Membuat agen layanan default secara manual

Meskipun Agen Layanan Mesin Penalaran disediakan secara otomatis selama deployment Agent Runtime, mungkin ada skenario saat Anda perlu membuatnya secara manual terlebih dahulu. Hal ini sangat penting jika Anda perlu memberikan peran tertentu kepada agen layanan untuk memastikan proses deployment memiliki izin yang diperlukan dan menghindari potensi kegagalan deployment.

Berikut adalah langkah-langkah untuk membuat Agen Layanan Mesin Penalaran secara manual:

1. Buat Agen Layanan Mesin Penalaran menggunakan Google Cloud CLI.

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

   Catatan: Respons terhadap perintah Google Cloud CLI mungkin hanya menampilkan Agen Layanan Vertex AI. Namun, Agen Layanan Reasoning Engine juga dibuat.

2. Buka halaman IAM, lalu klik Grant Access.

   Buka IAM

3. Di bagian Add principals, di kolom New principals, masukkan [e-mail].

4. Di bagian Assign roles, temukan dan pilih peran yang Anda perlukan.

5. Klik tombol Save.

Akun layanan kustom

Untuk menggunakan akun layanan Anda sendiri, Anda harus memberinya izin yang diperlukan untuk menjalankan agen. Akun layanan kustom Anda kemungkinan memerlukan peran Agent Platform User (roles/aiplatform.user).

1. Jika Anda tidak memiliki akun layanan, buat akun layanan. Lihat Membuat akun layanan.

2. Berikan peran Agent Platform User (roles/aiplatform.user) ke akun layanan.

3. Berikan peran lain yang diperlukan oleh kode agen Anda ke akun layanan.

4. Untuk men-deploy agen dengan akun layanan ini, berikan peran Service Account User (roles/iam.serviceAccountUser) kepada diri Anda sendiri di akun layanan kustom ini.

5. Saat men-deploy agen, tentukan alamat email akun layanan kustom Anda. Lihat Mengonfigurasi akun layanan kustom untuk mengetahui detailnya.

Akun layanan kustom lintas project

Jika akun layanan kustom Anda berasal dari project yang berbeda, Anda memerlukan konfigurasi tambahan di project tempat akun layanan berada dan project tempat Anda men-deploy agen.

1. Nonaktifkan kebijakan organisasi penggunaan akun layanan lintas project: Dalam project tempat akun layanan berada, pastikan kebijakan organisasi iam.disableCrossProjectServiceAccountUsage TIDAK diterapkan. Lihat Menonaktifkan penerapan penggunaan akun layanan lintas project untuk mengetahui detail selengkapnya.

2. Berikan izin ke Agen Layanan Agent Platform: Dalam project tempat akun layanan berada, berikan peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) kepada Agen Layanan Agent Platform ([e-mail]) dari project tempat Anda berencana men-deploy agen.

3. Memberikan izin ke akun layanan kustom: Di project tempat Anda berencana men-deploy agen, berikan peran yang diperlukan ke akun layanan kustom. Hal ini biasanya mencakup peran Agent Platform User (roles/aiplatform.user) dan peran lain yang diperlukan oleh kode agen Anda.

(Opsional) Membuat bucket Cloud Storage

Kebutuhan akan bucket Cloud Storage bergantung pada apakah Agent Platform SDK untuk Python memerlukan tempat untuk melakukan staging kode agen Anda sebelum deployment:

• Men-deploy dari file sumber: Agen ada sebagai file. Agent Platform SDK for Python dapat memaketkan dan mengupload file ini langsung ke layanan deployment, sehingga tidak memerlukan bucket staging Cloud Storage.

• Men-deploy dari objek agen: Agen ada dalam memori. Agent Platform SDK for Python mengemas objek ini dan menguploadnya ke bucket Cloud Storage, yang berfungsi sebagai area staging untuk layanan deployment.

Men-deploy dari file sumber

Jika Anda men-deploy agen dari file sumber, bucket Cloud Storage tidak diperlukan.

Men-deploy dari objek

Saat Anda men-deploy dari objek agen, Agent Runtime akan melakukan staging artefak agen yang di-deploy di bucket Cloud Storage sebagai bagian dari proses deployment. Pastikan akun utama yang diautentikasi untuk menggunakan Gemini Enterprise Agent Platform (baik Anda sendiri maupun akun layanan) memiliki akses Storage Admin ke bucket ini. Hal ini diperlukan karena Agent Platform SDK untuk Python menulis kode Anda ke bucket ini.

Jika sudah menyiapkan bucket, Anda dapat melewati langkah ini. Jika tidak, Anda dapat mengikuti petunjuk standar untuk membuat bucket.

Catatan: Sebaiknya buat bucket Cloud Storage di project yang sama tempat Anda men-deploy agen ke Agent Runtime. Jika Anda menggunakan bucket di project lain, Anda harus memberikan izin baca Agen Layanan Agent Platform ([e-mail]) secara manual ke bucket Cloud Storage Anda.

Minta administrator untuk memberi Anda peran IAM Storage Admin (roles/storage.admin) di project Anda.

KonsolGoogle Cloud

1. Di konsol Google Cloud , buka halaman Buckets Cloud Storage.

   Buka Buckets

2. Klik Create.
3. Di halaman Buat bucket, masukkan informasi bucket Anda. Untuk melanjutkan ke langkah berikutnya, klik Lanjutkan.
   1. Di bagian Get started, lakukan tindakan berikut:
      • Masukkan nama yang unik secara global dan memenuhi persyaratan penamaan bucket.
      • Untuk menambahkan label bucket, luaskan bagian Labels (), klik Add label, lalu tentukan key dan value untuk label Anda.
   2. Di bagian Choose where to store your data, lakukan tindakan berikut:
      1. Pilih Location type.
      2. Pilih lokasi tempat data bucket Anda disimpan secara permanen dari menu drop-down Location type.
         • Jika memilih jenis lokasi dual-region, Anda juga dapat memilih untuk mengaktifkan replikasi turbo menggunakan kotak centang yang relevan.
      3. Untuk menyiapkan replikasi lintas bucket, pilih Add cross-bucket replication via Storage Transfer Service dan ikuti langkah-langkah berikut:

         Menyiapkan replikasi lintas bucket

         1. Di menu Bucket, pilih bucket.

         2. Di bagian Replication settings, klik Configure guna mengonfigurasi setelan untuk tugas replikasi.

            Panel Configure cross-bucket replication akan muncul.

            • Untuk memfilter objek yang akan direplikasi berdasarkan awalan nama objek, masukkan awalan yang ingin Anda sertakan atau kecualikan objek, lalu klik Tambahkan awalan.
            • Untuk menetapkan kelas penyimpanan bagi objek yang direplikasi, pilih kelas penyimpanan dari menu Storage class. Jika Anda melewati langkah ini, objek yang direplikasi akan menggunakan kelas penyimpanan bucket tujuan secara default.
            • Klik Done.
   3. Di bagian Choose how to store your data, lakukan tindakan berikut:
      1. Pilih kelas penyimpanan default untuk bucket atau Autoclass untuk pengelolaan kelas penyimpanan otomatis untuk data bucket Anda.
      2. Untuk mengaktifkan namespace hierarkis, di bagian Optimalkan penyimpanan untuk workload yang memerlukan banyak data, pilih Aktifkan namespace hierarkis di bucket ini.
         Catatan: Anda tidak dapat mengaktifkan namespace hierarkis di bucket yang ada.
   4. Di bagian Choose how to control access to objects, pilih apakah bucket Anda menerapkan pencegahan akses publik atau tidak, lalu pilih metode kontrol akses untuk objek bucket Anda.
      Catatan: Anda tidak dapat mengubah setelan Prevent public access jika setelan ini diterapkan di kebijakan organisasi.
   5. Di bagian Choose how to protect object data, lakukan hal berikut:
      • Pilih salah satu opsi di bagian Perlindungan data yang ingin Anda tetapkan untuk bucket.
        • Untuk mengaktifkan penghapusan sementara, centang kotak Kebijakan penghapusan sementara (Untuk pemulihan data), dan tentukan jumlah hari yang Anda inginkan untuk mempertahankan objek setelah penghapusan.
        • Untuk menetapkan Pembuatan Versi Objek, klik kotak centang Pembuatan versi objek (Untuk kontrol versi), lalu tentukan jumlah maksimum versi per objek dan jumlah hari setelah versi lama tidak berlaku.
        • Untuk mengaktifkan kebijakan retensi pada objek dan bucket, klik kotak centang Retention (For compliance), lalu lakukan hal berikut:
          • Untuk mengaktifkan Kunci Retensi Objek, klik kotak centang Aktifkan retensi objek.
          • Untuk mengaktifkan Kunci Bucket, centang kotak Set bucket retention policy, lalu pilih satuan waktu dan lama waktu untuk periode retensi data Anda.
      • Untuk memilih cara data objek Anda akan dienkripsi, luaskan bagian Data encryption (), lalu pilih metode Data encryption.
4. Klik Create.

Command line

Buat bucket Cloud Storage dan konfigurasikan sebagai berikut:
• Ganti STORAGE_CLASS dengan kelas penyimpanan pilihan Anda.
• Ganti LOCATION dengan lokasi pilihan Anda (ASIA, EU, atau US)
• Ganti BUCKET_NAME dengan nama bucket yang memenuhi persyaratan nama bucket.

gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Menginstal dan melakukan inisialisasi Agent Platform SDK untuk Python

Bagian ini mengasumsikan bahwa Anda telah menyiapkan lingkungan pengembangan Python, atau menggunakan Colab (atau runtime lain yang sesuai dan telah disiapkan untuk Anda).

(Opsional) Menyiapkan lingkungan virtual

Sebaiknya siapkan lingkungan virtual untuk mengisolasi dependensi Anda.

Penginstalan

Untuk meminimalkan kumpulan dependensi yang harus Anda instal, kami telah memisahkan dependensi menjadi:

• agent_engines: kumpulan paket yang diperlukan untuk deployment ke Agent Runtime.
• adk: kumpulan paket Agent Development Kit (ADK) yang kompatibel.
• langchain: set paket LangChain dan LangGraph yang kompatibel.
• ag2: kumpulan paket AG2 yang kompatibel.
• llama_index: kumpulan paket LlamaIndex yang kompatibel.

Saat menginstal Agent Platform SDK untuk Python, Anda dapat menentukan dependensi yang diperlukan (dipisahkan dengan koma). Untuk menginstal semuanya:

pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.112.0

Untuk menggunakan Agent2Agent (A2A) di Agent Platform , Anda juga harus menginstal paket a2a-sdk:

pip install google-adk[a2a]

Autentikasi

Colab

Jalankan kode berikut:

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

Tindakan tidak diperlukan.

Shell Lokal

Jalankan perintah berikut:

gcloud auth application-default login

Mengimpor dan melakukan inisialisasi SDK

Jalankan kode berikut untuk mengimpor dan menginisialisasi SDK untuk Agent Runtime:

Google Cloud project

import vertexai
from vertexai import agent_engines # For the prebuilt templates

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

di mana

• PROJECT_ID adalahproject ID Google Cloud tempat Anda mengembangkan dan men-deploy agen, dan
• LOCATION adalah salah satu wilayah yang didukung.

(Opsional) Menggunakan container Anda sendiri (BYOC)

Untuk melihat contoh Bring your own container (BYOC), jalankan notebook "Deploy your containerized agent on Agent Runtime" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di Agent Platform Workbench | Lihat di GitHub

Secara default, Agent Runtime membangun container untuk Anda sebagai bagian dari proses deployment. Jika Anda ingin membangun container kustom untuk deployment, ikuti petunjuk di bagian ini.

Untuk men-deploy agen Anda dengan container kustom, selesaikan tugas tingkat tinggi berikut:

1. Membangun dan mengirim image container ke Artifact Registry.
2. Siapkan identitas dan izin untuk agen Anda.
3. Berikan peran Artifact Registry Reader ke agen layanan default Agent Runtime.

Penting: Jika Anda berencana merutekan traffic agen BYOC melalui Agent Gateway, Anda harus mengonfigurasi image container kustom untuk memercayai root certificate authority (CA) gateway. Untuk mengetahui petunjuknya, lihat Mengonfigurasi agen container kustom (BYOC) untuk Agent Gateway.

Membangun dan mengirim image container Anda

Untuk membangun dan mengirim image container, ikuti petunjuk di Membangun dan mengirim image Docker dengan Cloud Build.

Menyiapkan identitas dan izin untuk Agent Runtime

Agen layanan default Agent Runtime diperlukan untuk mengimpor container dari repositori Artifact Registry Anda.

Agen layanan otomatis dibuat di project Anda secara default. Jika belum ada, ikuti Menyiapkan identitas dan izin untuk agen Anda guna membuat dan mengonfigurasinya.

Memberikan peran Artifact Registry Reader

Berikan peran Artifact Registry Reader (roles/artifactregistry.reader) ke agen layanan default ([e-mail]).

Jalankan perintah berikut untuk memberikan peran yang diperlukan ke agen layanan default:

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
  --member="serviceAccount:[e-mail]" \
  --role="roles/artifactregistry.reader"

(Opsional) Memberikan izin lintas project

Izin lintas project diperlukan jika image container Anda disimpan di repositori Artifact Registry dalam project Google Cloud yang berbeda dengan tempat agen Anda di-deploy.

Dalam hal ini, berikan peran Artifact Registry Reader ke Agen Layanan Agent Platform ([e-mail]) di project repositori Artifact Registry Anda.

gcloud projects add-iam-policy-binding AR_REPO_PROJECT_NUMBER \
  --member="serviceAccount:[e-mail]" \
  --role="roles/artifactregistry.reader"

Langkah berikutnya

Ringkasan

Membuat agen

Pelajari cara membuat agen menggunakan Agent Platform Runtime.

Pemecahan masalah

Memecahkan masalah pembuatan agen

Pelajari cara mengatasi error umum saat membuat agen kustom.

Referensi

Dapatkan dukungan

Temukan referensi dan dukungan untuk Google Agent Platform.