Membangun Sistem Multi-Agen dengan ADK

1. Pengantar

Ringkasan

Lab ini mengajarkan cara mengatur sistem multi-agen yang kompleks menggunakan Agent Development Kit (ADK) Google. Anda akan beralih dari hierarki agen sederhana ke pembuatan alur kerja kolaboratif yang otomatis.

Yang akan Anda build

Anda akan membangun dua sistem multi-agen yang berbeda:

• Agen perencanaan perjalanan sederhana yang mempelajari cara mengalihkan percakapan antara agen "brainstorming" dan agen "perencanaan tempat wisata".
• Generator ide film yang lebih canggih yang menggunakan "ruang penulis" agen otomatis (seperti peneliti, penulis skenario, dan kritikus) untuk bekerja sama dalam loop guna membuat plot film lengkap.

Yang akan Anda pelajari

• Cara membuat hubungan induk dan sub-agen.
• Cara menulis data ke sesi state dari alat.
• Cara membaca dari state menggunakan pembuatan template kunci (misalnya, {my_key?}).
• Cara menggunakan SequentialAgent untuk alur kerja langkah demi langkah.
• Cara menggunakan LoopAgent untuk membuat siklus penyempurnaan iteratif.
• Cara menggunakan ParallelAgent untuk menjalankan tugas independen secara serentak.

2. Sistem Multi-Agen

Agent Development Kit (ADK) memungkinkan developer mendapatkan perilaku multi-langkah yang lebih andal dan canggih dari model generatif. Daripada satu perintah yang kompleks, ADK memungkinkan Anda membangun alur beberapa agen yang lebih sederhana yang berkolaborasi dalam suatu masalah dengan membagi pekerjaan.

Pendekatan ini memiliki beberapa keunggulan dibandingkan dengan menggunakan satu perintah monolitik:

• Desain yang Lebih Sederhana: Lebih mudah mendesain dan mengatur alur agen kecil khusus daripada merekayasa satu perintah besar yang kompleks.
• Keandalan: Agen khusus lebih andal dalam tugas tertentu daripada satu agen besar yang kompleks.
• Kemudahan pemeliharaan: Lebih mudah untuk memperbaiki atau meningkatkan kualitas agen kecil khusus tanpa merusak bagian lain dari sistem.
• Modularitas: Agen yang dibuat untuk satu alur kerja dapat dengan mudah digunakan kembali di alur kerja lainnya.

Hierarki Agen

Di ADK, Anda mengatur agen dalam struktur hierarki. Hierarki ini penting untuk mengontrol alur percakapan, karena membatasi agen mana yang dapat "meneruskan" percakapan ke agen lain. Hal ini membuat perilaku sistem lebih mudah diprediksi dan di-debug. Berbagai manfaat yang ditawarkan antara lain:

• Desain Intuitif: Strukturnya terinspirasi oleh tim di dunia nyata, sehingga lebih mudah dipahami.
• Alur yang Dikontrol: Hierarki memberi Anda kontrol yang tepat atas delegasi tugas, yang membantu dalam proses penelusuran bug. Misalnya, struktur hierarki memastikan agen penulisan laporan yang benar dipanggil, meskipun Anda memiliki dua agen dengan deskripsi yang serupa.

Seluruh struktur dimulai dengan root_agent. Agen ini bertindak sebagai induk dan dapat memiliki satu atau beberapa sub-agen, yang pada gilirannya juga dapat menjadi induk bagi sub-agennya sendiri, sehingga membentuk pohon.

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

Menukarkan kredit Google Cloud senilai $5 (opsional)

Untuk menjalankan workshop ini, Anda memerlukan Akun Penagihan dengan sejumlah kredit. Jika Anda berencana menggunakan penagihan sendiri, Anda dapat melewati langkah ini.

1. Klik link ini dan login dengan Akun Google pribadi.Anda akan melihat tampilan seperti ini:
2. Klik tombol KLIK DI SINI UNTUK MENGAKSES KREDIT ANDA.Tindakan ini akan membawa Anda ke halaman untuk menyiapkan profil penagihan
3. Klik Konfirmasi.

Anda kini terhubung ke Akun Penagihan Uji Coba Google Cloud Platform.

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

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.

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

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

5. Mengaktifkan API

Untuk menggunakan Vertex AI API dan berinteraksi dengan model Gemini, Anda harus mengaktifkan Vertex AI API di project Google Cloud Anda.

1. Di terminal, aktifkan API:

   gcloud services enable aiplatform.googleapis.com
   

Berikut adalah bagian yang diperbarui, yang menggantikan pembuatan file manual dengan petunjuk untuk meng-clone repositori GitHub dan menginstal dependensi.

Pengantar Vertex AI SDK untuk Python

Untuk berinteraksi dengan model yang dihosting di Vertex AI dari aplikasi Python, Anda akan menggunakan Vertex AI SDK untuk Python. SDK ini menyederhanakan proses pengiriman perintah, penentuan parameter model, dan penerimaan respons tanpa perlu menangani kompleksitas panggilan API yang mendasarinya secara langsung.

Anda dapat menemukan dokumentasi lengkap untuk Vertex AI SDK untuk Python di sini: Pengantar Vertex AI SDK untuk Python | Google Cloud.

6. Menyiapkan lingkungan project

Meng-clone repo

1. Di terminal, buat clone repositori yang berisi file awal.

   git clone --depth 1 https://github.com/GoogleCloudPlatform/devrel-demos.git
   

   Flag --depth 1 hanya meng-clone versi terbaru, yang lebih cepat.
2. Di terminal, buka direktori kerja yang benar untuk lab ini.

   cd devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   

Mengaktifkan lingkungan virtual

3. Di terminal, buat dan aktifkan lingkungan virtual menggunakan uv:

   uv venv
   source .venv/bin/activate
   

4. Di terminal, instal google-adk dan dependensi lainnya dari file requirements.txt:

   uv pip install -r requirements.txt
   

Meninjau struktur file Anda

Setelah semua file Anda dibuat, buka folder adk_multiagent_systems di explorer untuk melihat struktur lengkapnya.

1. Di menu Cloud Shell Editor, pilih File > Open Folder....
   
   
2. Di kotak yang muncul, tambahkan informasi folder berikut setelah nama pengguna Anda: devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems/. Klik Oke.
   Tampilannya akan seperti ini:
   
   
3. Panel explorer di sebelah kiri akan dimuat ulang. Sekarang Anda akan melihat struktur project lengkap, dengan sub-direktori parent_and_subagents dan workflow_agents, yang siap untuk langkah berikutnya.
   

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

Menyiapkan variabel lingkungan

1. Anda sudah ada di direktori adk_multiagent_systems. Di terminal, buat file .env untuk menyimpan variabel lingkungan Anda:

   cloudshell edit .env
   

2. Tempelkan kode berikut ke dalam file .env yang terbuka di editor:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT="[YOUR-PROJECT-ID]"
   GOOGLE_CLOUD_LOCATION=global
   MODEL="gemini-2.5-flash"
   

3. Ganti [YOUR-PROJECT-ID] dengan ID Project Google Cloud Anda yang sebenarnya. (misalnya, PROJECT_ID = "google-cloud-labs")
   Jika Anda tidak dapat mengingat project ID, jalankan perintah berikut di terminal. Daftar semua project dan ID-nya akan ditampilkan.

   gcloud projects list
   

4. Di terminal, salin file .env ini ke direktori sub-agen agar mereka juga dapat mengakses variabel:

   cp .env parent_and_subagents/.env
   cp .env workflow_agents/.env
   

   Struktur file sekarang akan terlihat seperti ini:
   

7. Menjelajahi transfer antara agen induk, sub-agen, dan agen rekanan

Percakapan selalu dimulai dengan root_agent. Secara default, agen induk menggunakan description sub-agennya untuk memutuskan kapan harus mentransfer percakapan. Anda juga dapat memandu transfer ini secara eksplisit di instruction induk menggunakan name sub-agen.

Mari kita uji.

1. Di Cloud Shell Editor, buka adk_multiagent_systems/parent_and_subagents/agent.py. Perhatikan tiga agen dalam file agent.py:
   • root_agent (bernama steering): Menanyakan pertanyaan kepada pengguna untuk memutuskan sub-agen mana yang akan ditransfer. Awalnya, agen ini hanya mengandalkan description sub-agennya.
   • travel_brainstormer: Membantu pengguna mencari ide tujuan.
   • attractions_planner: Membantu pengguna membuat daftar hal yang dapat dilakukan di negara tertentu.

   Tips: Untuk membaca file agent.py dalam urutan alur percakapan, biasanya paling mudah untuk mulai membaca dari root_agent di bagian bawah dan bergerak ke atas. Hal ini karena kode Python mengharuskan kita menentukan sub-agen sebelum dapat menambahkannya ke agen.

2. Jadikan travel_brainstormer dan attractions_planner sebagai sub-agen root_agent dengan menambahkan baris berikut ke pembuatan root_agent:

       sub_agents=[travel_brainstormer, attractions_planner]
   

   Catatan: Hierarki agen hanya ditentukan oleh daftar sub_agents induk; sub-agen tidak memerlukan parameter parent.

3. Di terminal, mulai percakapan dengan agen Anda:

   cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   adk run parent_and_subagents
   

4. Pada perintah [user]: di terminal, ketik:

   hello
   

   Contoh output (Output Anda mungkin sedikit berbeda):

   [steering]: Hi there! Do you already have a country in mind for your trip, or would you like some help deciding where to go?
   

5. Sekarang, beri tahu agen di terminal:

   I could use some help deciding.
   

   Contoh output (Output Anda mungkin sedikit berbeda):

   [travel_brainstormer]: Okay! To give you the best recommendations, I need to understand what you're looking for in a trip.
   ...
   

   Perhatikan tag [travel_brainstormer]. root_agent yang mentransfer kontrol berdasarkan hanya pada description sub-agen.
6. Di prompt user: di terminal, ketik exit, lalu tekan ENTER untuk mengakhiri percakapan.
7. Sekarang, mari kita buat lebih jelas. Di agent.py, tambahkan kode berikut ke instruction root_agent:

           If they need help deciding, send them to 'travel_brainstormer'.
           If they know what country they'd like to visit, send them to the 'attractions_planner'.
   

8. Di terminal, jalankan agen lagi:

   adk run parent_and_subagents
   

9. Pada perintah [user]: di terminal, ketik:

   hello
   

10. Jawab dengan:

    I would like to go to Japan.
    

    Contoh output (Output Anda mungkin sedikit berbeda):

    [attractions_planner]: Okay, I can help you with that! Here are some popular attractions in Japan:
    ...
    

    Perhatikan transfer ke attractions_planner, seperti yang dipandu oleh petunjuk baru Anda.
11. Sekarang balas dengan:

    Actually I don't know what country to visit.
    

    Contoh output (Output Anda mungkin sedikit berbeda):

    [travel_brainstormer]: Okay! I can help you brainstorm some countries for travel...
    

    Perhatikan bahwa Anda telah dipindahkan ke travel_brainstormer, rekan attractions_planner. Opsi ini diizinkan secara default.

    Jika Anda ingin mencegah transfer, Anda dapat menyetel disallow_transfer_to_peers=True pada agen attractions_planner.

12. Pada perintah pengguna, ketik exit untuk mengakhiri sesi.

Rekap

Di bagian ini, Anda telah mempelajari dasar-dasar hierarki agen dan alur percakapan:

• Percakapan selalu dimulai dengan root_agent.
• Agen induk dapat otomatis dialihkan ke sub-agen berdasarkan description-nya.
• Anda dapat mengontrol alur ini secara eksplisit dengan memberikan instruction induk untuk ditransfer ke sub-agen berdasarkan name-nya.
• Secara default, agen dapat mentransfer ke agen peer mereka (saudara dalam hierarki).

8. Menggunakan status sesi untuk menyimpan dan mengambil informasi

Setiap percakapan ADK memiliki Session, yang mencakup kamus status sesi. Status ini dapat diakses oleh semua agen, sehingga menjadi cara yang tepat untuk meneruskan informasi di antara agen atau mempertahankan data (seperti daftar) selama percakapan.

Untuk mempelajari cara menambahkan dan membaca dari status:

1. Kembali ke file adk_multiagent_systems/parent_and_subagents/agent.py
2. Tempel definisi fungsi berikut setelah header # Tools:

   def save_attractions_to_state(
   tool_context: ToolContext,
   attractions: List[str]
   ) -> dict[str, str]:
       """Saves the list of attractions to state["attractions"].
   
       Args:
           attractions [str]: a list of strings to add to the list of attractions
   
       Returns:
           None
       """
       # Load existing attractions from state. If none exist, start an empty list
       existing_attractions = tool_context.state.get("attractions", [])
   
       # Update the 'attractions' key with a combo of old and new lists.
       # When the tool is run, ADK will create an event and make
       # corresponding updates in the session's state.
       tool_context.state["attractions"] = existing_attractions + attractions
   
       # A best practice for tools is to return a status message in a return dict
       return {"status": "success"}
   

   Dalam kode ini, perhatikan:
   • Fungsi ini menerima tool_context: ToolContext. Objek ini adalah gateway Anda ke sesi.
   • Baris tool_context.state["attractions"] = ... membaca dan menulis langsung ke kamus status sesi. ADK akan menangani sisanya.
3. Tambahkan alat ke agen attractions_planner dengan menambahkan parameter tools:

       tools=[save_attractions_to_state]
   

4. Tambahkan poin-poin berikut ke instruction yang ada pada agen attractions_planner:

           - When they reply, use your tool to save their selected attraction and then provide more possible attractions.
           - If they ask to view the list, provide a bulleted list of { attractions? } and then suggest some more.
   

   Perhatikan bagian dalam tanda kurung kurawal: { attractions? }. Fitur ADK ini, pembuatan template kunci, menyisipkan nilai kunci attractions dari status ke dalam perintah agen. ? membuatnya opsional, sehingga mencegah error jika kunci belum ada.

5. Luncurkan UI Web Agent Development Kit dengan perintah berikut di terminal:

   adk web
   

   Output

   INFO:     Started server process [2434]
   INFO:     Waiting for application startup.
   +-------------------------------------------------------+
   | ADK Web Server started                                |
   |                                                       |
   | For local testing, access at http://localhost:8000.   |
   +-------------------------------------------------------+
   
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
   

   Catatan: Jika port 8000 sedang digunakan, Anda dapat menjalankan di port lain, misalnya: adk web --port 8001. Input nomor port pada langkah berikutnya harus diupdate agar cocok.

6. Di terminal Cloud Shell, klik Untuk melihat antarmuka web di tab baru, klik tombol Web Preview, lalu pilih Change Port.
   
7. Masukkan nomor port 8000, lalu klik Change and Preview. Tab browser baru akan terbuka dengan ADK Dev UI.
   
8. Dari dropdown Select an agent di sebelah kiri, pilih parent_and_subagents.
9. Mulai percakapan dengan: hello
10. Setelah agen menyapa Anda, balas dengan:

    I'd like to go to Egypt.
    

    Anda akan dialihkan ke attractions_planner dan diberi daftar tempat wisata.
11. Pilih tempat wisata, misalnya:

    I'll go to the Sphinx
    

12. Anda akan mendapatkan respons seperti: Oke, saya telah menyimpan The Sphinx ke daftar Anda...
13. Klik kotak alat respons (ditandai dengan tanda centang) untuk melihat acara yang dibuat dari respons alat.
    Perhatikan bahwa ini mencakup kolom actions yang mencakup stateDelta yang menjelaskan perubahan pada status.
14. Balas dengan objek wisata lain dari daftar agen.
15. Di menu navigasi sebelah kiri, klik "X" untuk keluar dari fokus pada peristiwa yang Anda periksa sebelumnya.
16. Di sidebar sebelah kiri, klik tab Negara Bagian. Anda kini dapat melihat array attractions dalam status sesi, yang akan berisi kedua item yang Anda pilih.
17. Kirim pesan ini ke agen:

    What is on my list?
    

    Sekarang, agen akan membaca dari status dan menampilkan daftar Anda.
18. Setelah selesai bereksperimen dengan agen, tutup tab browser web dan tekan CTRL + C di Terminal Cloud Shell untuk menghentikan server.

Untuk menyimpan seluruh respons teks agen dalam status, Anda dapat menetapkan parameter output_key saat menentukan agen, dan seluruh outputnya akan disimpan dalam kamus status dengan nama kolom tersebut.

Ringkasan Bagian

Di bagian ini, Anda telah mempelajari cara menggunakan status Session untuk membagikan data:

• Untuk menulis status: Anda menulis ke kamus status dari dalam alat, menggunakan objek tool_context.state (misalnya, tool_context.state["my_list"] = [...]).
• Untuk membaca status: Anda menyuntikkan data status langsung ke instruction agen menggunakan pembuatan template kunci (misalnya, Here is your list: {my_list?}).
• Untuk memeriksa status: Anda dapat memantau status sesi secara langsung di UI Dev ADK menggunakan tab Status.

9. Agen Alur Kerja

Sejauh ini, Anda telah melihat cara agen induk mentransfer ke sub-agen, lalu menunggu pengguna. Agen alur kerja berbeda: mereka mengeksekusi sub-agennya satu per satu dalam alur otomatis, tanpa menunggu input pengguna.

Fitur ini sangat cocok untuk tugas multi-langkah otomatis seperti pipeline "Rencanakan dan Lakukan" atau "Buat Draf dan Revisi". ADK menyediakan tiga agen alur kerja bawaan untuk mengelola hal ini:

• SequentialAgent
• LoopAgent
• ParallelAgent

Bagian selanjutnya dari lab ini akan berfokus pada pembuatan sistem multi-agen menggunakan tiga agen alur kerja ini.

Anda akan membuat agen yang mengembangkan dokumen saran untuk film baru tentang tokoh sejarah. Agen Anda akan menangani riset, penulisan berulang, dan pembuatan laporan.

Pada akhirnya, sistem Anda akan terlihat seperti ini:

Anda akan membangun sistem ini selangkah demi selangkah, dimulai dengan alur kerja yang paling sederhana.

10. Membangun sistem multi-agen dengan SequentialAgent

SequentialAgent adalah agen alur kerja yang mengeksekusi sub-agennya dalam urutan linear yang sederhana. Setiap agen dalam daftar sub_agents-nya dijalankan satu per satu, secara berurutan. Hal ini sangat cocok untuk pipeline yang tugasnya harus dilakukan dalam urutan tertentu, seperti agen saran film yang akan Anda buat sekarang.

Versi pertama ini akan disusun seperti ini:

• root_agent (greeter) akan menyambut pengguna dan mendapatkan subjek film.
• Kemudian, domain akan ditransfer ke SequentialAgent bernama film_concept_team, yang akan:
  1. Jalankan agen researcher untuk mendapatkan fakta dari Wikipedia.
  2. Jalankan agen screenwriter untuk menggunakan fakta tersebut dalam menulis plot.
  3. Jalankan agen file_writer untuk menyimpan plot akhir ke file.

Mari kita jalankan.

1. Di Cloud Shell Editor, buka adk_multiagent_systems/workflow_agents/agent.py.
   Baca file definisi agen ini. Karena sub-agen harus ditentukan sebelum dapat ditetapkan ke induk, untuk membaca file sesuai urutan alur percakapan, Anda dapat membaca agen dari bagian bawah file ke bagian atas.
2. Perhatikan alat append_to_state. Fungsi helper ini memungkinkan agen menambahkan data ke daftar dalam status sesi, yang merupakan cara researcher dan screenwriter meneruskan tugasnya.
3. Coba agen. Di terminal, luncurkan antarmuka web dengan pengaktifan pemuatan ulang langsung:

   cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   adk web --reload_agents
   

   Catatan: Jika port 8000 sedang digunakan, Anda dapat menjalankan di port lain, misalnya: adk web --reload_agents --port 8001.

4. Di terminal Cloud Shell, klik Untuk melihat antarmuka web di tab baru, klik tombol Web Preview, lalu pilih Change Port.
   
5. Masukkan nomor port 8000, lalu klik Change and Preview. Tab browser baru akan terbuka dengan ADK Dev UI.
   
6. Dari dropdown Pilih agen, pilih workflow_agents.
7. Mulai percakapan dengan: hello. Agen greeter akan merespons.
8. Saat diminta, masukkan tokoh sejarah. Anda dapat menggunakan salah satu opsi ini atau opsi Anda sendiri:
   • Zhang Zhongjing
   • Ada Lovelace
   • Marcus Aurelius
9. SequentialAgent sekarang akan mengambil alih. Anda tidak akan melihat pesan perantara apa pun. researcher, screenwriter, dan file_writer akan berjalan satu demi satu. Agen hanya akan merespons setelah seluruh urutan selesai.
   Jika gagal, Anda dapat mengklik + Sesi Baru di kanan atas dan mencoba lagi.
10. Setelah agen mengonfirmasi bahwa file telah ditulis, temukan dan buka file .txt baru di direktori movie_pitches di Cloud Shell Editor Anda untuk melihat output.
11. Di UI Dev ADK, klik ikon agen terakhir dalam histori chat untuk membuka tampilan peristiwa.
12. Tampilan peristiwa menampilkan grafik visual hierarki agen. Anda dapat melihat cara greeter memanggil film_concept_team, yang kemudian memanggil setiap sub-agennya secara berurutan.
13. Anda dapat mengklik tab Permintaan dan Respons untuk setiap agen dalam grafik guna memeriksa data persis yang diteruskan, termasuk status sesi.

Catatan: Kualitas output agen ini dibatasi oleh perintah sederhananya. Dalam sistem dunia nyata, Anda akan memberikan petunjuk dan contoh yang jauh lebih ketat kepada setiap agen untuk meningkatkan keandalan.

Ringkasan Bagian

Di bagian ini, Anda telah mempelajari cara menggunakan agen alur kerja:

• SequentialAgent menjalankan sub-agennya satu per satu, secara berurutan, tanpa menunggu input pengguna di antara langkah-langkahnya.
• Ini adalah "alur kerja" karena pengguna berbicara dengan root_agent, yang kemudian menyerahkan pekerjaan ke SequentialAgent untuk diselesaikan.
• Sub-agen dalam urutan menggunakan status sesi (misalnya, { PLOT_OUTLINE? }) untuk mengakses pekerjaan agen sebelumnya.
• Anda dapat menggunakan grafik peristiwa di Dev UI untuk memvisualisasikan dan men-debug seluruh alur kerja antar-agen.

11. Menambahkan LoopAgent untuk pekerjaan berulang

LoopAgent adalah agen alur kerja yang menjalankan sub-agennya secara berurutan, lalu mengulanginya, dimulai dari awal. "Loop" ini berlanjut hingga kondisi terpenuhi, seperti mencapai jumlah max_iterations atau sub-agen memanggil alat exit_loop bawaan.

Fitur ini berguna untuk tugas yang memerlukan penyempurnaan berulang. Anda akan menambahkan LoopAgent ini untuk membuat "ruang penulis" bagi agen presentasi film Anda. Hal ini memungkinkan agen researcher, screenwriter, dan critic baru bekerja dalam loop, meningkatkan kualitas plot dengan setiap iterasi hingga critic memutuskan bahwa plot sudah siap. Hal ini juga membantu agen menangani input pengguna yang lebih tidak jelas (seperti "dokter zaman dahulu") dengan membiarkannya meneliti dan menyempurnakan ide.

Untuk melakukan perubahan ini:

1. Di adk_multiagent_systems/workflow_agents/agent.py, tambahkan impor untuk exit_loop (di dekat impor google.adk lainnya):

   from google.adk.tools import exit_loop
   

2. Tambahkan agen critic baru. Agen ini akan meninjau plot. Jika bagus, fungsi ini akan memanggil exit_loop. Jika tidak, fungsi ini akan menambahkan masukan ke status untuk loop berikutnya.
   Tempel definisi agen berikut di bagian # Agents:

   critic = Agent(
       name="critic",
       model=model_name,
       description="Reviews the outline so that it can be improved.",
       instruction="""
       INSTRUCTIONS:
       Consider these questions about the PLOT_OUTLINE:
       - Does it meet a satisfying three-act cinematic structure?
       - Do the characters' struggles seem engaging?
       - Does it feel grounded in a real time period in history?
       - Does it sufficiently incorporate historical details from the RESEARCH?
   
       If the PLOT_OUTLINE does a good job with these questions, exit the writing loop with your 'exit_loop' tool.
       If significant improvements can be made, use the 'append_to_state' tool to add your feedback to the field 'CRITICAL_FEEDBACK'.
       Explain your decision and briefly summarize the feedback you have provided.
   
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       RESEARCH:
       { research? }
       """,
       before_model_callback=log_query_to_model,
       after_model_callback=log_model_response,
       tools=[append_to_state, exit_loop]
   )
   

3. Buat LoopAgent writers_room. Bagian ini akan berisi tiga agen yang akan bekerja dalam loop.
   Tempelkan kode berikut di atas definisi agen film_concept_team:

   writers_room = LoopAgent(
       name="writers_room",
       description="Iterates through research and writing to improve a movie plot outline.",
       sub_agents=[
           researcher,
           screenwriter,
           critic
       ],
       max_iterations=5,
   )
   

   Perhatikan parameter max_iterations=5. Ini adalah jalur pengaman penting untuk mencegah loop tak terbatas, meskipun Anda memiliki kondisi keluar.

4. Perbarui SequentialAgent film_concept_team untuk menggunakan loop writers_room yang baru. Ganti researcher dan screenwriter dengan agen writers_room tunggal.Ganti definisi film_concept_team yang ada dengan yang berikut ini:

   film_concept_team = SequentialAgent(
       name="film_concept_team",
       description="Write a film plot outline and save it as a text file.",
       sub_agents=[
           writers_room,
           file_writer
       ],
   )
   

5. Kembali ke tab ADK Dev UI dan klik + New Session di kanan atas.
6. Mulai percakapan baru dengan: hello
7. Jika diminta, berikan topik yang lebih luas kepada agen kali ini. Beberapa ide:
   • seorang desainer industri yang membuat produk untuk masyarakat luas
   • kartografer (pembuat peta)
   • orang yang membuat hasil panen menghasilkan lebih banyak makanan
   Agen sekarang akan bekerja melalui loop. Di UI Dev ADK, Anda akan melihat log saat agen berjalan beberapa kali (misalnya, "[peneliti]", "[penulis naskah]", "[kritikus]", "[peneliti]", "[penulis naskah]", "[kritikus]...").
8. Setelah loop selesai, agen akan menulis file. Tinjau file yang dihasilkan di direktori adk_multiagent_systems/movie_pitches.
9. Periksa grafik peristiwa di Dev UI untuk melihat struktur loop.

Ringkasan Bagian

Di bagian ini, Anda telah mempelajari cara menggunakan LoopAgent:

• LoopAgent adalah agen alur kerja yang mengulangi urutan sub-agennya, sehingga membuat "loop dalam" untuk tugas iteratif.
• Agen di dalam loop menggunakan status sesi untuk meneruskan tugas (misalnya, PLOT_OUTLINE) dan masukan (misalnya, CRITICAL_FEEDBACK) satu sama lain pada lintasan berikutnya.
• Loop dapat dihentikan dengan mencapai batas max_iterations atau oleh agen yang memanggil alat exit_loop.

12. Menggunakan ParallelAgent untuk "fan out and gather"

ParallelAgent adalah agen alur kerja yang mengeksekusi semua sub-agennya secara bersamaan (serentak). Hal ini berguna untuk tugas yang dapat dibagi menjadi sub-tugas independen, seperti menjalankan dua tugas riset yang berbeda.

Anda akan menggunakan ParallelAgent untuk membuat "tim praproduksi" yang bekerja secara paralel. Satu agen akan meneliti potensi penjualan tiket bioskop, sementara agen lain secara bersamaan mendiskusikan ide pemilihan pemeran. Pola ini sering disebut pola "fan out and gather": ParallelAgent "membagikan" tugas, dan agen berikutnya (file_writer) "mengumpulkan" hasilnya.

Alur agen akhir Anda adalah:

1. greeter (root) memulai percakapan.
2. Proses ini akan ditransfer ke film_concept_team (SequentialAgent), yang berjalan:
   • writers_room (LoopAgent) untuk membuat plot.
   • preproduction_team (ParallelAgent) baru untuk meneliti box office dan pemilihan pemeran secara bersamaan.
   • file_writer untuk mengumpulkan semua hasil dan menyimpan file.

Untuk melakukan perubahan ini:

1. Di adk_multiagent_systems/workflow_agents/agent.py, tempelkan ParallelAgent baru dan sub-agennya di bawah header # Agents.

   box_office_researcher = Agent(
       name="box_office_researcher",
       model=model_name,
       description="Considers the box office potential of this film",
       instruction="""
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       INSTRUCTIONS:
       Write a report on the box office potential of a movie like that described in PLOT_OUTLINE based on the reported box office performance of other recent films.
       """,
       output_key="box_office_report"
   )
   
   casting_agent = Agent(
       name="casting_agent",
       model=model_name,
       description="Generates casting ideas for this film",
       instruction="""
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       INSTRUCTIONS:
       Generate ideas for casting for the characters described in PLOT_OUTLINE
       by suggesting actors who have received positive feedback from critics and/or
       fans when they have played similar roles.
       """,
       output_key="casting_report"
   )
   
   preproduction_team = ParallelAgent(
       name="preproduction_team",
       sub_agents=[
           box_office_researcher,
           casting_agent
       ]
   )
   

2. Perbarui daftar sub_agents SequentialAgent's film_concept_team untuk menyertakan preproduction_team baru (antara writers_room dan file_writer).Ganti definisi film_concept_team yang ada dengan yang berikut:

   film_concept_team = SequentialAgent(
       name="film_concept_team",
       description="Write a film plot outline and save it as a text file.",
       sub_agents=[
           writers_room,
           preproduction_team,
           file_writer
       ],
   )
   

3. Perbarui instruction agen file_writer sehingga "mengumpulkan" laporan baru dari status dan menambahkannya ke file.
   Ganti string instruction untuk file_writer dengan ini:

       instruction="""
       INSTRUCTIONS:
       - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE.
       If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one.
       - Use your 'write_file' tool to create a new txt file with the following arguments:
       - for a filename, use the movie title
       - Write to the 'movie_pitches' directory.
       - For the 'content' to write, include:
       - The PLOT_OUTLINE
       - The BOX_OFFICE_REPORT
       - The CASTING_REPORT
   
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       BOX_OFFICE_REPORT:
       { box_office_report? }
   
       CASTING_REPORT:
       { casting_report? }
       """,
   

4. Kembali ke tab UI Dev ADK, lalu klik + Sesi Baru.
5. Masukkan hello untuk memulai percakapan.
6. Jika diminta, masukkan ide karakter baru. Beberapa ide:
   • aktris yang menemukan teknologi untuk wifi
   • koki yang menarik
   • pemain kunci dalam pameran pekan raya dunia
7. Setelah agen menyelesaikan tugasnya, periksa file akhir di direktori adk_multiagent_systems/movie_pitches. Sekarang dokumen tersebut akan berisi plot, laporan box office, dan laporan casting dalam satu dokumen.

Ringkasan Bagian

Di bagian ini, Anda telah mempelajari cara menggunakan ParallelAgent:

• Pekerjaan ParallelAgent "memperluas", menjalankan semua sub-agennya secara bersamaan, bukan secara berurutan.
• Cara ini sangat efisien untuk tugas yang tidak saling bergantung (seperti meneliti dua topik yang berbeda).
• Hasil agen paralel "dikumpulkan" oleh agen berikutnya. Hal ini dilakukan dengan membuat agen paralel menyimpan pekerjaannya ke status sesi (menggunakan output_key), dan membuat agen akhir (seperti file_writer) membaca kunci tersebut.

13. Agen alur kerja kustom

Jika agen alur kerja yang telah ditentukan sebelumnya, yaitu SequentialAgent, LoopAgent, dan ParallelAgent, tidak cukup untuk memenuhi kebutuhan Anda, CustomAgent memberikan fleksibilitas untuk menerapkan logika alur kerja baru.

Anda dapat menentukan pola untuk kontrol alur, eksekusi bersyarat, atau pengelolaan status antar-sub-agen. Hal ini berguna untuk alur kerja yang kompleks, orkestrasi stateful, atau mengintegrasikan logika bisnis kustom ke dalam lapisan orkestrasi framework.

Pembuatan CustomAgent berada di luar cakupan lab ini, tetapi sebaiknya Anda mengetahui bahwa CustomAgent ada jika Anda membutuhkannya.

14. Selamat!

Anda telah berhasil membangun sistem multi-agen yang canggih menggunakan Google Agent Development Kit (ADK). Anda telah berkembang dari hubungan agen induk-turunan sederhana hingga mengatur alur kerja otomatis yang kompleks yang dapat meneliti, menulis, dan menyempurnakan project kreatif.

Rekap

Di lab ini, Anda telah melakukan hal berikut:

• Agen yang diatur dalam pohon hierarkis dengan hubungan induk dan sub-agen.
• Transfer antar-agen yang dikontrol, baik secara otomatis (menggunakan description) maupun secara eksplisit (menggunakan instruction).
• Menggunakan alat untuk menulis data ke kamus tool_context.state.
• Menggunakan pembuatan template kunci (misalnya, { PLOT_OUTLINE? }) untuk membaca dari status sesi dan memandu perintah agen.
• Menerapkan SequentialAgent untuk membuat alur kerja langkah demi langkah yang sederhana (riset -> tulis -> simpan).
• Menggunakan LoopAgent dengan agen critic dan alat exit_loop untuk membuat siklus penyempurnaan iteratif.
• Menggunakan ParallelAgent untuk "memperluas" tugas independen (seperti casting dan riset box office) agar berjalan secara bersamaan.

Melanjutkan eksperimen

Ada banyak cara untuk mengembangkan apa yang telah Anda pelajari. Berikut adalah beberapa ide:

• Menambahkan agen lainnya: Coba tambahkan agen baru ke preproduction_team ParallelAgent Anda. Misalnya, Anda dapat membuat marketing_agent yang menulis tagline untuk film berdasarkan PLOT_OUTLINE.
• Menambahkan alat lainnya: Beri agen researcher Anda lebih banyak alat. Anda dapat membuat alat yang menggunakan Google Search API untuk menemukan informasi yang tidak ada di Wikipedia.
• Jelajahi CustomAgent: Lab ini menyebutkan CustomAgent untuk alur kerja yang tidak sesuai dengan template standar. Coba buat satu yang, misalnya, menjalankan agen secara bersyarat hanya jika ada kunci tertentu dalam status sesi.