Panduan memulai: Membangun dan men-deploy agen AI ke Cloud Run menggunakan Agent Development Kit (ADK)

Pelajari cara menggunakan satu perintah untuk membangun dan men-deploy agen AI ke Cloud Run menggunakan Agent Development Kit (ADK) untuk Python. Agen yang Anda deploy mengambil laporan cuaca untuk kota yang Anda tentukan.

Dengan mengikuti langkah-langkah dalam panduan memulai ini, Cloud Run akan otomatis membuat Dockerfile untuk Anda saat Anda men-deploy dari kode sumber.

Untuk mengetahui informasi selengkapnya tentang cara buildpack Python menentukan titik entri default untuk deployment sumber Cloud Run, lihat Membangun aplikasi Python.

Sebelum memulai

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

  2. Instal Google Cloud CLI.

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

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

    gcloud init

  5. Buat atau pilih Google Cloud project.

    Peran yang diperlukan untuk memilih atau membuat project

    • Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
    • Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

    • Buat Google Cloud project:

      gcloud projects create PROJECT_ID

      Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

    • Pilih project Google Cloud yang Anda buat:

      gcloud config set project PROJECT_ID

      Ganti PROJECT_ID dengan nama project Google Cloud Anda.

  6. Jika Anda menggunakan project yang sudah ada untuk panduan ini, pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini. Jika berhasil membuat project baru, berarti Anda sudah memiliki izin yang diperlukan.

  7. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

  8. Instal Google Cloud CLI.

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

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

    gcloud init

  11. Buat atau pilih Google Cloud project.

    Peran yang diperlukan untuk memilih atau membuat project

    • Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
    • Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

    • Buat Google Cloud project:

      gcloud projects create PROJECT_ID

      Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

    • Pilih project Google Cloud yang Anda buat:

      gcloud config set project PROJECT_ID

      Ganti PROJECT_ID dengan nama project Google Cloud Anda.

  12. Jika Anda menggunakan project yang sudah ada untuk panduan ini, pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini. Jika berhasil membuat project baru, berarti Anda sudah memiliki izin yang diperlukan.

  13. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

  14. Aktifkan Cloud Run Admin API, Vertex AI API, dan Cloud Build API:

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran. 

    gcloud services enable run.googleapis.com aiplatform.googleapis.com cloudbuild.googleapis.com
  15. Instal ADK dengan mengikuti petunjuk dalam dokumentasi Agent Development Kit.

  16. Jika Anda dikenai kebijakan organisasi pembatasan domain yang membatasi pemanggilan yang tidak diautentikasi untuk project, Anda perlu mengakses layanan yang di-deploy seperti yang dijelaskan di bagian Menguji layanan pribadi.

  17. Tinjau harga Cloud Run atau perkirakan biaya dengan kalkulator harga.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan panduan memulai ini, 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.

Memberi akun layanan Cloud Build akses ke project Anda

Cloud Build otomatis menggunakan akun layanan default Compute Engine sebagai akun layanan Cloud Build default untuk membangun kode sumber dan resource Cloud Run Anda, kecuali jika Anda mengganti perilaku ini.

Agar Cloud Build dapat membangun sumber Anda, berikan peran Cloud Run Builder (roles/run.builder) di project Anda kepada akun layanan Cloud Build:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

Ganti PROJECT_ID dengan project ID Google Cloud Anda dan SERVICE_ACCOUNT_EMAIL_ADDRESS dengan alamat email akun layanan Cloud Build. Jika Anda menggunakan akun layanan default Compute Engine sebagai akun layanan Cloud Build, gunakan format berikut untuk alamat email akun layanan:

PROJECT_NUMBER-compute@developer.gserviceaccount.com

Ganti PROJECT_NUMBER dengan nomor project Google Cloud Anda.

Untuk mengetahui petunjuk mendetail tentang cara menemukan project ID dan nomor project Anda, lihat Membuat dan mengelola project.

Pemberian peran builder Cloud Run memerlukan waktu beberapa menit untuk diterapkan.

Menulis aplikasi contoh

Untuk menulis aplikasi di Python:

  1. Buat direktori induk baru bernama parent_folder dan ubah direktori ke dalamnya:

    mkdir parent_folder
cd parent_folder

  2. Di direktori parent_folder, buat subdirektori baru bernama multi_tool_agent dan ubah ke direktori tersebut:

    mkdir multi_tool_agent
cd multi_tool_agent

  3. Buat file __init__.py untuk mengimpor agen:

    from . import agent

  4. Buat file agent.py untuk menentukan agen yang akan menjawab pertanyaan tentang waktu dan cuaca di kota tertentu:

    import datetime
from zoneinfo import ZoneInfo
from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city for which to retrieve the weather report.

    Returns:
        dict: status and result or error msg.
    """
    if city.lower() == "new york":
        return {
            "status": "success",
            "report": (
                "The weather in New York is sunny with a temperature of 25 degrees"
                " Celsius (77 degrees Fahrenheit)."
            ),
        }
    else:
        return {
            "status": "error",
            "error_message": f"Weather information for '{city}' is not available.",
        }

def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city.

    Args:
        city (str): The name of the city for which to retrieve the current time.

    Returns:
        dict: status and result or error msg.
    """

    if city.lower() == "new york":
        tz_identifier = "America/New_York"
    else:
        return {
            "status": "error",
            "error_message": (
                f"Sorry, I don't have timezone information for {city}."
            ),
        }

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    report = (
        f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
    )
    return {"status": "success", "report": report}

root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.5-flash",
    description=(
        "Agent to answer questions about the time and weather in a city."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the time and weather in a city."
    ),
    tools=[get_weather, get_current_time],
)

  5. Buat file .env dan tambahkan variabel berikut:

    GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=REGION

    Ganti kode berikut:

    • PROJECT_ID: Google Cloud Project ID
    • REGION: region tempat Anda berencana men-deploy layanan.

  6. Buka direktori folder induk parent_folder, lalu buat file requirements.txt untuk menambahkan dependensi google-adk:

    google-adk

    Project sumber Anda mencakup struktur berikut:

    parent_folder/
├── requirements.txt
└── multi_tool_agent/
    ├── __init__.py
    ├── agent.py
    └── .env

Aplikasi Anda sudah selesai dan siap untuk di-deploy.

Men-deploy ke Cloud Run dari sumber

Men-deploy dari sumber secara otomatis akan mem-build image container dari kode sumber dan men-deploy-nya.

  1. Di direktori kode sumber Anda (parent_folder), deploy ke Cloud Run menggunakan perintah berikut:

    gcloud run deploy --source .

    1. Saat diminta memasukkan nama layanan, tekan Enter untuk menerima nama default, misalnya weather-agent.

    2. Jika Anda diminta untuk mengaktifkan API tambahan di project, misalnya, Artifact Registry API, tanggapi dengan menekan y.

    3. Saat Anda diminta untuk memasukkan region: pilih region pilihan Anda, misalnya europe-west1.

    4. Jika Anda diminta untuk membuat repositori di region yang ditentukan, respons dengan menekan y.

    5. Jika Anda diminta untuk mengizinkan akses publik: respons y. Anda mungkin tidak melihat perintah ini jika ada kebijakan organisasi pembatasan domain yang mencegahnya; untuk mengetahui detail selengkapnya, lihat bagian Sebelum Anda memulai.

    Lalu tunggu sebentar sampai proses deployment selesai. Jika berhasil, command line akan menampilkan URL layanan agen yang di-deploy; URL tersebut akan berbentuk sebagai berikut, https://weather-agent-123456789101.us-central1.run.app/list-apps.

Menjalankan agen Anda

Untuk menggunakan agen ADK, Anda dapat menjalankan perintah curl berikut:

  1. Untuk mendapatkan daftar aplikasi, jalankan perintah berikut:

    curl -X GET SERVICE_URL/list-apps

    Ganti SERVICE_URL dengan URL layanan yang di-deploy.

  2. Untuk memulai sesi, jalankan perintah berikut:

    curl -X POST SERVICE_URL/apps/multi_tool_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": "value2"}'

  3. Untuk membuat kueri agen, jalankan perintah berikut:

    curl -X POST SERVICE_URL/run \
-H "Content-Type: application/json" \
-d "{\"appName\": \"multi_tool_agent\",\"userId\": \"u_123\",\"sessionId\": \"s_123\",\"newMessage\": { \"role\": \"user\", \"parts\": [{ \"text\": \"What's the weather in New York today?\" }]}}"

Agen akan menampilkan informasi cuaca dalam hasil kueri Anda.

Untuk mengetahui informasi dan contoh selengkapnya tentang perintah curl yang didukung, lihat Menggunakan Server API dalam dokumentasi ADK.

Pembersihan

Untuk menghindari biaya tambahan pada akun Google Cloud Anda, hapus semua resource yang Anda deploy dengan panduan memulai ini.

Menghapus repositori Anda

Cloud Run tidak mengenakan biaya saat layanan yang di-deploy tidak digunakan. Namun, Anda mungkin tetap dikenai biaya atas penyimpanan image container di Artifact Registry. Untuk menghapus repositori Artifact Registry, ikuti langkah-langkah di Menghapus repositori dalam dokumentasi Artifact Registry.

Menghapus layanan Anda

Layanan Cloud Run tidak menimbulkan biaya hingga menerima permintaan. Untuk menghapus layanan Cloud Run, ikuti salah satu langkah berikut:

Konsol

Untuk menghapus layanan:

  1. Di konsol Google Cloud , buka halaman Services Cloud Run:

    Buka Cloud Run

  2. Temukan layanan yang ingin Anda hapus dalam daftar layanan, lalu klik kotak centang layanan tersebut untuk memilihnya.

  3. Klik Hapus. Tindakan ini akan menghapus semua revisi layanan.

gcloud

Untuk menghapus layanan, jalankan perintah berikut:

gcloud run services delete SERVICE --region REGION

Ganti kode berikut:

  • SERVICE: nama layanan Anda.
  • REGION: Google Cloud region layanan.

Menghapus project pengujian Anda

Menghapus project Google Cloud akan menghentikan penagihan untuk semua resource dalam project tersebut. Untuk melepaskan semua Google Cloud resource di project Anda, ikuti langkah-langkah berikut:

    Menghapus Google Cloud project:

    gcloud projects delete PROJECT_ID

Langkah berikutnya

Untuk informasi lebih lanjut dalam mem-build container dari kode sumber dan penerapan untuk repositori, lihat: