azd CLI を使用してエージェント評価を実行する (プレビュー)

Azure Developer CLI (azd) CLI 評価エクスペリエンスを使用して、Microsoft Foundry で作成されたエージェントに測定品質ループを追加します。 この記事では、 azdでのホスト型エージェントのライフサイクルに焦点を当てます。ここでは、評価資産の作成、プロビジョニング、デプロイ、初期化、最初の評価の実行、実行の検査、評価レシピの再利用を後で実行します。

プロンプト ベースのエージェントは、Foundry プロジェクトでエージェント ターゲットとして使用できる場合にも評価できます。 ホステッド エージェントのデプロイ手順は、ホストされているエージェントにのみ適用されます。

この記事では、 azd ai agent eval generate と azd ai agent eval runを使用して最初のエージェント評価を実行する方法について説明します。

Prerequisites

• Microsoft Foundry にアクセスできる Azure サブスクリプション。
• Azure Developer CLI (azd)。 インストール手順については、「 Azure Developer CLI のインストールを参照してください。
• azd ai agent拡張機能バージョン 0.1.40-preview 以降がインストールされている (azd ext install azure.ai.agents)。 拡張機能がインストールされていない場合は、スターターテンプレートを初期化するか、azd ai agent を実行すると、拡張機能が自動的にインストールされます。 azd ext listを実行してインストールされているバージョンを確認し、アップグレードする必要がある場合はazd ext upgrade azure.ai.agentsを実行します。 azd AI エージェント拡張機能の詳細については、Microsoft Foundry agent extensionをご覧ください。
• 認証された azd セッション。 認証の状態を確認するには、 azd auth statusを実行します。 サインインしていない場合は、 azd auth loginを実行します。
• Foundry リソースの Foundry User ロール (以前は Azure AI User) です。 詳細については、Microsoft Foundry の ロールベースのアクセス制御 を参照してください。
• ホストされるエージェントの場合: 既存の Foundry プロジェクトは必要ありません。 azd ai agent init と azd provision は必要なリソースを作成します。
• プロンプト ベースのエージェントの場合: エージェントが既にデプロイされ、評価ターゲットとして使用できる既存の Foundry プロジェクト。
• 同じ Foundry プロジェクトでのチャットの完了をサポートするモデルデプロイ。
• 任意: eval generate でスモークデータセットを生成しない場合は、代表的な例を含む JSONL 評価データセット。

azd agent の評価のしくみ

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

評価フローには、次の成果物とコマンドが含まれています。

azd provision では、評価データセット、エバリュエーター、スイート、または最適化ジョブは作成されません。 評価のセットアップには、数分かかる生成作業が含まれる可能性があるため、明示的で再試行可能なままです。

ホストされるエージェントの場合、最初の評価では、デプロイされた呼び出し可能なエージェント ターゲットが必要です。 プロンプト ベースのエージェントの場合、展開手順は適用されません。エージェントは Foundry プロジェクトに既に存在し、評価ターゲットとして使用できる必要があります。

ホストされるエージェントを作成してデプロイする

hosted-agent プロジェクトがまだない場合は、 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`

プロンプト ベースのエージェントを評価するには、hosted-agent の作成コマンドとデプロイ コマンドをスキップします。 プロンプト ベースのエージェントが Foundry プロジェクトに存在し、評価ターゲットとして使用可能であることを確認したら、次のセクションに進みます。

評価資産を初期化する

azd ワークスペースまたはエージェント プロジェクト フォルダーから 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を実行すると、評価実行を開始する前に、それらの操作が自動的に再開されます。

プロンプト ベースのエージェント ターゲットを使用する

プロンプト ベースのエージェントの評価資産を初期化した場合は、同じ評価レシピ フローを使用できます。 プロンプト ベースのエージェントでは、ホステッド エージェントの展開手順は必要ありません。

評価を実行する前に、次の点を確認します。

• プロンプト ベースのエージェントは Foundry プロジェクトに存在します。
• エージェントは評価対象として利用できます。
• プロジェクト エンドポイントとエージェント ターゲットにアクセスできます。
• eval.yaml は、目的のプロンプト ベースのエージェントを選択します。

現在の 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

既定では、引数 0 の 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 は既定で最新の評価に設定され、その実行が一覧表示されます。

特定の実行の詳細を表示するには、eval ID を引数として渡し、実行 ID を --eval-run-idで渡します。 azd ai agent eval list出力から eval ID をコピーし、azd ai agent eval show <eval-id>出力から実行 ID をコピーします。

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

実行出力を使用して、次の応答を行います。

• 評価されたエージェントのバージョン。
• 解決されたデータセットと評価器のバージョン。
• 実行が完了したか、失敗したか、部分的に完了したか。
• 生成されたメトリックまたはエバリュエーター スコア。
• トークンの使用状況またはエバリュエーター ログに調査が必要かどうか。

エージェントを変更した後に再実行する

ホストされるエージェントを更新して再デプロイした後、同じ評価レシピをもう一度実行します。

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

プロンプト ベースのエージェントの場合は、Foundry でエージェントを更新してから、同じ評価レシピを再実行します。

同じ eval.yaml を再実行すると、データセット、エバリュエーター、しきい値の参照をエージェントの変更全体で安定した状態に保つことができます。

評価資産の更新、リセット、または修復

エージェント評価フローでは、ローカル評価レシピとして eval.yaml が使用されます。 ローカル データセット ファイルまたはエバリュエーター ルーブリックを編集し、それらの編集を新しいサービス バージョンとして登録する場合は、 azd ai agent eval update を使用します。

評価実行で使用される内容を更新するには、変更の種類に一致するパスを選択します。

たとえば、エージェント フォルダーの 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 は、再現性のためにレシピによって使用されるデータセット、エバリュエーター、またはスイート バージョンを記録します。

オプション: 評価信号から最適化を開始する

少なくとも 1 つの評価実行が成功した後、エージェントとレシピが最適化の前提条件を満たしている場合は、 eval.yaml をエージェント最適化への入力として使用できます。

最適化を開始する前に、次の点を確認します。

• エージェント ターゲットは最適化の準備ができています。 ホストされるエージェントの場合、エージェントはデプロイされ、呼び出し可能になります。
• eval.yaml は、目的のエージェント、データセット、エバリュエーターのバージョン、およびしきい値を参照します。
• 少なくとも 1 つの評価の実行が正常に完了しました。
• オプティマイザーに必要なエージェントの準備が完了しました。 オプティマイザーの前提条件とエージェントの準備要件については、 プロンプト オプティマイザーを使用したエージェント プロンプトの最適化に関するセクションを参照してください。

次に、以下を実行します。

azd ai agent optimize --config eval.yaml

optimize コマンドは、エージェントターゲット、データセット、エバリュエーター、しきい値を eval.yamlから読み取ります。 最適化ジョブを送信しますが、ソースの変更を自動的に適用したり、候補エージェントを再デプロイしたりすることはありません。 変更を適用する前に、オプティマイザーの出力を確認します。

ベスト プラクティス

• エージェントが評価ターゲットとして使用可能になった後にのみ、 azd ai agent eval generate を実行します。 ホストされるエージェントの場合、エージェントをデプロイして呼び出し可能にする必要があります。
• 生成された小さなデータセットまたはゴールデン データセットの小さなサブセットから始めます。
• スコアを信頼する前に、生成されたデータセットと評価者レビューの成果物を確認してください。
• 生成されたデータセットまたはエバリュエーター ファイルを編集した後、 azd ai agent eval update を実行して、再び評価を実行する前に、編集された資産を登録します。
• ソース管理 eval.yaml 、チームがレビュー可能で再現可能な評価レシピを必要としている場合です。
• チームが評価レシピの一部としてそれらをレビューして編集する場合は、エージェント フォルダー内の datasets/ と evaluators/ で、生成されたデータセットと評価者用ルーブリックをソース管理することを検討してください。
• エージェントの変更後に同じ eval.yaml を再実行し、比較で同じテストレシピが使用されるようにします。
• azd ai agent optimize --config eval.yamlは、有用なベースライン評価結果が得られ、エージェントが最適化のために準備された後にのみ使用します。

制限事項

• プライマリ コマンド フローは、ホストされているエージェントとデプロイ後の評価ループ用に最適化されています。
• azd provision は評価アセットを作成しません。
• eval run では、保留中の操作を eval generate --no-waitから再開する場合を除き、新しいデータセットやエバリュエーターは生成されません。
• 完全なスイート ライフサイクル、スケジュールされた評価、継続的な評価、アラート、および比較ワークフローは、最初の評価パスには必要ありません。

関連するコンテンツ

• AI エージェントを評価する
• Microsoft Foundry エージェントのユーザー評価
• 評価クラスター分析
• プロンプト オプティマイザーを使用してエージェント プロンプトを最適化する
• Microsoft Foundry
• エージェント監視ダッシュボードを使用してエージェントを監視する
• Foundry Agent Service でホストされるエージェント
• エージェント開発ライフサイクル