使用 azd CLI 執行代理程式評估（預覽版）

Important

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。某些功能可能不被支援或功能受限。欲了解更多資訊，請參閱 Microsoft Azure 預覽版補充使用條款。

利用 Azure Developer CLI（azd）CLI 評估經驗，為使用 Microsoft Foundry 建立的代理程式加入一個可衡量的品質迴圈。本文著重說明 azd 中的託管代理程式生命週期，包括建立、佈建、部署、初始化評估資產、執行首次評估、檢視執行情況，以及在後續執行中重複使用評估配方。

當提示詞型 Agent 可作為 Foundry 專案中的 Agent 目標時，也可以評估這些 Agent。託管代理部署步驟僅適用於託管代理。

本文將介紹如何使用 azd ai agent eval generate 和 azd ai agent eval run 執行首次代理程式評估。

先決條件

擁有存取 Microsoft Foundry 的 Azure 訂閱。
Azure 開發者 CLI（azd）。安裝說明請參見安裝Azure開發者 CLI。
已安裝 (azd ext install azure.ai.agents)，版本為 0.1.40-preview 或更新版本的azd ai agent擴充功能。如果你還沒安裝擴充功能，當你初始化啟動範本或執行 azd ai agent 時，擴充功能會自動安裝。執行 azd ext list 以確認已安裝版本，若需要升級則執行 azd ext upgrade azure.ai.agents 。欲了解更多關於 AI 代理擴充功能，azd請參閱 Microsoft Foundry 代理擴充功能。
一個經過 azd 認證的會話。要檢查你的認證狀態，請執行 azd auth status。如果你尚未登入，請執行 azd auth login。
Foundry 資源上的 Foundry User 角色（前稱 Azure AI User）。欲了解更多資訊，請參閱 Microsoft Foundry 的基於角色的存取控制。
對於託管代理： 不需要既有的鑄造廠專案。 azd ai agent init 並 azd provision 創造必要的資源。
針對以提示為基礎的代理程式： 已有的 Foundry 專案，其中代理程式已部署，且可作為評估目標。
支援同一 Foundry 專案中聊天完成功能的模型部署。
選用：如果您不想讓 eval generate 產生煙霧測試資料集，請提供具有代表性範例的 JSONL 評估資料集。

azd 代理程式評估的運作方式

主要的 azd CLI 評估體驗是針對託管代理生命週期設計的：

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

評估流程包含以下工件與指令。

Item	Description
`eval generate`	建立或修復 Agent 目標的本機評估資產。
`eval.yaml`	本機可執行的評估範本。它記錄代理目標、資料集參考、評估器參考及生成選項
產生的本機成品	可編輯的本地生成資料集與評估評分標準副本。這些產物儲存在代理資料夾下方 `datasets/` 及 `evaluators/` 中（例如， `src/<agent-name>/datasets/` 和 `src/<agent-name>/evaluators/`）。
註冊服務產物	評估執行所使用的 Foundry 資料集與評估器版本。這些就是生成資產的真實來源。
`eval run`	針對選取的 Agent 目標執行評估配方。
`eval update`	從本機資料集或評估工具編輯註冊新的服務版本，並在確認後更新 `eval.yaml`。
`eval list` 與 `eval show`	從 CLI 檢查評估執行和結果。
`optimize --config eval.yaml`	在代理程式和配方符合最佳化先決條件後，可選擇從評估配方開始進行最佳化。

azd provision 不建立評估資料集、評估器、套件或優化工作。評估設定可能涉及需時數分鐘的產生作業，因此會維持為明確且可重試。

對於託管代理，第一次進行評估時，需要有一個已部署且可叫用的代理目標。對於提示式代理，部署步驟不適用;代理人必須已存在於 Foundry 專案中，並作為評估對象可用。

建立並部署託管代理

如果您還沒有託管代理程式專案，請使用 azd 初始化一個：

azd ai agent init

配置 Foundry 資源並部署代理程式：

azd provision
azd deploy

部署完成後，確認代理是否可呼叫：

azd ai agent show

託管代理必須先部署並可調用，才能初始化評估資產。

部署成功後，CLI 建議將評估作為明確的下一步：

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

要評估基於提示的代理程式，請跳過主機代理的建立與部署指令。確認以提示為基礎的代理程式存在於 Foundry 專案中，且可作為評估目標使用後，再繼續進行下一節。

注意

以目標為基礎的評估會直接叫用你的代管代理程式。它適用於使用響應或調用協定並進行同步、非串流執行的代理程式。若要評估使用 A2A 或 Activity 協定，或其他執行模式（例如長時間執行或串流）的代理程式，請改為評估您的代理程式所產生的追蹤資料。詳見追蹤評估。

初始化評估資源

從 azd 工作區或 Agent 專案資料夾執行 eval generate：

azd ai agent eval generate

沒有標記時，指令會啟動互動式精靈。精靈會從azd環境中偵測代理目標，然後要求產生指令，讓服務能建立有用的種子評估資料和評估器規準。

互動輸出範例：

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

若透過指令碼使用，請直接傳遞生成輸入：

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是可選的，且在代理專案根中預設為。eval.yaml 用 --out-file <path> 來把設定寫到另一個位置。

若要使用現有資料集和選定的評估人員：

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

用你自己的評估資料集路徑來取代 ./tests/support-golden.jsonl 。

該 --dataset 值可以指向本地檔案或註冊的資料集名稱。重複使用 --evaluator，以加入多個內建或已註冊的自訂評估器。評估者參考文獻格式為 <source>.<name>：

builtin.<name> — 參照 Foundry 提供的內建評估器。
<name> —— 指的是 Foundry 專案中註冊的客製化評估器。請使用評估者的註冊姓名，不要加上版本後綴。

使用 `--no-wait` 延後產生

若資料集或評估器產生時間過長，請使用 --no-wait 提交生成工作並立即退出：

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

待處理的操作 ID 會寫成 eval.yaml。當你之後執行 azd ai agent eval run時，它會自動恢復這些操作，然後再開始評估執行。

使用提示詞型 Agent 目標

如果你已為以提示為基礎的代理程式初始化評估資源，就可以使用相同的評估配方流程。 Hosted Agent 部署步驟不需要用於提示詞型 Agent。

在進行評估前，請確認：

提示型代理位於 Foundry 專案中。
該代理人可作為評估目標。
你可以存取專案端點和代理目標。
eval.yaml 會選取預期的提示詞型 Agent。

若要列出目前 Foundry 專案中可用的代理人，請執行：

azd ai agent list

然後使用相同的指令執行並檢查評估：

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

檢閱 eval.yaml

在 eval generate 成功後，於代理專案根目錄開啟 eval.yaml。例如：

src/reservation-agent/eval.yaml

在此目錄中執行 eval run，或使用 --config src/reservation-agent/eval.yaml 明確指定路徑。該檔案標示代理人目標、資料集參考、評估器參考及生成選項。簡化的形狀為：

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 位於代理程式專案的根目錄，例如 src/<agent-name>/eval.yaml。
產生的資料集存放在 datasets/ 代理人資料夾下，產生的評估評分標準則存放 evaluators/ 在代理人資料夾下。
local_uri 在 eval.yaml 中的路徑是相對於代理程式專案目錄的。
參考的 local_uri 本地檔案是可編輯的。執行 azd ai agent eval update 以將本地變更註冊為服務中的新版本，並將該版本加入 eval.yaml。
eval run 使用固定於 eval.yaml 中的已註冊版本。要套用本機編輯，請在執行 eval update 之前先執行 eval run。
評估器可以是內建參考項目（例如 builtin.task_adherence），也可以是使用 name、version 和 local_uri 產生的自訂評估器。
將版本欄位視為字串，即使看起來像數字，這樣配方在 YAML 解析器中也能保持穩定。

執行評估

從代理專案資料夾中執行：

azd ai agent eval run

預設情況下，零參數 eval run 會在 eval.yaml 代理專案根中解決。你也可以明確傳遞設定路徑：

azd ai agent eval run --config eval.yaml

若 eval generate --no-wait 已建立待處理的產生操作，會在 eval run 開始評估執行前恢復這些操作。它不會從零開始新的資料集或評估器產生工作。

檢查評估執行

列出最近的評估執行：

azd ai agent eval list

顯示最新一次執行：

azd ai agent eval show

若未指定旗標，eval show 會預設使用最近一次評估，並列出其執行記錄。

要顯示特定跑動的細節，將評估 ID 作為參數傳遞，跑動 ID 則為 --eval-run-id。從azd ai agent eval list輸出中複製 eval 識別碼，並從azd ai agent eval show <eval-id>輸出中複製執行識別碼：

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

利用跑分輸出來回答：

評估的是哪個 Agent 版本。
已解析出的資料集和評估器版本有哪些。
無論執行結果是完成、失敗，還是部分完成。
已產生哪些指標或評估分數。
是否需要調查詞元使用量或評估工具記錄。

更換代理後重新執行

更新並重新部署主機代理後，再次執行相同的評估流程：

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

對於基於提示的代理，先在 Foundry 更新代理，然後重複執行相同的評估流程。

重複執行同一 eval.yaml 任務有助於保持資料集、評估器及閾值參考在代理變更間的穩定。

更新、重置或修復評估資產

Agent 評估流程會使用 eval.yaml 作為本機評估配方。當你編輯本地資料集檔案或評估器評分標準，並想將這些編輯註冊為新服務版本時，請使用 azd ai agent eval update 。

要更新評估執行所使用的路徑，請選擇與變更類型相符的路徑：

變化	更新方式
更改閾值、評估器參考、輸出設定或其他配方欄位	編輯 `eval.yaml`，然後執行 `azd ai agent eval run --config eval.yaml`。
使用不同的本地或註冊資料集	在 `eval.yaml` 中編輯資料集參照，或重新執行 `azd ai agent eval generate --dataset <path-or-name> --out-file eval.yaml`。
新增或變更評估器參照	編輯 `eval.yaml`，或使用可重複的 `azd ai agent eval generate` 值重新執行 `--evaluator`。
將本機編輯註冊至產生的資料集或評估工具 Rubric	執行 `azd ai agent eval update`、檢視偵測到的變更，並在 `eval.yaml` 中確認版本參照更新。
從預設的設定重新開始	執行 `azd ai agent eval generate --reset-defaults`。

例如，在 agent 資料夾中的 evaluators/ 下編輯生成的評估器評分標準後，執行：

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

update 指令會建立新的註冊資料集或評估器版本。現有的評估運行仍綁定於最初使用的版本。

當 eval.yaml 已存在時，eval generate 會偵測到它並輸出現有的設定：

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

要覆寫本地設定並重新產生預設評估資產，請執行：

azd ai agent eval generate --reset-defaults

--reset-defaults 覆蓋本地 eval.yaml 並重新生成預設的評估資產。現有的服務註冊資料集與評估器版本不會被刪除;只替換當地食譜。

不要依賴遠端的最新版本悄悄變更本地配方。本機 eval.yaml 會記錄配方使用的資料集、評估工具或套件版本，以便重現。

可選：從評估訊號開始優化

在至少有一次評估執行成功之後，如果代理程式和配方符合最佳化先決條件，你可以使用 eval.yaml 作為代理最佳化的輸入。

在開始優化前，請確認：

代理程式目標已可進行最佳化。對於託管代理，代理已被部署並可調用。
eval.yaml 參考目標代理、資料集、評估器版本及閾值。
至少有一次評估執行成功完成。
優化器所需的代理準備已完成。關於優化器的前置條件與代理準備需求，請參閱「用提示優化器優化代理提示」。

然後執行：

azd ai agent optimize --config eval.yaml

optimize 命令會從 eval.yaml 讀取代理目標、資料集、評估器和閾值。它會提交一個優化工作，但不會靜默套用原始碼變更或重新部署候選代理。在套用變更前，先檢查任何優化器的輸出。

最佳做法

僅在該代理程式可作為評估目標後，才執行 azd ai agent eval generate。對於託管代理，代理必須已部署且可叫用。
從小型產生資料集或黃金資料集的小型子集開始。
信任分數前，請先檢查產生的資料集和評估工具檢閱成品。
編輯產生的資料集或評估器檔案後，執行 azd ai agent eval update 登錄已編輯資產，再執行評估。
如果你的團隊想要一個可審查、可重現的評估配方，就使用來源控制 eval.yaml 。
如果您的團隊會在評估配方中檢閱和編輯產生的資料集和評估工具 Rubric，請考慮將其在 Agent 資料夾中的 datasets/ 和 evaluators/ 下納入原始檔控制。
在代理程式變更後，重新執行同一個 eval.yaml，以便比較時使用相同的測試配方。
只有在你有一個有用的基線評估結果，且代理人準備好進行優化後才使用 azd ai agent optimize --config eval.yaml 。

Limitations

主要指令流程針對託管代理及部署後評估迴圈進行優化。
azd provision 不會建立評估資產。
eval run 不會產生新的資料集或評估器，但會從 eval generate --no-wait 繼續尚未完成的作業。
第一階段評估路徑不需要完整的套件生命週期、排程評估、持續評估、警示及比較工作流程。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-06-15