Membangun dan men-deploy agen ADK di Cloud Run

1. Pengantar

Lab ini berfokus pada implementasi dan deployment layanan agen klien. Anda akan menggunakan Agent Development Kit (ADK) untuk membangun agen AI yang menggunakan alat.

Dalam lab ini, kita akan membangun agen kebun binatang yang menggunakan Wikipedia untuk menjawab pertanyaan tentang hewan.

Terakhir, kita akan men-deploy agen pemandu tur ke Google Cloud Run, bukan hanya menjalankannya secara lokal.

Prasyarat

• Project Google Cloud yang mengaktifkan penagihan.

Yang akan Anda pelajari

• Cara menyusun project Python untuk deployment ADK.
• Cara mengimplementasikan agen yang menggunakan alat dengan google-adk.
• Cara men-deploy aplikasi Python sebagai container serverless ke Cloud Run.
• Cara mengonfigurasi autentikasi layanan ke layanan yang aman menggunakan peran IAM.
• Cara menghapus resource Cloud untuk menghindari biaya pada masa mendatang.

Yang Anda butuhkan

• Akun Google Cloud dan Project Google Cloud
• Browser web seperti Chrome

2. Mengapa harus men-deploy ke Cloud Run?

Cloud Run adalah pilihan yang tepat untuk menghosting agen ADK karena merupakan platform serverless, yang berarti Anda dapat berfokus pada kode dan bukan pada pengelolaan infrastruktur yang mendasarinya. Kami menangani pekerjaan operasional untuk Anda.

Bayangkan Cloud Run seperti toko pop-up: toko ini hanya buka dan menggunakan resource saat pelanggan (permintaan) datang. Jika tidak ada pelanggan, toko akan tutup sepenuhnya, dan Anda tidak perlu membayar toko yang kosong.

Fitur Utama

Menjalankan Container di Mana Saja:

• Anda menyediakan container (image Docker) yang berisi aplikasi Anda.
• Cloud Run menjalankannya di infrastruktur Google.
• Tidak ada masalah penskalaan, penyiapan VM, atau patching OS.

Penskalaan Otomatis:

• Jika tidak ada orang yang menggunakan aplikasi Anda, tidak ada pula instance yang berjalan (turun ke nol instance yang hemat biaya).
• Jika ada 1.000 permintaan masuk, Cloud Run akan menjalankan salinan sebanyak yang diperlukan.

Stateless secara Default:

• Setiap permintaan dapat ditujukan ke instance yang berbeda.
• Jika Anda perlu menyimpan status, gunakan layanan eksternal seperti Cloud SQL, Firestore, atau Memorystore.

Mendukung Bahasa atau Framework Apa Pun:

• Asalkan dijalankan di container Linux, Cloud Run bisa menangani Python, Go, Node.js, Java, atau .Net.

Bayar Sesuai Penggunaan:

• Penagihan berbasis permintaan: Anda ditagih per permintaan + waktu komputasi (hingga 100 md).
• Penagihan berbasis instance: Ditagih untuk masa aktif instance penuh (tidak ada biaya per permintaan).

3. Penyiapan project

Akun Google

Jika belum memiliki Akun Google pribadi, Anda harus membuat Akun Google.

Gunakan akun pribadi, bukan akun kantor atau sekolah.

Akun kantor dan sekolah mungkin memiliki batasan yang mencegah Anda mengaktifkan API yang diperlukan untuk lab ini.

Login ke Konsol Google Cloud

Login ke Konsol Google Cloud menggunakan Akun Google pribadi.

Aktifkan Penagihan

Menyiapkan akun penagihan pribadi

Jika menyiapkan penagihan menggunakan kredit Google Cloud, Anda dapat melewati langkah ini.

Untuk menyiapkan akun penagihan pribadi, buka di sini untuk mengaktifkan penagihan di Konsol Cloud.

Beberapa Catatan:

• Menyelesaikan lab ini akan dikenai biaya kurang dari $1 USD untuk resource Cloud.
• Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource agar tidak dikenai biaya lebih lanjut.
• Pengguna baru memenuhi syarat untuk mengikuti Uji Coba Gratis senilai$300 USD.

Membuat project (opsional)

Jika Anda tidak memiliki project saat ini yang ingin digunakan untuk lab ini, buat project baru di sini.

4. Buka Cloud Shell Editor

1. Klik link ini untuk langsung membuka Cloud Shell Editor
2. Jika diminta untuk memberikan otorisasi kapan saja hari ini, klik Authorize untuk melanjutkan.
3. Jika terminal tidak muncul di bagian bawah layar, buka terminal:
   • Klik Lihat
   • Klik Terminal

5. Menetapkan project Anda

1. Di terminal, tetapkan project Anda dengan perintah ini:

   gcloud config set project [PROJECT_ID]
   

   Contoh: gcloud config set project lab-project-id-example

   Jika tidak ingat project ID, Anda dapat mencantumkan semua project ID dengan: gcloud projects list

   
2. Anda akan melihat pesan ini:

   Updated property [core/project].
   

   Jika Anda melihat WARNING dan diminta Do you want to continue (Y/n)?, berarti Anda kemungkinan telah memasukkan ID project dengan salah. Tekan n, tekan Enter, lalu coba jalankan perintah gcloud config set project lagi.

6. Mengaktifkan API

Untuk menggunakan Cloud Run, Artifact Registry, Cloud Build, Vertex AI, dan Compute Engine, Anda harus mengaktifkan API masing-masing di project Google Cloud Anda.

• Di terminal, aktifkan API:

  gcloud services enable \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    aiplatform.googleapis.com \
    compute.googleapis.com
  

  Setelah selesai dijalankan, Anda akan melihat output seperti berikut:

  Operation "operations/acat.p2-[GUID]" finished successfully.
  

Memperkenalkan API

• Cloud Run Admin API (run.googleapis.com) memungkinkan Anda menjalankan layanan frontend dan backend, tugas batch, atau situs di lingkungan yang terkelola sepenuhnya. Layanan ini menangani infrastruktur untuk men-deploy dan menskalakan aplikasi dalam container Anda.
• Artifact Registry API (artifactregistry.googleapis.com) menyediakan repositori pribadi yang aman untuk menyimpan image container Anda. Artifact Registry adalah evolusi Container Registry dan terintegrasi secara lancar dengan Cloud Run dan Cloud Build.
• Cloud Build API (cloudbuild.googleapis.com) adalah platform CI/CD serverless yang menjalankan build Anda di infrastruktur Google Cloud. Layanan ini digunakan untuk membangun image container Anda di cloud dari Dockerfile Anda.
• Vertex AI API (aiplatform.googleapis.com) memungkinkan aplikasi yang di-deploy berkomunikasi dengan model Gemini untuk melakukan tugas AI inti. Layanan ini menyediakan API terpadu untuk semua layanan AI Google Cloud.
• Compute Engine API (compute.googleapis.com) menyediakan virtual machine yang aman dan dapat disesuaikan yang berjalan di infrastruktur Google. Meskipun Cloud Run dikelola, Compute Engine API sering kali diperlukan sebagai dependensi dasar untuk berbagai resource komputasi dan jaringan.

7. Menyiapkan lingkungan pengembangan

Membuat direktori

1. Di terminal, buat direktori project dan subdirektori yang diperlukan:

   cd && mkdir zoo_guide_agent && cd zoo_guide_agent
   

2. Di terminal, jalankan perintah berikut untuk membuka direktori zoo_guide_agent di penjelajah Cloud Shell Editor:

   cloudshell open-workspace ~/zoo_guide_agent
   

3. Panel penjelajah di sebelah kiri akan dimuat ulang. Sekarang Anda akan melihat direktori yang Anda buat.
   
   

   Jika terminal menghilang saat Anda melakukan ini, Anda dapat membukanya kembali dengan mengklik View, lalu Terminal di menu atas.

   CRITICAL: Membuka ruang kerja baru akan mereset Cloud Shell Editor dan memulai ulang sesi terminal Anda. Anda harus memastikan untuk membuka kembali terminal, memverifikasi bahwa Anda berada di direktori yang benar ~/zoo_guide_agent (jalankan pwd dan cd ~/zoo_guide_agent jika perlu), dan project gcloud Anda masih dipilih (jalankan gcloud config set project [PROJECT_ID] jika perlu).

Persyaratan penginstalan

1. Jalankan perintah berikut di terminal untuk membuat file requirements.txt.

   cloudshell edit requirements.txt
   

2. Tambahkan kode berikut ke file requirements.txt yang baru dibuat

   google-adk==2.4.0
   langchain-community==0.3.27
   wikipedia==1.4.0
   

3. Di terminal, buat dan aktifkan lingkungan virtual menggunakan uv. Hal ini memastikan dependensi project Anda tidak bertentangan dengan Python sistem.

   uv venv
   source .venv/bin/activate
   

   Catatan: Jika sesi Cloud Shell Anda dimuat ulang atau Anda membuka tab terminal baru, Anda mungkin perlu mengaktifkan kembali lingkungan virtual dengan menjalankan source .venv/bin/activate.

4. Instal paket yang diperlukan ke lingkungan virtual Anda di terminal.

   uv pip install -r requirements.txt
   

Membuat Akun Layanan dan Mengonfigurasi Izin IAM

Sebelum membuat agen, Anda perlu membuat akun layanan dan mengonfigurasi izin yang diperlukan. Hal ini memastikan agen Anda dapat memanggil model Vertex AI dan Cloud Build dapat men-deploy aplikasi Anda dengan berhasil.

1. Di terminal, buat akun layanan khusus untuk layanan Cloud Run Anda:

   SA_NAME=lab-service-account
   PROJECT_ID=$(gcloud config get-value project)
   gcloud iam service-accounts create ${SA_NAME} \
       --display-name="Service Account for Zoo Agent"
   

2. Beri akun layanan peran Vertex AI User agar agen Anda dapat memanggil Gemini:

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
   

3. Konfigurasi izin Cloud Build. Karena project Google Cloud modern membatasi izin akun layanan default, Anda harus memberikan peran yang diperlukan kepada akun layanan Compute Engine default untuk membangun dan men-deploy container Anda. Jalankan perintah berikut di terminal:

   PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
   
   # Grant Artifact Registry Writer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/artifactregistry.writer"
   
   # Grant Storage Object Viewer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/storage.objectViewer"
   
   # Grant Logs Writer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/logging.logWriter"
   

Menyiapkan variabel lingkungan

Sekarang, Anda akan membuat file .env yang berisi variabel lingkungan yang digunakan oleh agen dan skrip deployment.

1. Karena Anda telah menentukan variabel dalam sesi terminal pada langkah sebelumnya, Anda dapat membuat file .env secara langsung:

   cat <<EOF > .env
   PROJECT_ID=$PROJECT_ID
   PROJECT_NUMBER=$PROJECT_NUMBER
   SA_NAME=$SA_NAME
   SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
   MODEL="gemini-3.5-flash"
   EOF
   

   Periksa file .env dan pastikan PROJECT_ID, PROJECT_NUMBER, dan SERVICE_ACCOUNT telah diberi nilai. Jika detail project tidak ada, temukan dengan menjalankan gcloud projects list. Anda dapat memverifikasi keberadaan akun layanan dengan menjalankan: gcloud iam service-accounts list.

8. Membuat Alur Kerja Agen

Buat file __init__.py

1. Buat file init.py dengan menjalankan perintah berikut di terminal:

   cloudshell edit __init__.py
   

   File ini memberi tahu Python bahwa direktori zoo_guide_agent adalah paket.
2. Tambahkan kode berikut ke file __init__.py baru:

   from . import agent
   

Buat file agent.py

1. Buat file agent.py utama dengan menempelkan perintah berikut ke terminal.

   cloudshell edit agent.py
   

2. Impor dan Penyiapan Awal: Tambahkan kode berikut ke file agent.py Anda yang saat ini kosong:

   import os
   import logging
   from dotenv import load_dotenv
   
   from google.adk import Agent
   from google.adk.agents import SequentialAgent
   from google.adk.tools.tool_context import ToolContext
   from google.adk.tools.langchain_tool import LangchainTool
   
   from langchain_community.tools import WikipediaQueryRun
   from langchain_community.utilities import WikipediaAPIWrapper
   
   import google.auth
   import google.auth.transport.requests
   import google.oauth2.id_token
   
   # --- Setup Logging and Environment ---
   
   load_dotenv()
   
   model_name = os.getenv("MODEL")
   

   Blok pertama file agent.py ini membawa semua library yang diperlukan dari ADK dan Google Cloud. Blok ini juga menyiapkan logging dan memuat variabel lingkungan dari file .env Anda, yang sangat penting untuk mengakses model dan URL server Anda.
3. Menentukan alat: Kualitas agen bergantung pada alat yang dapat digunakannya. Tambahkan kode berikut ke bagian bawah agent.py untuk menentukan alat:

   # Greet user and save their prompt
   
   def add_prompt_to_state(
       tool_context: ToolContext, prompt: str
   ) -> dict[str, str]:
       """Saves the user's initial prompt to the state."""
       tool_context.state["PROMPT"] = prompt
       logging.info(f"[State updated] Added to PROMPT: {prompt}")
       return {"status": "success"}
   
   # Configuring the Wikipedia Tool
   api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
   api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
   wikipedia_tool = LangchainTool(
       tool=WikipediaQueryRun(api_wrapper=api_wrapper)
   )
   

   Penjelasan Alat
   • add_prompt_to_state 📝: Alat ini mengingat pertanyaan pengunjung kebun binatang. Saat pengunjung bertanya, "Di mana singanya?", alat ini akan menyimpan pertanyaan spesifik itu ke memori agen sehingga agen lain dalam alur kerja tersebut tahu apa yang harus diteliti.
     Cara kerja: Alat ini adalah fungsi Python yang menulis perintah pengunjung ke dalam kamus tool_context.state yang digunakan bersama. Konteks alat ini merepresentasikan memori jangka pendek agen untuk satu percakapan. Data yang disimpan ke status oleh satu agen dapat dibaca oleh agen berikutnya dalam alur kerja tersebut.
   • LangchainTool 🌍: Alat ini memberikan pengetahuan umum tentang dunia kepada agen pemandu tur. Saat pengunjung mengajukan pertanyaan yang tidak ada dalam database kebun binatang, seperti "Apa makanan singa di alam liar?", alat ini memungkinkan agen mencari jawabannya di Wikipedia. (Anda dapat mempelajari lebih lanjut cara mengonfigurasi dan memanggil alat Wikipedia dalam panduan Menggunakan Alat Wikipedia).
     Cara kerja: Alat ini berfungsi sebagai adaptor, sehingga agen kita dapat menggunakan alat WikipediaQueryRun yang telah dibangun sebelumnya dari library LangChain.
     
     
4. Tentukan agen Spesialis: Tambahkan kode berikut ke bagian bawah agent.py untuk menentukan agen comprehensive_researcher dan response_formatter:

   # 1. Researcher Agent
   comprehensive_researcher = Agent(
       name="comprehensive_researcher",
       model=model_name,
       description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
       instruction="""
       You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
       You have access to two tools:
       1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
       2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).
   
       First, analyze the user's PROMPT.
       - If the prompt can be answered by only one tool, use that tool.
       - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
         you MUST use both tools to gather all necessary information.
       - Synthesize the results from the tool(s) you use into preliminary data outputs.
   
       PROMPT:
       { PROMPT }
       """,
       tools=[
           wikipedia_tool
       ],
       output_key="research_data" # A key to store the combined findings
   )
   
   # 2. Response Formatter Agent
   response_formatter = Agent(
       name="response_formatter",
       model=model_name,
       description="Synthesizes all information into a friendly, readable response.",
       instruction="""
       You are the friendly voice of the Zoo Tour Guide. Your task is to take the
       RESEARCH_DATA and present it to the user in a complete and helpful answer.
   
       - First, present the specific information from the zoo (like names, ages, and where to find them).
       - Then, add the interesting general facts from the research.
       - If some information is missing, just present the information you have.
       - Be conversational and engaging.
   
       RESEARCH_DATA:
       { research_data }
       """
   )
   

   • Agen comprehensive_researcher adalah "otak" operasi kami. Agen ini mengambil perintah pengguna dari State yang digunakan bersama, memeriksa Alat Wikipedia, dan memutuskan alat mana yang akan digunakan untuk menemukan jawaban.
   • Peran agen response_formatter adalah presentasi. Agen ini mengambil data mentah yang dikumpulkan oleh agen Peneliti (diteruskan melalui State) dan menggunakan kemampuan bahasa LLM untuk mengubahnya menjadi respons percakapan yang mudah dipahami.
     
5. Tentukan agen Alur kerja: Tambahkan blok kode ini ke bagian bawah agent.py untuk menentukan agen berurutan tour_guide_workflow:

   tour_guide_workflow = SequentialAgent(
       name="tour_guide_workflow",
       description="The main workflow for handling a user's request about an animal.",
       sub_agents=[
           comprehensive_researcher, # Step 1: Gather all data
           response_formatter,       # Step 2: Format the final response
       ]
   )
   

   Agen alur kerja bertindak sebagai manajer 'back-office' untuk tur kebun binatang. Agen ini menerima permintaan riset dan memastikan kedua agen yang kita tentukan di atas menjalankan tugasnya dalam urutan yang benar: riset dulu, lalu pemformatan. Urutan ini akan menciptakan proses yang terprediksi dan andal untuk menjawab pertanyaan pengunjung.
   Cara kerja: Agen ini adalah SequentialAgent, jenis agen khusus yang tidak berpikir sendiri. Tugasnya hanyalah menjalankan daftar sub_agents (peneliti dan pemformat) dalam urutan tetap, dengan otomatis meneruskan memori bersama dari satu sub-agen ke sub-agen berikutnya.
6. Menyusun alur kerja utama: Tambahkan blok kode terakhir ini ke bagian bawah agent.py untuk menentukan root_agent:

   root_agent = Agent(
       name="greeter",
       model=model_name,
       description="The main entry point for the Zoo Tour Guide.",
       instruction="""
       - Let the user know you will help them learn about the animals we have in the zoo.
       - When the user responds, use the 'add_prompt_to_state' tool to save their response.
       After using the tool, transfer control to the 'tour_guide_workflow' agent.
       """,
       tools=[add_prompt_to_state],
       sub_agents=[tour_guide_workflow]
   )
   

   Framework ADK menggunakan root_agent sebagai titik awal untuk semua percakapan baru. Peran utamanya adalah mengorkestrasi keseluruhan proses. Agen ini bertindak sebagai pengontrol awal, yang mengelola giliran pertama percakapan.
   

File agent.py lengkap

File agent.py Anda kini sudah selesai. Dengan membangunnya seperti ini, Anda dapat melihat bagaimana setiap komponen, yakni alat, agen worker, dan agen pengelola, memiliki peran spesifik dalam menciptakan sistem akhir yang cerdas.

File lengkapnya akan terlihat seperti ini:

import os
import logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

Selanjutnya adalah deployment.

9. Menyiapkan aplikasi untuk deployment

Periksa struktur akhir

Sebelum men-deploy, pastikan direktori project Anda berisi file yang benar.

• Pastikan folder zoo_guide_agent Anda terlihat seperti ini:

  zoo_guide_agent/
  ├── .env
  ├── __init__.py
  ├── agent.py
  └── requirements.txt
  

Mengonfigurasi .gcloudignore dan memuat variabel lingkungan

1. Buat file .gcloudignore di direktori zoo_guide_agent untuk mencegah upload lingkungan virtual (.venv/) dan file lain yang tidak diperlukan ke Google Cloud:

   cloudshell edit .gcloudignore
   

2. Tambahkan konten berikut ke .gcloudignore:

   .gcloudignore
   .git
   .gitignore
   .venv/
   venv/
   __pycache__/
   .env
   

3. Muat variabel lingkungan ke dalam sesi terminal Anda:

   source .env
   

   Catatan: Jika sesi Cloud Shell Anda di-refresh atau Anda membuka tab terminal baru, Anda harus menjalankan source .env lagi untuk memuat ulang variabel ini sebelum men-deploy.

10. Men-deploy agen menggunakan CLI ADK

Setelah kode lokal dan project Google Cloud Anda siap, sekarang saatnya men-deploy agen. Anda akan menggunakan perintah adk deploy cloud_run, yakni alat praktis yang mengotomatiskan seluruh alur kerja deployment. Satu perintah ini mengemas kode Anda, membangun image container, mengirimkannya ke Artifact Registry, dan meluncurkan layanan di Cloud Run, sehingga dapat diakses di web.

1. Jalankan perintah berikut di terminal untuk men-deploy agen Anda:

   # Run the deployment command
   uvx --from google-adk==2.4.0 \
   adk deploy cloud_run \
     --project=$PROJECT_ID \
     --region=europe-west1 \
     --service_name=zoo-tour-guide \
     --with_ui \
     . \
     -- \
     --allow-unauthenticated \
     --set-env-vars=MODEL=$MODEL,GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global \
     --labels=dev-tutorial=codelab-adk \
     --service-account=$SERVICE_ACCOUNT
   

   Perintah uvx memungkinkan Anda menjalankan alat command line yang dipublikasikan sebagai paket Python tanpa memerlukan penginstalan global alat tersebut.

   Catatan: Perintah deployment di bawah ini akan memerlukan waktu beberapa menit untuk selesai dijalankan.

2. Jika Anda diminta melakukan hal berikut:

   Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
   [europe-west1] will be created.
   
   Do you want to continue (Y/n)?
   

   Jika ya, ketik Y, lalu tekan ENTER.
3. Setelah berhasil dieksekusi, perintah akan memberikan URL layanan Cloud Run yang di-deploy. (Tampilannya akan terlihat seperti https://zoo-tour-guide-123456789.europe-west1.run.app).
4. Salin URL layanan Cloud Run yang di-deploy untuk tugas berikutnya.

11. Menguji agen yang di-deploy

Dengan agen Anda yang kini aktif di Cloud Run, Anda akan melakukan pengujian untuk mengonfirmasi bahwa deployment berhasil dan agen berfungsi seperti yang diharapkan. Anda akan menggunakan URL Layanan publik (seperti https://zoo-tour-guide-123456789.europe-west1.run.app/) untuk mengakses antarmuka web ADK dan berinteraksi dengan agen.

1. Buka URL Layanan Cloud Run publik di browser web Anda. Karena Anda menggunakan --with_ui flag, Anda akan melihat UI developer ADK.
2. Aktifkan Token Streaming di kanan atas.
   Sekarang Anda dapat berinteraksi dengan agen Kebun Binatang.
3. Ketik hello, lalu tekan enter untuk memulai percakapan baru.
4. Amati hasilnya. Agen akan merespons dengan cepat menggunakan sapaannya, yang akan terlihat seperti ini:

   "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
   

5. Ajukan pertanyaan kepada agen seperti:

   Where can I find the polar bears in the zoo and what is their diet?
   

   

Penjelasan Alur Agen

Sistem Anda beroperasi sebagai tim multi-agen yang cerdas. Prosesnya dikelola dengan urutan yang jelas untuk memastikan alur yang lancar dan efisien, mulai dari pertanyaan pengguna hingga jawaban akhir yang mendetail.

1. The Zoo Greeter (The Welcome Desk)

Seluruh proses dimulai dengan agen penyambut.

• Tugasnya: Memulai percakapan. Instruksinya adalah menyapa pengguna dan menanyakan hewan apa yang ingin dipelajari.
• Alatnya: Saat pengguna membalas, Greeter menggunakan alat add_prompt_to_state untuk menangkap kata-kata persisnya (misalnya, "beri tahu saya tentang singa") dan menyimpannya ke dalam memori sistem.
• Pengalihan: Setelah menyimpan perintah, kontrol langsung dialihkan ke sub-agennya, tour_guide_workflow.

2. The Comprehensive Researcher (The Super-Researcher)

Agen ini adalah langkah pertama dalam alur kerja utama dan "otak" dari operasi. Alih-alih menugaskan tim besar, kini Anda memiliki satu agen sangat terampil yang dapat mengakses semua informasi yang tersedia.

• Tugasnya: Menganalisis pertanyaan pengguna dan menyusun rencana yang cerdas. Agen ini memanfaatkan kapabilitas penggunaan alat di model bahasa untuk memutuskan apakah ia memerlukan:
  • Pengetahuan umum dari web (melalui Wikipedia API).
  • Atau keduanya jika menangani pertanyaan kompleks.

3. The Response Formatter (The Presenter)

Setelah Comprehensive Researcher mengumpulkan semua fakta, agen ini dijalankan terakhir.

• Tugasnya: Bertindak sebagai figur ramah Pemandu Tur Kebun Binatang. Agen ini mengambil data mentah (yang bisa berasal dari satu atau kedua sumber) dan menyempurnakannya.
• Tindakannya: Agen ini menyintesis semua informasi menjadi satu jawaban yang kohesif dan menarik. Sesuai instruksinya, agen ini menyajikan terlebih dahulu informasi kebun binatang yang spesifik, lalu menambahkan fakta umum yang menarik.
• Hasil Akhir: Teks yang dihasilkan oleh agen ini merupakan jawaban lengkap dan mendetail yang dilihat pengguna di jendela percakapan.

Jika Anda tertarik untuk mempelajari lebih lanjut cara membangun Agen, lihat referensi berikut:

1. Dokumentasi ADK
2. Membangun Alat Kustom Untuk Agen ADK

12. Membersihkan lingkungan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource tersebut, atau simpan project dan hapus setiap resource.

Menghapus layanan, image, dan resource Cloud Run

Jika ingin mempertahankan project Google Cloud, tetapi menghapus resource tertentu yang dibuat di lab ini, Anda harus menghapus layanan yang sedang berjalan, registry image container, bucket penyimpanan sumber sementara, dan akun layanan.

• Jalankan perintah berikut di terminal:

  gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
  gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet
  gsutil rm -r gs://run-sources-${PROJECT_ID}-europe-west1
  gcloud iam service-accounts delete lab-service-account@${PROJECT_ID}.iam.gserviceaccount.com --quiet
  

Menghapus project (Opsional)

Jika Anda membuat project baru khusus untuk lab ini dan tidak berencana menggunakannya lagi, cara termudah untuk melakukan pembersihan adalah dengan menghapus seluruh project. Tindakan ini memastikan semua resource (termasuk Akun Layanan dan artefak build tersembunyi) dihapus sepenuhnya.

• Di terminal, jalankan perintah berikut (ganti [YOUR_PROJECT_ID] dengan project ID Anda yang sebenarnya)

  gcloud projects delete $PROJECT_ID
  

  Menghapus project tidak dapat dibatalkan. Pastikan project ini tidak digunakan untuk pekerjaan lain sebelum melanjutkan.

13. Selamat

Anda telah berhasil membangun dan men-deploy aplikasi AI multiagen ke Google Cloud.

Rangkuman

Dalam lab ini, Anda beralih dari direktori kosong ke layanan AI yang aktif dan dapat diakses publik. Berikut tampilan yang telah Anda buat:

• Anda membuat tim khusus: Alih-alih menggunakan satu AI generik, Anda membuat "Peneliti" untuk menemukan fakta dan "Pemformat" untuk menyempurnakan jawaban.
• Anda memberi mereka alat: Anda menghubungkan agen Anda ke dunia luar menggunakan Wikipedia API.
• Anda telah mengirimkannya: Anda telah mengambil kode Python lokal dan men-deploy-nya sebagai container serverless di Cloud Run, serta mengamankannya dengan Akun Layanan khusus.

Yang telah kita bahas

• Cara menyusun project Python untuk deployment dengan ADK.
• Cara menerapkan alur kerja multi-agen menggunakan [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/).
• Cara mengintegrasikan alat eksternal seperti Wikipedia API.
• Cara men-deploy agen ke Cloud Run menggunakan perintah adk deploy.

14. Survei

Output:

Bagaimana Anda akan menggunakan tutorial ini?

Hanya membacanya Membaca dan menyelesaikan latihannya