Bermigrasi ke model baru

Dokumen ini menjelaskan cara memigrasikan aplikasi agen CX Agent Studio yang ada ke model dasar yang berbeda, memvalidasi kualitas agen, dan men-deploy konfigurasi yang diperbarui secara bertahap tanpa mengganggu traffic produksi langsung.

Ringkasan alur kerja migrasi

Migrasi model yang lengkap mengikuti empat tahap:

1. Isolasi perubahan Anda: Buat versi yang tidak dapat diubah dari aplikasi agen produksi Anda, atau ekspor dan impor aplikasi ke lingkungan pengujian terpisah.
2. Memperbarui setelan model: Ubah model global, tinjau penggantian model sub-agen dan alat, serta verifikasi setelan percobaan ulang dan penggantian menggunakan konsol, file konfigurasi yang diekspor, atau REST API.
3. Evaluasi dan sempurnakan performa: Uji percakapan di simulator, jalankan evaluasi dengan Temukan masalah dengan AI, dan gunakan AI Co-Builder: Arc untuk menyesuaikan petunjuk hingga metrik kualitas Anda memenuhi nilai minimum target.
4. Deploy secara bertahap: Simpan konfigurasi yang divalidasi sebagai versi dan gunakan pemisahan traffic di saluran deployment Anda untuk mengalihkan traffic aktif secara bertahap sambil memantau hasilnya.

Langkah 1: Pisahkan perubahan Anda

Sebelum mengubah setelan model, isolasi pekerjaan Anda agar update dan pengujian tidak memengaruhi percakapan pelanggan secara langsung. Anda dapat mengisolasi perubahan dengan menggunakan versi dalam aplikasi agen yang sama atau dengan mengekspor aplikasi ke lingkungan sandbox terpisah.

Menggunakan versi di aplikasi agen yang sama

Jika saluran deployment Anda mengarah ke versi tertentu yang tidak dapat diubah, pengeditan yang Anda lakukan pada draf aplikasi agen tidak akan memengaruhi traffic aktif hingga Anda membuat versi dan menetapkannya ke saluran deployment.

Untuk menyimpan snapshot dasar pengukuran dari konfigurasi Anda saat ini:

1. Buka konsol CX Agent Studio dan pilih aplikasi agen Anda.
2. Buka panel Versions di Agent Builder.
3. Klik + Create version.
4. Masukkan nama deskriptif, seperti pre-model-migration-baseline, dan deskripsi opsional, lalu klik Create.
5. Buka tab Deploy dan pastikan saluran deployment aktif Anda mengarah ke versi yang tidak dapat diubah (ditunjukkan dengan badge Live di panel Versions), bukan draf yang dapat diubah.

Mengekspor dan mengimpor ke lingkungan sandbox

Jika Anda lebih suka menguji perubahan model dalam project atau aplikasi staging terpisah, ekspor aplikasi agen Anda dan impor ke lingkungan pengujian:

1. Buka konsol CX Agent Studio dan pilih project Anda.
2. Dalam daftar aplikasi agen, buka menu untuk aplikasi Anda, lalu pilih Export.
3. Jika lingkungan sandbox Anda menggunakan dependensi eksternal yang berbeda, seperti penyimpanan data atau endpoint layanan, ekstrak arsip yang didownload, perbarui file environment.json, dan kompresi direktori ke dalam file ZIP. Untuk mengetahui informasi selengkapnya, lihat File lingkungan.
4. Di project sandbox atau aplikasi pengujian, buka menu aplikasi, pilih Impor, lalu upload arsip.
5. Opsional: Ekspor kasus pengujian evaluasi dari aplikasi sumber dan impor ke aplikasi sandbox agar Anda dapat menjalankan pengujian regresi.

Langkah 2: Perbarui setelan model

Tinjau daftar model yang didukung untuk memilih model Gemini target yang sesuai dengan modalitas agen Anda (teks atau suara). Anda dapat memperbarui setelan model menggunakan konsol, file konfigurasi yang diekspor, atau REST API.

Mengupdate model menggunakan konsol

Saat memigrasikan aplikasi agen di konsol, periksa model aplikasi global, penggantian agen individual, model alat penyimpanan data, dan setelan penggantian:

1. Mengubah model global:
   1. Di agent builder, buka Settings untuk melihat setelan aplikasi agen.
   2. Di bagian Basic > Interactions, pilih model target Anda di kolom Global model. Model ini berfungsi sebagai default untuk semua agen dalam aplikasi yang tidak menentukan penggantian.
2. Memeriksa penggantian model root dan sub-agen:
   1. Di agent builder, buka menu di panel judul agen root, lalu pilih Edit config untuk melihat setelan agen.
   2. Periksa kolom Model. Jika agen mengganti model global, pilih model target Anda atau hapus penggantian agar agen mewarisi model global.
   3. Ulangi pemeriksaan ini untuk setiap sub-agen dalam hierarki agen Anda.
3. Memeriksa model alat penyimpanan data:
   1. Jika aplikasi Anda menggunakan alat penyimpanan data, buka panel Tools dan pilih setiap alat penyimpanan data.
   2. Luaskan Advanced > Modalities dan verifikasi pilihan Rewriter model dan Summarization model untuk konfigurasi Text dan Voice.
4. Tinjau setelan percobaan ulang dan penggantian:
   1. Buka Settings untuk aplikasi agen, lalu buka Basic > Behavior > Fallback behavior.
   2. Pastikan Retries, Agent response, dan Fallback dikonfigurasi dengan tepat untuk penanganan error selama pembuatan model.

Catatan: Jika Anda memigrasikan agen suara dari gemini-composite-v1 ke gemini-composite-v2, tinjau juga perintah gaya bicara Anda dan konversikan tag inline tanda kurung siku ke tanda kurung sudut. Untuk mengetahui informasi selengkapnya, lihat Bermigrasi dari Composite V1.

Mengupdate model menggunakan file konfigurasi yang diekspor

Jika Anda mengelola aplikasi agen melalui kontrol versi atau pipeline CI/CD, Anda dapat memperbarui setelan model di arsip yang diekspor dan mengimpor ulang paket:

1. Ekstrak file ZIP aplikasi agen yang diekspor.

2. Untuk setiap direktori agen di bagian agents/<var>AGENT_NAME</var>/, buka file agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml dan perbarui kolom modelSettings.model ke ID model target:

   displayName: "AGENT_NAME"
   modelSettings:
     model: "MODEL_ID"
   instruction: "agents/AGENT_NAME/instruction.txt"
   

   Ganti kode berikut:

   • <var>AGENT_NAME</var>: nama tampilan agen.
   • <var>MODEL_ID</var>: ID model target, seperti gemini-3.5-flash atau gemini-composite-v2.

3. Kompresi direktori root menjadi file ZIP dan impor file yang diperbarui ke CX Agent Studio.

Mengupdate model menggunakan REST API

Anda dapat memperbarui ModelSettings secara terprogram di aplikasi agen dan di setiap agen menggunakan REST API CX Agent Studio.

Sebelum memanggil API, kumpulkan nilai berikut:

• <var>PROJECT_ID</var>: Project ID Google Cloud Anda.
• <var>LOCATION_ID</var>: region aplikasi agen Anda, seperti us atau eu.
• <var>APP_ID</var>: ID resource aplikasi agen Anda.
• <var>AGENT_ID</var>: ID resource agen root atau sub-agen tertentu.
• <var>MODEL_ID</var>: ID model target, seperti gemini-3.5-flash.

Untuk memperbarui model global default untuk aplikasi agen, kirim permintaan PATCH ke metode projects.locations.apps.patch dengan updateMask=modelSettings:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

Untuk memperbarui penggantian model pada setiap agen root atau sub-agen, kirim permintaan PATCH ke metode projects.locations.apps.agents.patch dengan updateMask=modelSettings:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/agents/AGENT_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

Langkah 3: Evaluasi dan sempurnakan performa agen

Model dasar dapat berbeda dalam gaya penalaran, kepatuhan terhadap petunjuk, panjang respons, dan perilaku panggilan alat. Setelah beralih model, uji agen Anda dan sempurnakan petunjuknya sebelum mengarahkan traffic pelanggan langsung ke konfigurasi yang diperbarui.

Menguji secara interaktif di simulator

Jalankan pemeriksaan awal di simulator Preview agent:

1. Buka simulator di Agent Builder, lalu klik Start new conversation.
2. Uji interaksi teks atau audio yang representatif dan pastikan agen mengikuti petunjuk, memanggil alat dengan argumen yang valid, dan beralih antar-sub-agen seperti yang diharapkan.
3. Perluas detail trace untuk setiap giliran guna memeriksa latensi langkah, input dan output alat, serta respons JSON mentah.
4. Opsional: Untuk menambahkan percakapan ke suite regresi, buka menu simulator dan pilih Save as golden.

Menjalankan evaluasi dan mendiagnosis masalah dengan AI

Gunakan evaluasi untuk mengukur performa di seluruh kasus pengujian golden, skenario, dan simulasi, serta bandingkan hasilnya dengan versi dasar pengukuran Anda:

1. Klik Evaluate di bagian atas agent builder.
2. Pilih kasus pengujian yang mencakup perjalanan penting pengguna dan varian agen, lalu klik Run selected.
3. Dalam dialog run, pilih Find issues with AI, tetapkan jumlah run ke 3 atau lebih untuk analisis AI yang optimal, lalu mulai run. Untuk mengetahui informasi selengkapnya, lihat Menggunakan AI untuk meningkatkan kualitas kasus pengujian.
4. Setelah proses selesai, tinjau metrik evaluasi—termasuk kebenaran alat, kecocokan semantik, kepuasan sasaran pengguna, sasaran tercapai, halusinasi, dan tugas selesai—dan periksa giliran yang gagal atau sasaran yang tidak tercapai.
5. Di halaman hasil, klik Ask Gemini untuk meninjau loss_report yang dihasilkan, meringkas akar masalah di seluruh operasi yang gagal, dan melihat perbaikan petunjuk atau konfigurasi yang disarankan.

Petunjuk pendakian bukit dengan AI Co-Builder: Arc

Jika hasil evaluasi Anda menunjukkan regresi atau perubahan perilaku pada model target, gunakan AI Co-Builder: Arc dan helper evaluasi untuk menyempurnakan perintah Anda secara berulang:

1. Klik Arc di bagian atas pembuat agen untuk membuka AI Co-Builder.
2. Klik Select context, lalu pilih agen atau petunjuk tertentu yang perlu disesuaikan, atau lampirkan transkrip yang gagal dan laporan kerugian.
3. Minta Arc untuk memperbarui petunjuk atau deskripsi alat Anda untuk mengatasi kegagalan yang diamati sambil mempertahankan perilaku di seluruh kasus pengujian lainnya. Anda juga dapat menggunakan fitur restructure instructions untuk mengatur petunjuk ke dalam format terstruktur.
4. Jalankan kembali suite evaluasi setelah menerapkan perbaikan dan ulangi hingga semua kasus pengujian memenuhi kriteria kelulusan Anda. Untuk panduan tambahan, lihat Praktik terbaik evaluasi dan hillclimbing.

Langkah 4: Deploy secara bertahap dengan pemisahan traffic

Setelah agen yang diperbarui lulus evaluasi, luncurkan secara bertahap menggunakan versi dan pemisahan traffic deployment.

Membuat versi untuk agen yang dimigrasikan

Simpan snapshot yang tidak dapat diubah dari konfigurasi yang divalidasi:

1. Jika Anda menguji perubahan dalam aplikasi sandbox terpisah, ekspor paket aplikasi yang divalidasi dan impor ke aplikasi produksi Anda.
2. Di aplikasi produksi, buka panel Versions, lalu klik + Create version.
3. Masukkan nama dan deskripsi yang mengidentifikasi model target, seperti v2-gemini-3-5-flash, lalu klik Create.

Mengalihkan traffic langsung secara bertahap

Gunakan pemisahan traffic untuk mengarahkan sebagian kecil percakapan langsung ke versi yang dimigrasikan sebelum mempromosikannya ke 100% traffic:

1. Klik tab Deploy di bagian atas agent builder, lalu pilih saluran deployment Anda.
2. Di bagian Agent version, klik Add version dan sertakan versi produksi dasar pengukuran dan versi kandidat yang dimigrasikan.
3. Tetapkan Persentase traffic awal yang kecil ke versi kandidat (misalnya, 90% untuk versi dasar pengukuran dan 10% untuk versi kandidat, dengan total 100%), lalu simpan konfigurasi saluran. Anda juga dapat mengonfigurasi experimentConfig.versionRelease.trafficAllocations secara terprogram menggunakan REST API.
4. Memantau performa live di berbagai versi:
   • Periksa volume sesi, latensi, dan tingkat eskalasi di dasbor pemantauan.
   • Periksa transkrip live di histori percakapan.
   • Buat kueri log interaksi yang diekspor berdasarkan app_version_id di BigQuery untuk membandingkan tingkat eksekusi dan hasil alat di berbagai versi. Untuk contoh kueri SQL, lihat Menganalisis performa versi di BigQuery.
5. Setelah Anda mengonfirmasi stabilitas dan kualitas, tingkatkan persentase traffic untuk versi yang dimigrasikan secara bertahap hingga menyalurkan 100% traffic aktif. Jika Anda mendeteksi masalah yang tidak terduga selama peluncuran, arahkan 100% traffic kembali ke versi dasar pengukuran atau pulihkan versi sebelumnya di panel Versions.