Men-deploy agen A2A ke Cloud Run

Siapkan dan konfigurasi agen Agent2Agent (A2A) untuk deployment di Cloud Run.

Panduan ini mencakup langkah-langkah penting untuk men-deploy agen A2A:

Tinjau spesifikasi A2A dan agen contoh

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

Sebelum memulai

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  6. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut: 

    gcloud init

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

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  11. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut: 

    gcloud init

  12. Untuk membuat akun layanan, jalankan perintah berikut:
    13. gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

    Ganti nilai berikut:

    • A2A_SERVICE_ACCOUNT_NAME: nama akun layanan

    • DESCRIPTION: deskripsi opsional untuk akun layanan

    • DISPLAY_NAME: nama akun layanan untuk ditampilkan di konsol Google Cloud

    Memberikan peran akun layanan

    Untuk memberikan peran IAM yang diperlukan ke akun Anda di project Anda:

         gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

    Ganti:

    • PROJECT_ID: project ID Anda
    • A2A_SERVICE_ACCOUNT_NAME: nama akun layanan Anda
    • ROLE: peran yang Anda tambahkan ke akun layanan

    Peran yang diperlukan

    Untuk mendapatkan izin yang Anda perlukan guna men-deploy agen A2A, minta administrator untuk memberi Anda peran IAM berikut:

    Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

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

    Memberikan peran

    Konsol

    1. Di konsol Google Cloud , buka halaman IAM.

      Buka IAM
    2. Pilih project.
    3. Klik Grant access.

    4. Di kolom New principals, masukkan ID pengguna Anda. Ini biasanya adalah alamat email yang digunakan untuk men-deploy layanan Cloud Run.

    5. Di daftar Select a role, pilih peran.
    6. Untuk memberikan peran tambahan, klik Tambahkan peran lain, lalu tambahkan setiap peran tambahan.
    7. Klik Simpan.

    gcloud

    Untuk memberikan peran IAM yang diperlukan ke akun Anda di project Anda:

         gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

    Ganti:

    • PROJECT_NUMBER dengan nomor project Google Cloud Anda.
    • PROJECT_ID dengan project ID Google Cloud Anda.
    • PRINCIPAL dengan akun yang Anda tambahkan binding-nya. Biasanya berupa alamat email yang digunakan untuk men-deploy layanan Cloud Run.
    • ROLE dengan peran yang Anda tambahkan ke akun deployer.

    Mempersiapkan deployment Cloud Run

    Bagian ini menjelaskan konfigurasi yang diperlukan untuk menyiapkan agen A2A Anda agar dapat di-deploy ke Cloud Run untuk contoh kode Python.

    Menyiapkan agen A2A

    1. Ambil contoh kode dengan meng-clone repositori aplikasi contoh ke komputer lokal Anda:

      git clone https://github.com/a2aproject/a2a-samples

    2. Ubah ke direktori yang berisi kode contoh:

      cd a2a-samples/samples/python/agents/adk_cloud_run

    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.

    Agen memerlukan akses ke layanan eksternal untuk menyelesaikan tugas mereka. Rahasia adalah mekanisme yang aman untuk memberikan akses tersebut. Saat men-deploy dengan AlloyDB untuk PostgreSQL, Anda memerlukan pengguna dan sandi. Buat dan kelola secret sandi dan pengguna database dalam Secret Manager dengan menjalankan perintah berikut di gcloud CLI:

    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"

    Untuk mengetahui informasi selengkapnya, lihat Membuat secret.

    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.

    Dockerfile menentukan detail image container. Berikut adalah Dockerfile dari agen A2A contoh yang Anda clone sebelumnya:

    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.

    Men-deploy agen A2A ke Cloud Run

    Deploy aplikasi A2A Anda dengan konfigurasi TaskStore dalam memori atau dengan AlloyDB untuk PostgreSQL.

    • Konfigurasi TaskStore dalam memori menyimpan semua datanya secara eksklusif dalam instance penampung Cloud Run. Artinya, semua data tugas akan hilang saat instance penampung dimatikan, diskalakan, atau dimulai ulang.
    • AlloyDB untuk PostgreSQL menyediakan persistensi data, sehingga memungkinkan agen diskalakan secara horizontal, dan memastikan tugas tetap berjalan setelah dimulai ulang, peristiwa penskalaan, dan deployment.

    Konfigurasi TaskStore dalam memori cocok untuk mengembangkan agen A2A di lingkungan lokal, dan AlloyDB untuk PostgreSQL cocok untuk menskalakan agen A2A dalam produksi.

    Perintah berikut menunjukkan cara menggunakan autentikasi berbasis IAM untuk layanan Cloud Run Anda. Penggunaan flag --no-allow-unauthenticated saat deployment adalah pendekatan yang direkomendasikan untuk mengonfigurasi autentikasi bagi klien Google Cloud internal, seperti Gemini Enterprise.

    Jika server A2A Anda dirancang untuk akses publik, dan perlu menangani autentikasi tingkat agen, Anda dapat menentukan tanda --allow-unauthenticated selama deployment. Lihat Autentikasi akses publik Cloud Run untuk mengetahui detail selengkapnya. Untuk mengizinkan akses publik ke layanan Cloud Run Anda, Anda juga harus memberikan informasi autentikasi penting di kartu agen A2A menggunakan parameter securitySchemes dan security. Untuk mengetahui informasi selengkapnya, lihat Spesifikasi A2A: Detail Objek SecurityScheme.

    Men-deploy dengan konfigurasi TaskStore dalam memori

    Untuk men-deploy agen A2A dengan konfigurasi TaskStore dalam memori, jalankan perintah berikut di direktori yang berisi kode sumber agen A2A Anda:

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

    Ganti kode berikut:

    • REGION: Google Cloud region tempat Anda ingin men-deploy layanan—misalnya europe-west1.
    • PROJECT_ID: Project ID Anda.
    • PROJECT_NUMBER: nomor project Anda.
    • A2A_SERVICE_ACCOUNT_NAME: nama akun layanan A2A Anda.

    Men-deploy dengan AlloyDB untuk PostgreSQL

    Untuk mempertahankan tugas A2A, gunakan AlloyDB untuk PostgreSQL. Untuk men-deploy agen A2A dengan AlloyDB for PostgreSQL untuk penyimpanan tugas persisten, gunakan perintah berikut:

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",USE_ALLOY_DB="True",DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",DB_NAME="postgres"

    Ganti kode berikut:

    • REGION: Google Cloud region tempat Anda ingin men-deploy layanan—misalnya europe-west1.
    • PROJECT_ID: Project ID Anda.
    • PROJECT_NUMBER: nomor project Anda.
    • CLUSTER_NAME: nama cluster AlloyDB untuk PostgreSQL Anda.
    • A2A_SERVICE_ACCOUNT_NAME: nama akun layanan A2A Anda.

    Men-debug kegagalan deployment

    Jika Anda mengalami error atau kegagalan deployment Cloud Run, pertimbangkan hal berikut:

    • Log mendetail: Untuk log deployment mendetail, tetapkan tanda --verbosity=info dalam perintah gcloud run deploy Anda.

    • URL tidak cocok: Jika run.app URL yang ditampilkan oleh perintah deployment berbeda dengan URL deterministik yang diharapkan, perbarui APP_URL variabel lingkungan untuk layanan Cloud Run Anda:

      1. Gunakan perintah berikut untuk mengupdate variabel lingkungan APP_URL:

        gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

        Ganti kode berikut:

        • SERVICE_NAME: nama layanan Cloud Run Anda.
        • PROJECT_ID: Project ID Anda.
        • REGION: Google Cloud region tempat Anda ingin men-deploy layanan. Contohnya, europe-west1.
        • CLOUD_RUN_SERVICE_URL: URL layanan Cloud Run Anda.

      2. Pastikan APP_URL diperbarui dengan benar dengan menjelaskan layanan:

        gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"

    Memahami URL aplikasi Cloud Run

    Setelah deployment berhasil, Cloud Run akan otomatis menyediakan URL run.app, yang berfungsi sebagai endpoint untuk mengkueri layanan A2A aktif Anda. URL bersifat deterministik dan dapat diprediksi jika nama layanan Anda cukup pendek.

    • Format URL Cloud Run: https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
    • Contoh URL: https://sample-a2a-agent-1234.europe-west1.run.app

    Menguji dan memantau deployment agen A2A

    Setelah berhasil men-deploy agen A2A ke Cloud Run, uji fungsinya secara menyeluruh. Tetapkan praktik pemantauan yang efektif untuk memastikan performa dan keandalan yang berkelanjutan.

    Pemeriksa A2A: Memvalidasi kepatuhan agen

    Gunakan alat a2a-inspector untuk memeriksa, men-debug, dan memvalidasi agen Google A2A yang di-deploy. Alat ini memastikan bahwa agen Anda sepenuhnya mematuhi spesifikasi A2A dan berfungsi dengan benar.

    Setelah koneksi berhasil, pemeriksa akan melakukan tindakan berikut:

    • Menampilkan kartu agen: Menampilkan kartu agen Anda secara otomatis.
    • Memvalidasi kepatuhan: Memeriksa apakah kartu memenuhi spesifikasi A2A.
    • Mengaktifkan live chat: Memungkinkan Anda mengirim dan menerima pesan dengan agen.
    • Menampilkan data mentah: Menampilkan pesan JSON-RPC 2.0 mentah di konsol untuk proses debug.

    Interaksi CLI dengan agen A2A yang di-deploy

    Gunakan alat command-line interface (CLI) dari repositori contoh A2A untuk berinteraksi dengan layanan yang di-deploy. CLI ini mendukung autentikasi berbasis token pembawa.

    Jika layanan Anda menggunakan autentikasi berbasis IAM, ekspor token gcloud agar interaksi berhasil:

    export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

    Ganti CLOUD_RUN_SERVICE_URL dengan URL layanan Cloud Run yang di-deploy.

    Pengujian lokal layanan A2A yang di-deploy

    Anda dapat menguji layanan Cloud Run yang di-deploy secara lokal. Hal ini sangat berguna saat menerapkan autentikasi berbasis IAM.

    Menguji autentikasi berbasis IAM untuk agen Cloud Run

    Klien yang berinteraksi dengan layanan Cloud Run yang diamankan dengan Identity and Access Management (IAM) harus memiliki peran IAM roles/run.invoker.

    Uji alur autentikasi layanan yang di-deploy secara lokal menggunakan perintah gcloud auth print-identity-token:

    curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json

    Ganti CLOUD_RUN_SERVICE_URL dengan URL layanan Cloud Run yang di-deploy.