Jalankan evaluasi agen dengan CLI azd (pratinjau)

Important

Item-item yang ditandai sebagai (pratinjau) dalam artikel ini saat ini tersedia untuk pratinjau publik. Pratinjau ini disediakan tanpa adanya perjanjian tingkat layanan, dan kami tidak menyarankan penggunaannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

Gunakan fitur evaluasi Azure Developer CLI (azd) untuk menambahkan siklus kualitas terukur ke agen yang dibuat menggunakan Microsoft Foundry. Artikel ini berfokus pada siklus hidup agen yang dihosting di azd, tempat Anda membuat, memprovisikan, menyebarkan, menginisialisasi aset evaluasi, menjalankan evaluasi pertama, memeriksa proses eksekusi, dan menggunakan kembali resep evaluasi untuk eksekusi berikutnya.

Agen berbasis prompt juga dapat dievaluasi ketika tersedia sebagai target agen dalam proyek Foundry. Langkah-langkah penyebaran agen terhosting hanya berlaku untuk agen terhosting.

Artikel ini membahas cara menjalankan evaluasi agen pertama dengan azd ai agent eval generate dan azd ai agent eval run.

Prerequisites

Langganan Azure dengan akses ke Microsoft Foundry.
Azure Developer CLI (azd). Untuk petunjuk penginstalan, lihat Install Azure Developer CLI.
Ekstensi azd ai agent, versi 0.1.40-preview atau yang lebih baru, terinstal (azd ext install azure.ai.agents). Jika Anda tidak memiliki ekstensi yang terinstal, saat Anda menginisialisasi templat pemula atau menjalankan azd ai agent ekstensi diinstal secara otomatis. Jalankan azd ext list untuk memverifikasi versi yang diinstal, dan jalankan azd ext upgrade azure.ai.agents jika Anda perlu meningkatkan. Untuk mempelajari selengkapnya tentang azd ekstensi agen AI, lihat ekstensi agen Microsoft Foundry.
Sesi azd yang diautentikasi. Untuk memeriksa status autentikasi Anda, jalankan azd auth status. Jika Anda belum login, jalankan azd auth login.
Peran Foundry User pada sumber daya Foundry (sebelumnya bernama Azure AI User). Untuk informasi selengkapnya, lihat Kontrol akses berbasis peran untuk Microsoft Foundry.
Untuk agen yang dihosting: Tidak diperlukan proyek Foundry yang sudah ada sebelumnya. azd ai agent init dan azd provision buat sumber daya yang diperlukan.
Untuk agen berbasis prompt: Proyek Foundry yang sudah ada dengan agen yang sudah di-deploy dan tersedia sebagai target evaluasi.
Penerapan model yang mendukung penyelesaian chat dalam proyek Foundry yang sama.
Opsional: himpunan data evaluasi JSONL dengan contoh representatif, jika Anda tidak ingin eval generate menghasilkan himpunan data asap.

Cara kerja evaluasi agen azd

Pengalaman evaluasi utama CLI azd dirancang untuk siklus hidup agen yang dihosting:

azd ai agent init
azd provision
azd deploy
azd ai agent eval generate
azd ai agent eval run
azd ai agent eval update
# Optional, after the agent and eval recipe meet optimization prerequisites:
azd ai agent optimize

Alur evaluasi mencakup artefak dan perintah berikut.

Barang	Description
`eval generate`	Membuat atau memperbaiki aset evaluasi lokal untuk target agen.
`eval.yaml`	Resep evaluasi lokal yang dapat dijalankan. Mencatat target agen, referensi dataset, referensi evaluator, dan opsi generasi
Artefak lokal yang dihasilkan	Salinan lokal yang dapat diedit dari himpunan data dan rubrik evaluator yang dihasilkan. Artefak disimpan di bawah `datasets/` dan `evaluators/` di folder agen (misalnya, `src/<agent-name>/datasets/` dan `src/<agent-name>/evaluators/`).
Artefak layanan yang terdaftar	Versi dataset dan evaluator Foundry yang digunakan dalam proses evaluasi. Ini adalah sumber kebenaran untuk aset yang dihasilkan.
`eval run`	Menjalankan resep evaluasi terhadap target agen yang dipilih.
`eval update`	Mendaftarkan versi layanan baru dari dataset lokal atau hasil edit evaluator, lalu memperbarui `eval.yaml` setelah konfirmasi.
`eval list` dan `eval show`	Periksa proses evaluasi dan hasilnya melalui CLI.
`optimize --config eval.yaml`	Secara opsional memulai pengoptimalan dari resep evaluasi setelah agen dan resep memenuhi prasyarat pengoptimalan.

azd provision tidak membuat dataset evaluasi, evaluator, rangkaian, atau tugas pengoptimalan. Penyiapan evaluasi dapat melibatkan pekerjaan pembuatan yang membutuhkan waktu beberapa menit, sehingga tetap eksplisit dan dapat diulang.

Untuk agen terhosting, evaluasi pertama memerlukan target agen yang sudah di-deploy dan dapat dipanggil. Untuk agen berbasis permintaan, langkah penyebaran tidak berlaku; agen harus sudah ada di proyek Foundry dan tersedia sebagai target evaluasi.

Buat dan sebarkan agen yang dihosting

Jika Anda belum memiliki proyek agen yang dihosting, inisialisasi dengan azd:

azd ai agent init

Sediakan sumber daya Foundry dan terapkan agen:

azd provision
azd deploy

Setelah penyebaran selesai, verifikasi bahwa agen dapat dipanggil:

azd ai agent show

Agen yang dihosting harus disebarkan dan dipanggil sebelum Anda menginisialisasi aset evaluasi.

Setelah penyebaran berhasil, CLI menyarankan evaluasi sebagai langkah eksplisit berikutnya:

Set up an evaluation suite to measure quality and impact in one step with `azd ai agent eval generate`

Untuk mengevaluasi agen berbasis prompt, lewati perintah pembuatan dan penyebaran agen yang dihosting. Lanjutkan ke bagian berikutnya setelah Anda mengonfirmasi bahwa agen berbasis perintah ada di proyek Foundry dan tersedia sebagai target evaluasi.

Note

Evaluasi berbasis target memanggil agen yang dihosting secara langsung. Ini bekerja dengan agen yang menggunakan respons atau protokol pemanggilan dengan eksekusi non-streaming yang sinkron. Untuk mengevaluasi agen yang menggunakan protokol A2A atau protokol Activity, atau pola eksekusi lain seperti proses yang berjalan lama atau streaming, evaluasilah trace yang dihasilkan agen Anda sebagai gantinya. Lihat Evaluasi pelacakan.

Inisialisasi aset evaluasi

Jalankan eval generate dari ruang kerja azd atau folder proyek agen:

azd ai agent eval generate

Tanpa flag, perintah akan memulai panduan interaktif. Panduan mendeteksi target agen dari lingkungan azd, lalu meminta instruksi pembuatan agar layanan dapat membuat data evaluasi awal yang berguna dan rubrik penilaian.

Contoh output interaktif:

? Eval suite name: reservation-agent
? How would you like to provide the agent instruction?: Type inline
? Describe what this agent does and what scenarios to test: This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement.
? Include agent traces for evaluator generation?: No
? Select the model for evaluation and generation: gpt-4o (deployed)
? Max samples (between 15 and 1000): 100
  (–) Running  Evaluator generation  (evaluatorgen-reservation-agent-v3-abc12345)
  (–) Running  Dataset generation  (datagen-abc123456)
  (✓) Done  Evaluator generation  (20 seconds)
  (✓) Done  Dataset generation  (2m 9s)

Eval suite created
  Config:     src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  Evaluator dimensions (4):
    Weight  Dimension
    ──────  ─────────
        10  booking_accuracy
         5  policy_enforcement
         6  cancellation_handling
         5  general_quality

  Portal:
    Dataset:   https://ai.azure.com/.../build/data/datasets/reservation-agent-dev-eval-seed/1.0
    Evaluator: https://ai.azure.com/.../build/evaluations/catalog/reservation-agent-quality/1

  Next steps:
    azd ai agent eval run
      Run the eval suite against your agent.
    azd ai agent eval update
      Edit the generated dataset or evaluator locally, then upload changes.

Untuk penggunaan dalam skrip, berikan input generasi secara langsung:

azd ai agent eval generate \
  --gen-instruction "This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement." \
  --eval-model gpt-4o \
  --max-samples 100

--out-file bersifat opsional dan default ke eval.yaml di akar proyek agen. Gunakan --out-file <path> untuk menulis konfigurasi ke lokasi lain.

Untuk menggunakan himpunan data yang ada dan evaluator yang dipilih:

azd ai agent eval generate \
  --dataset ./tests/support-golden.jsonl \
  --gen-instruction "Support quality, policy adherence, and escalation behavior" \
  --max-samples 50 \
  --evaluator builtin.intent_resolution \
  --evaluator support-quality \
  --out-file eval.yaml

Ganti ./tests/support-golden.jsonl dengan jalur ke himpunan data evaluasi Anda sendiri.

Nilai --dataset dapat menunjuk ke file lokal atau nama himpunan data terdaftar. Ulangi --evaluator untuk menyertakan beberapa evaluator kustom bawaan atau terdaftar. Referensi evaluator menggunakan format <source>.<name>:

builtin.<name> — mereferensikan evaluator bawaan yang disediakan oleh Foundry.
<name> — mereferensikan evaluator kustom yang terdaftar dalam proyek Foundry. Gunakan nama terdaftar evaluator tanpa akhiran versi.

Tangguhkan pembuatan dengan `--no-wait`

Jika pembuatan himpunan data atau evaluator terlalu lama, gunakan --no-wait untuk mengirimkan pekerjaan pembuatan dan segera keluar:

azd ai agent eval generate \
  --gen-instruction "..." \
  --no-wait

ID operasi yang tertunda ditulis ke eval.yaml. Ketika Anda kemudian menjalankan azd ai agent eval run, sistem akan secara otomatis melanjutkan operasi tersebut sebelum memulai proses evaluasi.

Gunakan target agen berbasis prompt

Jika Anda menginisialisasi aset evaluasi untuk agen berbasis permintaan, Anda dapat menggunakan alur resep evaluasi yang sama. Langkah penyebaran agen yang dihosting tidak diperlukan untuk agen berbasis permintaan.

Sebelum Anda menjalankan evaluasi, konfirmasikan bahwa:

Agen berbasis prompt tersedia di proyek Foundry.
Agen tersedia sebagai target evaluasi.
Anda memiliki akses ke titik akhir proyek dan target agen.
eval.yaml memilih agen berbasis prompt yang dimaksud.

Untuk mencantumkan agen yang tersedia dalam proyek Foundry saat ini, jalankan:

azd ai agent list

Kemudian gunakan perintah yang sama untuk menjalankan dan memeriksa evaluasi:

azd ai agent eval run --config eval.yaml
azd ai agent eval show

Meninjau eval.yaml

Setelah eval generate berhasil, buka eval.yaml di akar proyek agen. Contohnya:

src/reservation-agent/eval.yaml

Jalankan eval run dari direktori ini, atau lewati jalur secara eksplisit dengan --config src/reservation-agent/eval.yaml. File mengidentifikasi target agen, referensi himpunan data, referensi evaluator, dan opsi pembuatan. Bentuk yang disederhanakan adalah:

name: reservation-agent
agent:
  name: reservation-agent
  kind: hosted
  version: "3"
  config: .agent_configs\baseline\metadata.yaml
dataset_reference:
  name: reservation-agent-dev-eval-seed
  version: "1.0"
  local_uri: datasets\reservation-agent-dev-eval-seed
evaluators:
  - builtin.task_adherence
  - name: reservation-agent-quality
    version: "1"
    local_uri: evaluators\reservation-agent-quality\rubric_dimensions.json
options:
  eval_model: gpt-4o
max_samples: 100

eval.yaml tinggal di akar proyek agen, misalnya src/<agent-name>/eval.yaml.
Himpunan data yang dihasilkan berada di datasets/ dan rubrik evaluator yang dihasilkan berada di evaluators/ dalam folder agen.
local_uri jalur di eval.yaml relatif terhadap direktori proyek agen.
File lokal yang dirujuk oleh local_uri dapat diedit. Jalankan azd ai agent eval update untuk mendaftarkan perubahan lokal sebagai versi baru di layanan dan menaikkan versi di eval.yaml.
eval run menggunakan versi terdaftar yang disematkan di eval.yaml. Untuk menerapkan pengeditan lokal, jalankan eval update sebelum eval run.
Evaluator dapat menjadi referensi bawaan (misalnya, builtin.task_adherence) atau evaluator kustom yang dihasilkan dengan name, , versiondan local_uri.
Perlakukan bidang versi sebagai string, bahkan jika terlihat numerik, sehingga resepnya tetap stabil di seluruh pengurai YAML.

Jalankan evaluasi

Dari folder proyek agen, jalankan:

azd ai agent eval run

Secara bawaan, eval run tanpa argumen merujuk ke eval.yaml di akar proyek agen. Anda juga dapat meneruskan jalur konfigurasi secara eksplisit:

azd ai agent eval run --config eval.yaml

Jika eval generate --no-wait membuat operasi pembuatan tertunda, eval run melanjutkan operasi tersebut sebelum memulai proses evaluasi. Ini tidak memulai himpunan data baru atau pekerjaan pembuatan evaluator dari awal.

Periksa jalannya evaluasi

Tampilkan proses evaluasi terbaru:

azd ai agent eval list

Tampilkan eksekusi terbaru:

azd ai agent eval show

Tanpa opsi, eval show secara bawaan menggunakan evaluasi terbaru dan menampilkan daftar eksekusinya.

Untuk menampilkan detail eksekusi tertentu, berikan ID eval sebagai argumen dan ID eksekusi dengan --eval-run-id. Salin ID eval dari azd ai agent eval list output dan ID eksekusi dari azd ai agent eval show <eval-id> output:

azd ai agent eval show <eval-id> --eval-run-id <run-id>

Gunakan output eksekusi untuk menjawab:

Versi agen mana yang dievaluasi.
Versi himpunan data dan evaluator mana yang berhasil diatasi.
Apakah proses selesai, gagal, atau selesai sebagian.
Metrik atau skor evaluator mana yang dihasilkan.
Apakah penggunaan token atau log evaluator perlu diselidiki.

Jalankan kembali setelah mengubah agen

Setelah Anda memperbarui dan menyebarkan ulang agen yang dihosting, jalankan resep evaluasi yang sama lagi:

azd deploy
azd ai agent eval run --config eval.yaml

Untuk agen berbasis prompt, perbarui agen di Foundry, lalu jalankan ulang resep evaluasi yang sama.

Menjalankan ulang eval.yaml yang sama membantu menjaga referensi dataset, evaluator, dan ambang batas tetap stabil meskipun terjadi perubahan agen.

Memperbarui, mengatur ulang, atau memperbaiki aset evaluasi

Alur evaluasi agen menggunakan eval.yaml sebagai resep evaluasi lokal. Gunakan azd ai agent eval update saat Anda mengedit file himpunan data lokal atau rubrik evaluator dan ingin mendaftarkan pengeditan tersebut sebagai versi layanan baru.

Untuk memperbarui apa yang digunakan eksekusi evaluasi, pilih jalur yang cocok dengan jenis perubahan:

Perubahan	Bagaimana cara memperbarui
Mengubah ambang batas, referensi evaluator, pengaturan output, atau bidang resep lainnya	Edit `eval.yaml`, lalu jalankan `azd ai agent eval run --config eval.yaml`.
Menggunakan himpunan data lokal atau terdaftar yang berbeda	Edit referensi himpunan data di `eval.yaml`, atau jalankan `azd ai agent eval generate --dataset <path-or-name> --out-file eval.yaml`ulang .
Menambahkan atau mengubah referensi evaluator	Edit `eval.yaml`, atau jalankan ulang `azd ai agent eval generate` dengan nilai `--evaluator` yang dapat diulang.
Mendaftarkan pengeditan lokal ke himpunan data atau rubrik evaluator yang dihasilkan	Jalankan `azd ai agent eval update`, tinjau perubahan yang terdeteksi, dan konfirmasi pembaruan referensi versi di `eval.yaml`.
Mulai lagi dari konfigurasi bawaan yang dibuat	Jalankan `azd ai agent eval generate --reset-defaults`.

Misalnya, setelah mengedit rubrik evaluator yang dihasilkan di bawah evaluators/ di folder agen, jalankan:

azd ai agent eval update
azd ai agent eval run --config eval.yaml

Perintah pembaruan membuat himpunan data atau versi evaluator terdaftar baru. Proses evaluasi yang ada tetap terikat pada versi yang digunakan saat proses tersebut dijalankan.

Ketika eval.yaml sudah ada, eval generate mendeteksinya dan mencetak konfigurasi yang ada:

Eval config already exists: src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  To run the evaluation:
    azd ai agent eval run

  To update local edits as new versions:
    azd ai agent eval update

  To overwrite and regenerate:
    azd ai agent eval generate --reset-defaults

Untuk menimpa konfigurasi lokal dan menghasilkan ulang aset evaluasi bawaan, jalankan:

azd ai agent eval generate --reset-defaults

--reset-defaults menimpa eval.yaml lokal dan membuat ulang aset evaluasi default. Himpunan data dan versi evaluator yang terdaftar di layanan yang ada tidak dihapus; hanya resep lokal yang diganti.

Jangan mengandalkan versi terbaru jarak jauh yang mengubah resep lokal secara diam-diam. eval.yaml lokal mencatat versi dataset, evaluator, atau suite yang digunakan oleh resep untuk memastikan hasil dapat direproduksi.

Opsional: memulai pengoptimalan dari sinyal evaluasi

Setelah setidaknya satu eksekusi evaluasi berhasil, Anda dapat menggunakan eval.yaml sebagai input untuk pengoptimalan agen jika agen dan resep memenuhi prasyarat pengoptimalan.

Sebelum memulai pengoptimalan, konfirmasikan bahwa:

Target agen siap untuk pengoptimalan. Untuk agen yang dihosting, agen tersebut di-deploy dan dapat dipanggil.
eval.yaml mereferensikan agen, himpunan data, versi evaluator, dan ambang yang dimaksudkan.
Setidaknya satu proses evaluasi berhasil diselesaikan.
Persiapan agen yang diperlukan pengoptimal telah selesai. Untuk prasyarat pengoptimal dan persyaratan persiapan agen, lihat Mengoptimalkan permintaan agen dengan Prompt Optimizer.

Kemudian jalankan layar perintah berikut:

azd ai agent optimize --config eval.yaml

Perintah optimalkan membaca target agen, himpunan data, evaluator, dan ambang batas dari eval.yaml. Ini mengirimkan pekerjaan pengoptimalan, tetapi tidak secara diam-diam menerapkan perubahan sumber atau menyebarkan ulang agen kandidat. Tinjau output pengoptimal sebelum menerapkan perubahan.

Praktik terbaik

Jalankan azd ai agent eval generate hanya setelah agen tersedia sebagai target evaluasi. Untuk agen yang dihosting, agen tersebut harus di-deploy dan dapat dipanggil.
Mulailah dengan himpunan data kecil yang dihasilkan atau subset kecil himpunan data emas Anda.
Periksa dataset yang dihasilkan dan artefak ulasan evaluator sebelum mempercayai skor.
Setelah mengedit himpunan data atau file evaluator yang dihasilkan, jalankan azd ai agent eval update untuk mendaftarkan aset yang diedit sebelum menjalankan evaluasi lagi.
Kontrol sumber eval.yaml jika tim Anda menginginkan resep evaluasi yang dapat ditinjau dan dapat direproduksi.
Pertimbangkan pengontrol sumber yang dihasilkan himpunan data dan rubrik evaluator di bawah datasets/ dan evaluators/ di folder agen jika tim Anda meninjau dan mengeditnya sebagai bagian dari resep evaluasi.
Jalankan kembali hal yang sama eval.yaml setelah perubahan agen sehingga perbandingan menggunakan resep pengujian yang sama.
Gunakan azd ai agent optimize --config eval.yaml hanya setelah Anda memiliki hasil evaluasi dasar yang berguna dan agen siap untuk optimasi.

Keterbatasan

Alur perintah utama dioptimalkan untuk agen terhosting dan siklus evaluasi pasca-deployment.
azd provision tidak membuat aset evaluasi.
eval run tidak menghasilkan himpunan data atau evaluator baru, kecuali untuk melanjutkan operasi yang tertunda dari eval generate --no-wait.
Siklus hidup rangkaian penuh, evaluasi terjadwal, evaluasi berkelanjutan, pemberitahuan, dan alur kerja perbandingan tidak diperlukan untuk jalur evaluasi pertama.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-06-19