Ringkasan hosting agen A2A di Cloud Run

Panduan ini memberikan ringkasan tentang cara menyiapkan dan mengonfigurasi agen Agent2Agent (A2A) untuk deployment di Cloud Run. Bagian ini mencakup langkah-langkah penting seperti menyiapkan lingkungan cloud, mengonfigurasi peran Identity and Access Management (IAM) yang diperlukan, dan menyiapkan agen untuk deployment.

Sebelum memulai

Sebelum Anda mulai mengembangkan dan men-deploy agen A2A, pahami konsep dan referensi berikut:

Roadmap deployment agen A2A

Untuk men-deploy agen Anda, selesaikan langkah-langkah berikut:

Arsitektur tingkat tinggi

Inti Agen A2A adalah lapisan penayangan dan pengaturan alur kerja, seperti Cloud Run. Lapisan ini mengelola interaksi dengan model AI seperti Gemini dan Vertex AI, penyimpanan memori seperti AlloyDB dan A2A TaskStore, serta alat eksternal melalui API. Klien berinteraksi dengan agen dengan mengirim permintaan, seperti "Dapatkan Kartu Agen" atau "kirim pesan", dan menerima info terbaru tugas.

Diagram berikut mengilustrasikan arsitektur sistem Agen A2A, yang menunjukkan Klien A2A (pengguna atau agen) berinteraksi dengan Agen A2A.

Arsitektur Agen A2A yang menunjukkan interaksi klien dengan agen melalui lapisan inferensi dan orkestrasi.
Arsitektur agen A2A

Untuk mengetahui informasi tentang siklus proses permintaan A2A, lihat bagian Siklus Proses Permintaan A2A.

Peran dan izin IAM untuk agen A2A Cloud Run

Peran IAM yang dikonfigurasi dengan benar penting agar layanan Cloud Run Anda dapat berinteraksi dengan aman dengan layanan lain. Google CloudBuat akun layanan khusus dan berikan izin khusus yang tercantum di bagian berikut untuk memastikan keamanan dan efisiensi operasional.

Buat akun layanan Cloud Run

Sebelum menjalankan perintah gcloud, pastikan Anda telah diautentikasi. Jalankan perintah berikut untuk login ke akun Google Cloud Anda:

gcloud auth login

Buat akun layanan khusus untuk instance layanan A2A yang di-deploy. Gunakan perintah gcloud iam service-accounts create.

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

Ganti A2A_SERVICE_ACCOUNT_NAME dengan nama akun layanan.

Mengonfigurasi peran IAM untuk agen A2A

Tetapkan peran IAM berikut ke akun layanan Anda berdasarkan Google Cloud layanan yang berinteraksi dengan agen A2A Anda:

Akses Secret Manager untuk kredensial yang aman

  • Peran: Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • Tujuan: Mengizinkan akun layanan Cloud Run mengambil secret, seperti kredensial database, dari Secret Manager secara aman.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID." \
  --role="roles/secretmanager.secretAccessor"

Akses model Vertex AI untuk kemampuan AI

  • Peran: Vertex AI User (roles/aiplatform.user)

  • Tujuan: Diperlukan agar akun layanan Cloud Run dapat memanggil API prediksi pada model Vertex AI.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID." \
  --role="roles/aiplatform.user"

Akses instance AlloyDB untuk penyimpanan persisten (jika ada)

  • Peran: AlloyDB Client (roles/alloydb.client) dan Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • Tujuan: Memungkinkan identitas layanan Cloud Run berinteraksi dengan cluster AlloyDB untuk penyimpanan tugas persisten, yang sangat penting untuk agen A2A produksi.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID." \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID." \
  --role="roles/serviceusage.serviceUsageConsumer"

Menyiapkan agen A2A untuk deployment Cloud Run

Bagian ini menjelaskan konfigurasi yang diperlukan untuk menyiapkan agen A2A Anda agar dapat di-deploy ke Cloud Run, sehingga memastikan operasi yang aman, efisien, dan skalabel di cloud.

Mengonfigurasi secret untuk layanan Cloud Run

Berikan semua kredensial sensitif, seperti kunci API dan sandi database, ke server A2A Anda menggunakan mekanisme yang aman. Cloud Run mendukung penyediaan secret sebagai variabel lingkungan atau volume yang dipasang secara dinamis. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi secret di Cloud Run.

Misalnya, buat dan kelola secret sandi dan pengguna database dalam Google Secret Manager menggunakan gcloud CLI. Untuk mengetahui informasi selengkapnya, lihat Membuat secret.

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

Membuat Dockerfile untuk containerisasi

Cloud Run dapat men-deploy layanan baik dari image container yang sudah dihosting maupun langsung dari kode sumber Anda. Saat men-deploy dari kode sumber, Cloud Run akan otomatis mem-build image container jika ada Dockerfile di direktori root project Anda.

Berikut adalah contoh Dockerfile untuk deployment agen A2A:

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

Men-deploy dari kode sumber tanpa Dockerfile

Untuk repositori kode sumber tanpa Dockerfile, Cloud Run menawarkan dukungan bawaan untuk bahasa pemrograman populer tertentu, sehingga menyederhanakan proses pembuatan container.

Langkah berikutnya