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

Pratinjau — The Python buildpack supports default entrypoint detection for the Agent Development Kit (ADK) framework google-adk

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Framework Agent Development Kit (ADK) menyederhanakan pembuatan, evaluasi, dan deployment agen AI. ADK menyediakan pendekatan modular yang mengutamakan kode untuk membangun agen yang dapat melakukan penalaran, membuat rencana, dan menggunakan alat.

Tutorial ini menunjukkan cara membangun dan men-deploy agen AI ke Cloud Run menggunakan ADK untuk Python. Agen ini mengambil laporan cuaca untuk kota yang Anda tentukan.

Untuk mengetahui informasi selengkapnya tentang cara menghosting agen ADK menggunakan Google Cloud CLI, lihat Men-deploy ke Cloud Run dalam dokumentasi ADK.

Tujuan

• Tulis aplikasi contoh untuk menentukan weather-agent.
• Deploy agen ke Cloud Run dari sumber.
• Jalankan agen Anda untuk meminta informasi cuaca.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih sebagai berikut:

• Artifact Registry
• Cloud Build
• Cloud Run
• Vertex AI

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Sebelum memulai

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.

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.

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.

1. Enable the Cloud Run Admin API, Vertex AI API, and Cloud Build APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

2. Siapkan lingkungan pengembangan Cloud Run di Google Cloud project Anda.
3. Instal ADK dengan mengikuti petunjuk dalam dokumentasi Agent Development Kit.

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

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk men-deploy agen AI ke Cloud Run, minta administrator untuk memberi Anda peran IAM berikut:

• Cloud Run Source Developer (roles/run.sourceDeveloper) di project
• Vertex AI User (roles/aiplatform.user) di project
• Pengguna Akun Layanan (roles/iam.serviceAccountUser) di identitas layanan
• Logs Viewer (roles/logging.viewer) di project

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.

Menulis aplikasi contoh

Untuk menulis aplikasi di Python:

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

   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.0-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. Dalam direktori kode sumber Anda (parent_folder), deploy ke Cloud Run menggunakan perintah berikut:

   gcloud beta 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 memulai.

   Lalu tunggu sebentar sampai proses deployment selesai. Jika berhasil, command line akan menampilkan URL layanannya. Buka /list-apps dari URL layanan Anda. Contoh, https://weather-agent-123456789101.us-central1.run.app/list-apps.

Menjalankan agen Anda

Untuk membuat kueri agen ADK, jalankan 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": 42}'
   

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.

Berhasil: Anda men-deploy agen AI menggunakan Agent Development Kit ke Cloud Run.

Pembersihan

Agar tidak menimbulkan biaya tambahan pada akun Google Cloud Anda, hapus semua resource yang Anda deploy dengan tutorial ini.

Menghapus project

Jika Anda membuat project baru untuk tutorial ini, hapus project tersebut. Jika Anda menggunakan project yang ada dan perlu mempertahankannya tanpa perubahan yang Anda tambahkan dalam tutorial ini, hapus resource yang Anda buat untuk tutorial.

Cara termudah untuk menghilangkan penagihan adalah dengan menghapus project yang Anda buat untuk tutorial.

Untuk menghapus project:

Peringatan: Menghapus project akan mengakibatkan:

• Semua hal dalam project akan dihapus. Jika Anda menggunakan project yang ada untuk mengerjakan tugas di dokumen ini, saat Anda menghapusnya, pekerjaan lain dalam project tersebut juga akan dihapus.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin juga membuat project ID kustom yang masih ingin digunakan pada masa mendatang. Agar tidak kehilangan URL yang menggunakan project ID tersebut, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

Jika Anda berencana mempelajari berbagai arsitektur, tutorial, atau panduan memulai, project dapat digunakan kembali agar Anda tidak melampaui batas kuota project.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Menghapus resource tutorial

1. Hapus layanan Cloud Run yang Anda deploy dalam tutorial ini. Layanan Cloud Run tidak menimbulkan biaya hingga menerima permintaan.

   Untuk menghapus layanan Cloud Run, jalankan perintah berikut:

   gcloud run services delete SERVICE-NAME

   Ganti SERVICE-NAME dengan nama layanan Anda.

   Anda juga dapat menghapus layanan Cloud Run dari konsolGoogle Cloud .

2. Hapus konfigurasi region default gcloud yang Anda tambahkan selama penyiapan tutorial:

    gcloud config unset run/region
   

3. Hapus konfigurasi project:

    gcloud config unset project