Merancang agen di Agent Studio

Halaman ini memberikan ringkasan tentang cara menggunakan Agent Studio di konsol Google Cloud .

Agent Studio adalah visual designer low-code dalam konsol Google Cloud yang menyederhanakan pengembangan agen. Anda dapat memetakan alur kerja agen secara visual, menguji respons secara real time, dan bereksperimen dengan berbagai konfigurasi sebelum men-deploy atau beralih ke kode.

Dokumen ini memberikan ringkasan Agent Studio dan menjelaskan cara menyiapkan lingkungan, membuat dan menguji agen, serta men-deploy-nya langsung ke runtime produksi.

Menyiapkan lingkungan Anda

Sebelum menggunakan Agent Studio, siapkan Google Cloud.

Mendapatkan peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna menggunakan Agent Studio, minta administrator Anda untuk memberi Anda peran IAM Agent Platform User (roles/aiplatform.user) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

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

Buat agen

Anda dapat membuat agen di Agent Studio menggunakan perintah atau alat pembuat alur.

Membuat agen menggunakan perintah

Gunakan langkah-langkah berikut untuk membuat agen menggunakan perintah:

  1. Di konsol Google Cloud , buka halaman Agen.

    Buka Agen

  2. Klik Buat agen untuk membuka kanvas Agent Studio bagi agen baru.

  3. Di kotak chat, masukkan perintah yang menjelaskan tujuan dan perilaku yang diinginkan dari agen Anda.

  4. Klik .

  5. Bergantung pada perintah Anda, salah satu hal berikut akan terjadi:

    • Berhasil: Pembuat alur akan segera diperbarui untuk menampilkan pratinjau live agen Anda, dan chat akan memberikan ringkasan modifikasi yang dilakukan. Semua perubahan akan disimpan secara otomatis.

    • Perlu klarifikasi: Jika perintah Anda ambigu, asisten akan mengajukan pertanyaan klarifikasi dalam chat untuk lebih memahami apa yang ingin Anda buat.

    • Error: Jika asisten tidak dapat menerapkan perintah Anda, pesan error akan meminta Anda untuk menyusun ulang permintaan Anda.

  6. Anda dapat terus mengupdate agen menggunakan perintah atau pembuat alur.

  7. Untuk menyimpan agen, klik Simpan di header kanvas dan ikuti perintahnya. Untuk mengetahui detailnya, lihat Menyimpan agen.

  8. Untuk menguji kemampuan dan respons agen saat Anda membangun agen, klik tab Pratinjau dan mulai percakapan dengan agen Anda.

Batasan

Batasan berikut berlaku saat Anda membuat agen menggunakan perintah:

Kemampuan Batasan
Knowledge Tidak dapat menambahkan pengetahuan ke agen. Anda dapat menggunakan antarmuka pembuat alur untuk menambahkan pengetahuan ke agen.

Membuat agen menggunakan builder alur

Gunakan langkah-langkah berikut untuk mendesain dan menguji agen menggunakan builder alur:

  1. Di konsol Google Cloud , buka halaman Agen.

    Buka Agen

  2. Klik Buat agen untuk membuka kanvas Agent Studio. untuk agen baru.

  3. Desain dan simpan agen Anda di kanvas Agent Studio. Anda dapat membuat agen utama dan menambahkan sub-agen. Agen utama selalu berupa agen lokal. Sub-agen dapat berupa agen lokal atau agen Agent Registry:

    • Agen lokal: Agen yang petunjuk, model, dan alatnya dibuat dan dikonfigurasi langsung dalam kanvas Agent Studio.
    • Agen Agent Registry: Agen yang terdaftar dan dipublikasikan di Agent Registry. Anda dapat menggunakan agen ini sebagai subagen jarak jauh dalam alur agen utama Anda.

    Saat mendesain, Anda dapat beralih antara tab Flow dan Preview berikut:

    Flow

    Buat agen utama dan sub-agen menggunakan representasi visual alur kerja dan logika kontrol agen Anda.

    1. Klik agen untuk membuka panel Detail untuk agen tersebut. Anda juga dapat mengklik Tambahkan sub-agen (+) untuk menambahkan sub-agen.

    2. Konfigurasi agen utama dan sub-agen Anda di panel Details:

      Untuk agen utama dan subagen lokal:

      1. Nama: Tambahkan nama untuk membantu mengidentifikasi agen.
      2. Deskripsi: Ringkasan tujuan agen Anda.
      3. Petunjuk: Tambahkan petunjuk untuk memandu agen Anda.
      4. Model: Pilih model untuk mendukung agen Anda.
      5. Alat: Klik Tambahkan alat (+) untuk menambahkan alat yang memungkinkan agen menyelesaikan tugas. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan dan menambahkan alat.

      Untuk sub-agen (lokal atau dari Agent Registry):

      1. Sumber sub-agen: Pilih sumber sub-agen:

        • Lokal: Buat petunjuk, model, dan alat sub-agen langsung di kanvas.
        • Agent Registry: Pilih agen terdaftar dari Agent Registry sebagai sub-agen jarak jauh. Opsi ini hanya tersedia setelah Anda menyimpan agen. Untuk mengetahui detailnya, lihat Menyimpan agen.

        Saat Anda memilih agen terdaftar, nama dan deskripsinya diimpor dari registri dan menjadi hanya baca di kanvas. Agen induk merutekan tugas ke subagen ini berdasarkan Kartu Agennya.

        Untuk menjalankan atau men-deploy agen induk, identitas agen induk harus memiliki izin untuk menemukan dan memanggil subagen A2A. Dialog izin menangani tindakan ini secara otomatis. Jika Anda perlu mengelola izin secara manual, lihat Memberikan akses untuk delegasi Agen-ke-Agen (A2A).

    3. Untuk menyimpan agen, klik Simpan di header kanvas dan ikuti perintahnya. Untuk mengetahui detailnya, lihat Menyimpan agen.

    Pratinjau

    Lakukan percakapan dengan agen Anda di panel pratinjau untuk menguji kemampuan dan responsnya.

    • Untuk melihat pratinjau agen tersimpan, Agent Studio memverifikasi izin identitas agen. Jika peran yang diperlukan tidak ada, notifikasi akan muncul. Klik Kelola untuk membuka dialog izin dan mengelola izin identitas agen.
    • Anda dapat memeriksa peristiwa dari setiap eksekusi agen untuk men-debug perilaku agen Anda. Untuk mengetahui informasi selengkapnya, lihat Memeriksa peristiwa agen.

  4. Klik Dapatkan kode untuk melihat kode agen Anda. Jika ingin melanjutkan pengembangan agen di tempat lain, Anda dapat menyalin kode dan menempelkannya ke editor kode pilihan Anda.

    Jika agen Anda menggunakan subagen jarak jauh dari Agent Registry, kode Python yang dihasilkan mencakup panggilan ke AgentRegistry.get_remote_a2a_agent untuk menyelesaikan subagen secara dinamis saat runtime.

Setelah agen Anda selesai, Anda dapat men-deploy-nya langsung dari Agent Studio. Untuk mengetahui informasi selengkapnya, lihat Men-deploy Agen dari Agent Studio.

Memeriksa peristiwa agen

Memeriksa peristiwa membantu Anda men-debug perilaku agen, serta memecahkan masalah dan melacak proses penalaran agen dan permintaan model.

Anda dapat men-debug eksekusi agen dengan memeriksa peristiwa agen di tab Pratinjau Agent Studio. Tindakan ini memungkinkan Anda mendiagnosis masalah dalam setiap peristiwa yang dihasilkan agen selama proses berjalan.

Untuk memeriksa peristiwa agen, ikuti langkah-langkah berikut:

  1. Buka agen Anda di kanvas Agent Studio dan buka tab Preview.
  2. Mulai chat dengan agen Anda di panel pratinjau untuk memulai proses.

  3. Pilih peristiwa dalam percakapan untuk membuka detailnya. Detail yang tersedia bergantung pada acara dan dapat mencakup hal berikut:

    • Penulis: Agen atau subagen yang menghasilkan peristiwa. Gunakan penulis untuk mengidentifikasi sub-agen mana yang melakukan langkah dalam alur kerja multi-agen.
    • Permintaan dan respons: Payload yang dikirim ke model dan respons yang ditampilkan.
    • Panggilan alat: Argumen yang diteruskan ke alat selama eksekusi agen.
    • Metadata: Informasi diagnostik tambahan, seperti nama model, penggunaan token, dan stempel waktu.

Jika agen menampilkan error selama pratinjau, error akan muncul di tab Pratinjau sehingga Anda dapat mendiagnosis masalah tersebut.

Menyimpan agen

Anda harus menyimpan agen sebelum dapat melihat pratinjau, men-deploy, atau mengupload file pengetahuan, karena agen yang belum disimpan belum memiliki identitas. Persyaratan ini juga berlaku untuk sub-agen Agent Registry.

Selain itu, Anda juga harus menyimpan agen sebelum menambahkan server MCP yang dipublikasikan di Agent Registry sebagai alat tingkat node.

Untuk menyimpan agen untuk pertama kalinya:

  1. Di kanvas Agent Studio, klik Simpan.

  2. Dalam dialog Simpan Agen, masukkan Nama agen.

  3. Klik Simpan.

Setelah penyimpanan pertama, Agent Studio akan otomatis menyimpan perubahan lebih lanjut yang Anda buat. Jika Anda mencoba keluar dari kanvas sebelum menyimpan agen baru, Agent Studio akan meminta Anda untuk menyimpannya terlebih dahulu.

Memperbarui agen

Gunakan langkah-langkah berikut untuk memperbarui agen:

  1. Di konsol Google Cloud , buka halaman Agen.

    Buka Agen

  2. Pada agen yang ingin Anda perbarui, klik , lalu klik Edit.

  3. Perbarui agen menggunakan perintah atau pembuat alur.

Agent Studio otomatis menyimpan perubahan Anda.

Menyiapkan dan menambahkan alat di Agent Studio

Anda dapat mengonfigurasi alat berikut untuk agen Anda:

  • Google Penelusuran: Memungkinkan agen melakukan penelusuran web menggunakan Google Penelusuran. Diaktifkan secara default.

  • Konteks URL: Memungkinkan model menganalisis URL dari perintah yang dikirim ke agen. Diaktifkan secara default.

  • Server MCP dari Agent Registry: Lampirkan server MCP yang dipublikasikan di Agent Registry sebagai alat tingkat node. Opsi ini hanya tersedia setelah Anda menyimpan agen. Untuk mengetahui detailnya, lihat Menyimpan agen.

    1. Klik Tambahkan (+) di samping Server MCP dari Agent Registry.
    2. Lokasi: Pilih wilayah untuk memfilter alat terdaftar.
    3. Server MCP: Pilih server MCP Google terdaftar dari daftar.
    4. Konfigurasi Auth: Pilih Tidak Ada untuk menggunakan akses layanan standar yang diselesaikan melalui binding IAM.
    5. Klik Tambahkan.
    6. Jika Anda menyimpan agen untuk pertama kalinya, klik Simpan di header kanvas. Perubahan berikutnya akan otomatis disimpan.

    Agen Anda dapat menggunakan semua alat di server MCP yang terhubung.

Memigrasikan alat lama

Untuk membantu menerapkan keamanan dan menstandardisasi pengelolaan alat melalui Agent Registry, Agent Studio menghentikan integrasi langsung dengan penyimpanan data Vertex AI Search dan server Model Context Protocol (MCP) langsung.

Untuk agen yang sudah ada, alat yang tidak digunakan lagi ini bersifat hanya baca. Untuk mempertahankan fungsi penuh, migrasikan ke server MCP dari Agent Registry.

Bermigrasi dari penyimpanan data Vertex AI Search lama

Jika agen Anda menggunakan alat Agent Platform Search Data Store yang tidak digunakan lagi, migrasikan ke server MCP Agent Search yang tersedia di Agent Registry. Alat ini ditampilkan sebagai discoveryengine.googleapis.com di Agent Registry.

Saat menghubungkan server MCP Agent Search, Anda harus menentukan konfigurasi penayangan target dalam petunjuk agen. Selain itu, identitas agen memerlukan izin akses.

Untuk melakukan migrasi, ikuti langkah-langkah berikut:

  1. Buka agen Anda di kanvas Agent Studio.
  2. Temukan alat Penyimpanan Data Vertex AI Search di panel Alat.
  3. Catat setelan alat, seperti project ID, lokasi, dan ID penyimpanan data.
  4. Buat agen baru dan simpan.
  5. Beri identitas agen peran Discovery Engine Viewer (roles/discoveryengine.viewer). Sebaiknya berikan peran ini langsung di aplikasi penelusuran atau penyimpanan data target. Namun, untuk tujuan pemecahan masalah, Anda dapat memberikan akses ke project. Untuk menemukan pokok identitas agen dan memberikan peran, lihat Mengelola peran secara manual. Agen juga memerlukan peran Pengguna Alat MCP (roles/mcp.toolUser), yang diberikan secara otomatis oleh dialog izin.
  6. Di panel Tools, klik Add (+) di samping MCP Server from Agent Registry.
  7. Tentukan hal berikut:
    1. Lokasi: Pilih wilayah tempat alat Anda terdaftar.
    2. Server MCP: Pilih Agent Search atau discoveryengine.googleapis.com dari daftar server MCP yang terdaftar.
    3. Konfigurasi Auth: Pilih Tidak Ada. Akses diselesaikan melalui binding IAM standar.
    4. Klik Tambahkan.

  8. Dalam petunjuk agen baru, tentukan konfigurasi penayangan target menggunakan nilai yang Anda catat pada langkah 3. Contoh:

    Use the search tool to answer questions about YOUR_TOPIC.
When using the search tool, use this servingConfig:
projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search

    Untuk aplikasi penelusuran, ganti dataStores/DATA_STORE_ID dengan engines/APP_ID. Untuk format dan argumen yang didukung, lihat Referensi Alat MCP: discoveryengine.googleapis.com.

Bermigrasi dari server MCP langsung lama

Jika agen Anda terhubung langsung ke server MCP menggunakan URL endpoint, Anda harus mendaftarkan katalog server MCP Anda terlebih dahulu di Agent Registry.

Untuk memigrasikan alat, ikuti langkah-langkah berikut:

  1. Pastikan server MCP Anda terdaftar di Agent Registry.
  2. Perbarui agen Anda di Agent Studio:
    1. Buka agen Anda di kanvas Agent Studio.
    2. Temukan dan hapus koneksi server MCP langsung lama.
    3. Klik Tambahkan (+) di samping Server MCP dari Agent Registry.
    4. Pilih server MCP terdaftar Anda dari daftar.
    5. Klik Tambahkan.
    6. Jika Anda menyimpan agen untuk pertama kalinya, klik Simpan di header kanvas. Perubahan berikutnya akan otomatis disimpan.

Melakukan grounding pada agen dengan file pengetahuan

Mengupload dokumen referensi statis untuk mendasari respons agen Anda di Agent Studio:

  1. Pilih node agen induk di kanvas tempat Anda ingin melampirkan file referensi. Perhatikan bahwa Anda tidak dapat melampirkan file pengetahuan ke sub-agen.
  2. Di panel Details node, temukan bagian Knowledge. Bagian Pengetahuan hanya muncul setelah Anda menyimpan agen untuk pertama kalinya. Untuk mengetahui detailnya, lihat Menyimpan agen.
  3. Klik komponen upload file dan jelajahi untuk memilih file referensi Anda. Anda dapat melampirkan hingga 10 file per agen. Ukuran file tidak boleh lebih dari 2 megabyte (2 MB). Kanvas upload mendukung jenis file berikut:
    • PDF
    • Teks biasa

  4. Jika Anda menyimpan agen untuk pertama kalinya, klik Simpan di header kanvas untuk menyimpan file di bucket Cloud Storage khusus dengan awalan jalur yang cocok dengan AGENT_ID agen induk. Perubahan berikutnya akan disimpan secara otomatis.

    Dialog izin memberikan peran Storage Object Viewer (roles/storage.objectViewer) ke identitas agen di bucket.

  5. Buka tab Pratinjau dan kirimkan kueri pengujian untuk memverifikasi bahwa agen mendasarkan responsnya menggunakan konten file tanpa berhalusinasi.

  6. Opsional: Anda dapat mengklik Dapatkan kode untuk menyalin kode Python yang dihasilkan (agent.py) dan memeriksa konfigurasi file perujukan. Anda dapat melewati langkah ini.

Mengelola izin identitas agen

Setiap agen di Agent Studio memiliki identitas unik, yang bertindak sebagai pokok IAM untuk mengakses resource Google Cloud lain.

Format utamanya adalah:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

Ganti kode berikut:

  • ORGANIZATION_ID: ID numerik organisasi Anda.
  • PROJECT_NUMBER: nomor project Google Cloud project Anda.
  • LOCATION: region tempat agen Anda di-deploy.
  • REASONING_ENGINE_ID: ID resource mesin penalaran Anda.

Untuk mengetahui konteks selengkapnya tentang identitas agen, lihat Membuat agen dengan identitas agen dan Ringkasan identitas agen.

Perilaku dialog izin

Saat Anda mengklik Deploy atau membuka tab Preview untuk agen yang disimpan, Agent Studio akan otomatis memeriksa apakah identitas agen memiliki serangkaian peran IAM yang diperlukan agar dapat berjalan dengan sukses. Beberapa izin yang tidak ada dapat menyebabkan agen Anda gagal jika tidak disiapkan dengan benar. Memberikan izin ini ke identitas agen akan membantu agen berfungsi sebagaimana mestinya.

Jika sistem mendeteksi masalah izin, dialog izin akan menampilkan pesan error.

  • Peran yang tidak ada: Jika peran yang diperlukan tidak ada, dialog akan muncul yang mencantumkan peran terperinci. Klik Izinkan Semua dalam dialog untuk otomatis memberikan semua peran yang diperlukan ke identitas agen dalam satu tindakan. Untuk melihat pratinjau atau men-deploy agen tanpa memberikan peran, klik Tetap lanjutkan.
  • Semua peran diberikan: Jika semua peran yang diperlukan sudah diberikan, dialog izin tidak akan muncul.
  • Agen yang belum disimpan: Agen yang belum disimpan belum memiliki identitas. Dialog izin tidak muncul, dan opsi Pratinjau dan Deploy dinonaktifkan hingga Anda menyimpan agen.

Peran yang diperlukan

Dialog izin secara otomatis memberikan daftar peran berikut:

  • roles/storage.objectViewer: Wajib diisi jika agen menggunakan file yang diupload. Peran ini harus diberikan di bucket Cloud Storage tertentu untuk file agen (misalnya, {projectNumber}_{location}_agent_studio_files).
  • roles/mcp.toolUser: Diperlukan jika agen menggunakan alat MCP Agent Registry.
  • roles/agentregistry.viewer: Diperlukan jika agen menggunakan alat atau subagen MCP Agent Registry.
  • roles/iamconnectors.user: Wajib diisi jika alat MCP Agent Registry menentukan authProviderName.
  • roles/aiplatform.viewer: Wajib diisi jika agen memanggil subagen jarak jauh melalui delegasi Agent-to-Agent (A2A).

Mengelola peran secara manual di konsol Google Cloud

Dialog izin akan otomatis memberikan peran yang diperlukan. Namun, jika Anda lebih memilih untuk mengelola peran secara manual atau perlu memecahkan masalah izin, ikuti langkah-langkah berikut:

  1. Salin principal identitas unik agen. Di header kanvas Agent Studio, klik menu drop-down di samping nama agen, lalu salin string utama.

    Format utama terlihat seperti contoh berikut:

    principal://agents.global.org-ORG_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

  2. Di konsol Google Cloud , buka IAM:

    Buka IAM

  3. Telusuri prinsipal identitas agen dalam daftar prinsipal. Anda dapat menelusuri menggunakan REASONING_ENGINE_ID tertentu dari akhir string pokok. Untuk mendapatkan akun utama identitas agen, Anda memiliki salah satu opsi berikut:

    • Jika principal identitas agen sudah tercantum, klik Edit principal di samping identitas agen.
    • Jika prinsipal identitas agen tidak tercantum, klik Berikan akses untuk menambahkannya sebagai prinsipal baru.

  4. Tambahkan atau ubah peran yang diperlukan untuk konfigurasi Anda, seperti roles/storage.objectViewer atau roles/mcp.toolUser.

  5. Klik Simpan.

Bergantung pada konfigurasi, Anda mungkin perlu memberikan peran tambahan secara manual yang tidak ditangani secara otomatis oleh dialog izin. Misalnya, jika alat MCP terdaftar Anda mengakses resource Google Cloud lainnya, seperti membuat kueri data dari BigQuery, Anda harus memberikan peran yang diperlukan secara manual, seperti peran Pelihat Data BigQuery (roles/bigquery.dataViewer), ke identitas agen.

Men-deploy agen dari Agent Studio

Setelah membuat dan melihat pratinjau agen, Anda dapat men-deploy-nya ke produksi. Gunakan langkah-langkah berikut untuk men-deploy agen dari Agent Studio:

  1. Dari halaman daftar Agen, klik agen yang ingin Anda deploy. Halaman detail Agen akan muncul untuk agen yang dipilih.

  2. Klik Deploy untuk membuka dialog Deploy ke instance Agent Runtime.

    Jika identitas agen tidak memiliki izin yang diperlukan, dialog izin akan muncul dan menangani tindakan ini secara otomatis. Jika Anda perlu mengelola izin secara manual, lihat Mengelola izin identitas agen dan Memberikan akses untuk delegasi Agen-ke-Agen (A2A).

  3. Di jendela konfigurasi deployment, konfigurasi opsi berikut:

    • Nama tampilan dan Deskripsi: Edit nama tampilan dan, jika perlu, tambahkan deskripsi untuk agen Anda.
    • Deploy sebagai A2A: Centang kotak ini untuk men-deploy agen sebagai aset Agent-to-Agent (A2A) yang dapat digunakan kembali oleh agen lain. Untuk aplikasi mandiri, jangan centang kotak untuk mengemas agen sebagai aplikasi ADK standar.

  4. Pilih region deployment dari daftar region yang tersedia, lalu klik OKE.

  5. Klik Deploy.

Deployment membuat instance runtime baru dan dapat memerlukan waktu hingga lima menit untuk selesai. Setelah berhasil, pesan akan muncul di tab Flow pada kanvas Agent Studio. Agen Anda kini tersedia dalam produksi dan dapat berintegrasi dengan aman dengan aplikasi eksternal Anda.

Melihat agen yang di-deploy

Untuk melihat agen yang di-deploy:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

  2. Gunakan daftar Region untuk memfilter menurut region deployment.

  3. Agen yang di-deploy yang merupakan bagian dari project yang dipilih akan muncul dalam daftar.

  4. Klik nama agen yang ditentukan. Halaman Metrics untuk agen akan terbuka.

  5. Pilih tab Playground untuk menguji agen Anda.

  6. Masukkan kueri pengujian di panel chat untuk memverifikasi bahwa agen berjalan dengan berhasil.

Untuk mengetahui informasi selengkapnya tentang metrik yang tersedia untuk agen Anda, lihat Melihat metrik untuk agen yang di-deploy.