クイック スタート: ホストされているエージェントを評価する

azd プロジェクト ディレクトリから、エージェントがデプロイされ、呼び出し可能であることを確認します。

azd ai agent show

テスト プロンプトを送信します。

azd ai agent invoke "Write a haiku about deploying cloud applications."

数秒以内に応答が表示されます。

1. Foundry ポータルを開き、プロジェクトに移動します。
2. エージェントを選択し、[ プレイグラウンド ] タブを選択します。
3. テスト プロンプトを送信する (例: Write a haiku about deploying cloud applications.

数秒以内に応答が表示されます。

Foundry SDK をインストールします。

pip install "azure-ai-projects>=2.0.0" azure-identity

2 つの環境変数を設定し、プロジェクト クライアントを作成します。 FOUNDRY_PROJECT_ENDPOINT をプロジェクト エンドポイントに設定し、FOUNDRY_MODEL_NAME を評価モデルとして使用するチャット補完デプロイに設定します。 次のコード サンプルでは、このコンテキストで実行することを前提としています。

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment = os.environ["FOUNDRY_MODEL_NAME"]

credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
client = project_client.get_openai_client()

デプロイされたエージェントが登録され、使用可能であることを確認します。 <your-agent-name>をホストされているエージェントの名前に置き換えます。

agent = project_client.agents.get("<your-agent-name>")
print(f"Found agent: {agent.name}")

呼び出しは、エージェントが存在する場合はエージェントを返し、名前が間違っているか、エージェントがデプロイされていない場合はエラーを発生させます。

Foundry SDK と OpenAI evals クライアントをインストールします。

dotnet add package Azure.AI.Projects --prerelease
dotnet add package OpenAI
dotnet add package Azure.Identity

2 つの環境変数を設定し、クライアントを作成します。 FOUNDRY_PROJECT_ENDPOINT をプロジェクト エンドポイントに設定し、FOUNDRY_MODEL_NAME を評価モデルとして使用するチャット補完デプロイに設定します。 次のコード サンプルでは、このコンテキストで実行することを前提としています。

using System.ClientModel;
using System.Text.Json;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Core;
using Azure.Identity;
using OpenAI;
using OpenAI.Evals;

#pragma warning disable AAIP001, OPENAI001

var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!;
var modelDeployment = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")!;

var credential = new DefaultAzureCredential();
AIProjectClient projectClient = new(new Uri(endpoint), credential);

// OpenAI-compatible evals client bound to the Foundry project endpoint.
// A Microsoft Entra token works as the credential because both use "Authorization: Bearer".
var token = credential.GetToken(new TokenRequestContext(["https://ai.azure.com/.default"])).Token;
EvaluationClient evalClient = new(
    new ApiKeyCredential(token),
    new OpenAIClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1") });

デプロイされたエージェントが登録され、使用可能であることを確認します。 <your-agent-name>をホストされているエージェントの名前に置き換えます。

ProjectsAgentRecord agent = projectClient.AgentAdministrationClient.GetAgent("<your-agent-name>");
Console.WriteLine($"Found agent: {agent.Name}");

呼び出しは、エージェントが存在する場合はエージェントを返し、名前が間違っているか、エージェントがデプロイされていない場合はエラーを発生させます。

Foundry SDK をインストールします。

npm install @azure/ai-projects @azure/identity dotenv

2 つの環境変数を設定し、プロジェクト クライアントを作成します。 FOUNDRY_PROJECT_ENDPOINT をプロジェクト エンドポイントに設定し、FOUNDRY_MODEL_NAME を評価モデルとして使用するチャット補完デプロイに設定します。 次のコード サンプルでは、このコンテキストで実行することを前提としています。

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";

const endpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "";
const modelDeployment = process.env["FOUNDRY_MODEL_NAME"] || "";

const projectClient = new AIProjectClient(
  endpoint,
  new DefaultAzureCredential(),
);
const client = projectClient.getOpenAIClient();

デプロイされたエージェントが登録され、使用可能であることを確認します。 <your-agent-name>をホストされているエージェントの名前に置き換えます。

const agent = await projectClient.agents.get("<your-agent-name>");
console.log(`Found agent: ${agent.name}`);

呼び出しは、エージェントが存在する場合はエージェントを返し、名前が間違っているか、エージェントがデプロイされていない場合はエラーを発生させます。

リファレンス: AIProjectClient クラス

まず、エージェントのテスト クエリの JSONL ファイルを作成します。 各行は、 query フィールドを持つ JSON オブジェクトです。 src/<your-agent-name>/tests/queries.jsonlとして、エージェントのソース フォルダー内に保存します。

{"query": "Write a haiku about deploying cloud applications."}

次に、eval.yamlと同じエージェント ソース フォルダーにsrc/<your-agent-name>/eval.yaml ファイルを作成します。 データセットをポイントし、適用する組み込みのエバリュエーターを一覧表示します。 dataset.local_uri パスは、このフォルダーに対する相対パスです。 <your-agent-name> をホストされているエージェント名に、<your-chat-completion-deployment> をジャッジモデルのデプロイ名に置き換えてください。

name: agent-eval
agent:
  name: <your-agent-name>
  kind: hosted
dataset:
  local_uri: tests/queries.jsonl
evaluators:
  - builtin.intent_resolution
  - builtin.task_adherence
options:
  eval_model: <your-chat-completion-deployment>
max_samples: 15

eval_model値は、応答をスコア付けするジャッジ モデルです。エージェントが既に使用しているデプロイを再利用できます。

1. Foundry ポータルでエージェントを開き、[評価] タブを選択し、[作成] を選択します。
2. [ 評価ターゲットの選択] で、[エージェント] を選択 します。
3. [ 評価範囲の選択] で、[ 個々のターン] を選択します。
4. [ データ ソースの選択] で [ 既存のデータセット ] を選択し、プロジェクトのデータ資産からテスト クエリの CSV または JSONL ファイルを選択します。
5. [ エージェントの構成] ステップが表示されたら、エージェントを確認し、既定のユーザー プロンプト {{item.query}}受け入れます。 エージェントが別の入力形式を想定している場合にのみ、それを調整してください。
6. [ テスト条件の選択] で、 タスクの準拠 や 意図の解決など、1 つ以上のエージェント エバリュエーターを選択します。

ウィザードを開いたままにします。 評価は次の手順で送信します。

まず、エージェントのテスト クエリの JSONL ファイルを作成します。 各行は、 query フィールドを持つ JSON オブジェクトです。 queries.jsonlとして保存します。

{"query": "Write a haiku about deploying cloud applications."}

プロジェクト内のデータセットとしてファイルをアップロードします。

dataset = project_client.datasets.upload_file(
    name="agent-test-queries",
    version="1",
    file_path="./queries.jsonl",
)

次に、組み込みのエバリュエーターを選択し、入力をマップします。 data_mapping パラメーターは、クエリとエージェントの応答を検索する場所を各エバリュエーターに指示します。 AI 支援評価ツールでは、initialization_parameters にジャッジ モデルが必要です。この値は、プロジェクト内のチャット補完デプロイである必要があります。

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Intent Resolution",
        evaluator_name="builtin.intent_resolution",
        initialization_parameters={"model": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    ),
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Task Adherence",
        evaluator_name="builtin.task_adherence",
        initialization_parameters={"model": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    ),
]

評価を作成します。 テスト データ スキーマとテスト条件を定義し、1 つ以上の実行のコンテナーとして機能します。

from openai.types.eval_create_params import DataSourceConfigCustom

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
    include_sample_schema=True,
)

evaluation = client.evals.create(
    name="Agent Quality Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)
print(f"Evaluation created: {evaluation.id}")

まず、エージェントのテスト クエリの JSONL ファイルを作成します。 各行は、 query フィールドを持つ JSON オブジェクトです。 queries.jsonlとして保存します。

{"query": "Write a haiku about deploying cloud applications."}

プロジェクト内のデータセットとしてファイルをアップロードします。

AIProjectDataset dataset = projectClient.Datasets.UploadFile(
    name: "agent-test-queries",
    version: "1",
    filePath: "./queries.jsonl");

次に、組み込みのエバリュエーターを選択し、入力をマップします。 data_mapping パラメーターは、クエリとエージェントの応答を検索する場所を各エバリュエーターに指示します。 AI 支援評価ツールでは、initialization_parameters にジャッジ モデルが必要です。この値は、プロジェクト内のチャット補完デプロイである必要があります。

var testingCriteria = new object[]
{
    new
    {
        type = "azure_ai_evaluator",
        name = "Intent Resolution",
        evaluator_name = "builtin.intent_resolution",
        initialization_parameters = new { model = modelDeployment },
        data_mapping = new { query = "{{item.query}}", response = "{{sample.output_items}}" },
    },
    new
    {
        type = "azure_ai_evaluator",
        name = "Task Adherence",
        evaluator_name = "builtin.task_adherence",
        initialization_parameters = new { model = modelDeployment },
        data_mapping = new { query = "{{item.query}}", response = "{{sample.output_items}}" },
    },
};

評価を作成します。 テスト データ スキーマとテスト条件を定義し、1 つ以上の実行のコンテナーとして機能します。

var createEvaluation = new
{
    name = "Agent Quality Evaluation",
    data_source_config = new
    {
        type = "custom",
        item_schema = new
        {
            type = "object",
            properties = new { query = new { type = "string" } },
            required = new[] { "query" },
        },
        include_sample_schema = true,
    },
    testing_criteria = testingCriteria,
};

ClientResult evaluationResult = evalClient.CreateEvaluation(
    BinaryContent.Create(BinaryData.FromObjectAsJson(createEvaluation)));
string evaluationId = JsonDocument.Parse(evaluationResult.GetRawResponse().Content.ToString())
    .RootElement.GetProperty("id").GetString()!;
Console.WriteLine($"Evaluation created: {evaluationId}");

まず、エージェントのテスト クエリの JSONL ファイルを作成します。 各行は、 query フィールドを持つ JSON オブジェクトです。 queries.jsonlとして保存します。

{"query": "Write a haiku about deploying cloud applications."}

プロジェクト内のデータセットとしてファイルをアップロードします。

const dataset = await projectClient.datasets.uploadFile(
  "agent-test-queries",
  "1",
  "./queries.jsonl",
);

次に、組み込みのエバリュエーターを選択し、入力をマップします。 data_mapping パラメーターは、クエリとエージェントの応答を検索する場所を各エバリュエーターに指示します。 AI 支援評価ツールでは、initialization_parameters にジャッジ モデルが必要です。この値は、プロジェクト内のチャット補完デプロイである必要があります。

const testingCriteria = [
  {
    type: "azure_ai_evaluator",
    name: "Intent Resolution",
    evaluator_name: "builtin.intent_resolution",
    initialization_parameters: { model: modelDeployment },
    data_mapping: {
      query: "{{item.query}}",
      response: "{{sample.output_items}}",
    },
  },
  {
    type: "azure_ai_evaluator",
    name: "Task Adherence",
    evaluator_name: "builtin.task_adherence",
    initialization_parameters: { model: modelDeployment },
    data_mapping: {
      query: "{{item.query}}",
      response: "{{sample.output_items}}",
    },
  },
];

評価を作成します。 テスト データ スキーマとテスト条件を定義し、1 つ以上の実行のコンテナーとして機能します。

const dataSourceConfig = {
  type: "custom",
  item_schema: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
  },
  include_sample_schema: true,
};

const evaluation = await client.evals.create({
  name: "Agent Quality Evaluation",
  data_source_config: dataSourceConfig,
  testing_criteria: testingCriteria,
});
console.log(`Evaluation created: ${evaluation.id}`);

azd workspace root から評価を実行します。

azd ai agent eval run --config eval.yaml

コマンドは、 eval.yamlを読み取り、各クエリをエージェントに送信し、応答をスコア付けして、完了すると概要を出力します。

Eval run started
   Eval: eval_b36748dede424e4ba3f8e6c99ca2cf27
   Run:  evalrun_5f72ef189ad24790a32128e6f230b131
   (✓) Done  Eval run

Results:    1 total, 1 passed, 0 failed, 0 errored

Per-criteria results:
  intent_resolution: 1 passed, 0 failed, 0 errored
  task_adherence: 1 passed, 0 failed, 0 errored

1. [ 確認と送信 ] ステップで、評価の 名前 を入力します。
2. ターゲット、スコープ、データ ソース、選択したエバリュエーターを確認します。
3. [ 送信] を 選択して実行を開始します。

各テスト クエリをエージェントに送信し、エバリュエーターを適用する実行を作成します。 <your-agent-name>をホストされているエージェントの名前に置き換えます。

eval_run = client.evals.runs.create(
    eval_id=evaluation.id,
    name="Agent Evaluation Run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {"type": "file_id", "id": dataset.id},
        "input_messages": {
            "type": "template",
            "template": [
                {
                    "type": "message",
                    "role": "user",
                    "content": {"type": "input_text", "text": "{{item.query}}"},
                }
            ],
        },
        "target": {
            "type": "azure_ai_agent",
            "name": "<your-agent-name>",
            # "version": "1",  # Optional; omit to use the latest version
        },
    },
)

print(f"Evaluation run started: {eval_run.id}")

各テスト クエリをエージェントに送信し、エバリュエーターを適用する実行を作成します。 <your-agent-name>をホストされているエージェントの名前に置き換えます。

var createRun = new
{
    name = "Agent Evaluation Run",
    data_source = new
    {
        type = "azure_ai_target_completions",
        source = new { type = "file_id", id = dataset.Id },
        input_messages = new
        {
            type = "template",
            template = new object[]
            {
                new { type = "message", role = "user", content = new { type = "input_text", text = "{{item.query}}" } },
            },
        },
        // Add a "version" property to the target to pin a specific agent version; omit to use the latest.
        target = new { type = "azure_ai_agent", name = "<your-agent-name>" },
    },
};

ClientResult runResult = evalClient.CreateEvaluationRun(
    evaluationId, BinaryContent.Create(BinaryData.FromObjectAsJson(createRun)));
string runId = JsonDocument.Parse(runResult.GetRawResponse().Content.ToString())
    .RootElement.GetProperty("id").GetString()!;
Console.WriteLine($"Evaluation run started: {runId}");

各テスト クエリをエージェントに送信し、エバリュエーターを適用する実行を作成します。 <your-agent-name>をホストされているエージェントの名前に置き換えます。

const evalRun = await client.evals.runs.create(evaluation.id, {
  name: "Agent Evaluation Run",
  data_source: {
    type: "azure_ai_target_completions",
    source: { type: "file_id", id: dataset.id },
    input_messages: {
      type: "template",
      template: [
        {
          type: "message",
          role: "user",
          content: { type: "input_text", text: "{{item.query}}" },
        },
      ],
    },
    target: {
      type: "azure_ai_agent",
      name: "<your-agent-name>",
      // version: "1", // Optional; omit to use the latest version
    },
  },
});

console.log(`Evaluation run started: ${evalRun.id}`);

最近の評価を一覧表示します。

azd ai agent eval list

    Eval ID                                Name        Status of last run  Runs
    -------                                ----        ------------------  ----
*   eval_b36748dede424e4ba3f8e6c99ca2cf27  agent-eval  Completed           1

* = active eval in current environment

最新の評価とその実行を表示します。

azd ai agent eval show

Eval:   eval_b36748dede424e4ba3f8e6c99ca2cf27
Name:   agent-eval
Agent:  <your-agent-name>
Runs:   1

Recent runs:
  Run ID                                    Status     Passed  Failed  Created
  ------                                    ------     ------  ------  -------
  evalrun_5f72ef189ad24790a32128e6f230b131  Completed  1/1     0       2026-06-17 14:52 UTC

結果を使用して、どのエージェント バージョンが評価され、どのエバリュエーター スコアが生成されたかを確認します。 Foundry ポータルでエバリュエーターごとの詳細とレポートへのリンクを表示するには、 azd ai agent eval show <eval-id> --eval-run-id <run-id>実行します。

1. 詳細ページには、各エバリュエーターのターゲット、データセット、状態、トークンの使用状況、集計スコアが表示されます。
2. 実行名を選択して行レベルの結果を表示します。各クエリ、エージェント応答、エバリュエーター スコア、スコアの説明です。

完了するまでポーリングし、その後、ステータスと、Foundry ポータルで結果を開くためのレポート URL を出力します。

import time

while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=evaluation.id)
    if run.status in ["completed", "failed"]:
        break
    time.sleep(5)

print(f"Status: {run.status}")
print(f"Report URL: {run.report_url}")

実行レベルでは、各エバリュエーターの成功と失敗の集計カウントを確認できます。

print(run.result_counts)
for criteria in run.per_testing_criteria_results:
    print(criteria.testing_criteria, "passed:", criteria.passed, "failed:", criteria.failed)

ResultCounts(errored=0, failed=0, passed=1, total=1, skipped=0)
Intent Resolution passed: 1 failed: 0
Task Adherence passed: 1 failed: 0

行レベルの詳細については、出力項目を一覧表示します。 各結果には、エバリュエーター名、成功または失敗、スコアが含まれます。

for item in client.evals.runs.output_items.list(run_id=eval_run.id, eval_id=evaluation.id):
    for result in item.results:
        print(item.id, result.name, "passed:", result.passed, "score:", result.score)

完了するまでポーリングし、その後、ステータスと、Foundry ポータルで結果を開くためのレポート URL を出力します。

JsonElement run = default;
while (true)
{
    ClientResult runStatus = evalClient.GetEvaluationRun(evaluationId, runId, options: null);
    run = JsonDocument.Parse(runStatus.GetRawResponse().Content.ToString()).RootElement;
    string status = run.GetProperty("status").GetString()!;
    if (status is "completed" or "failed") break;
    Thread.Sleep(TimeSpan.FromSeconds(5));
}

Console.WriteLine($"Status: {run.GetProperty("status").GetString()}");
Console.WriteLine($"Report URL: {run.GetProperty("report_url").GetString()}");

実行レベルでは、各エバリュエーターの成功と失敗の集計カウントを確認できます。

Console.WriteLine(run.GetProperty("result_counts").GetRawText());
foreach (JsonElement criteria in run.GetProperty("per_testing_criteria_results").EnumerateArray())
{
    Console.WriteLine(
        $"{criteria.GetProperty("testing_criteria").GetString()} " +
        $"passed: {criteria.GetProperty("passed").GetInt32()} " +
        $"failed: {criteria.GetProperty("failed").GetInt32()}");
}

行レベルの詳細については、出力項目を一覧表示します。 各結果には、エバリュエーター名、成功または失敗、スコアが含まれます。

ClientResult outputItems = evalClient.GetEvaluationRunOutputItems(
    evaluationId, runId, limit: 100, order: null, after: null, outputItemStatus: null, options: null);
foreach (JsonElement item in JsonDocument.Parse(outputItems.GetRawResponse().Content.ToString())
    .RootElement.GetProperty("data").EnumerateArray())
{
    foreach (JsonElement result in item.GetProperty("results").EnumerateArray())
    {
        Console.WriteLine(
            $"{item.GetProperty("id").GetString()} {result.GetProperty("name").GetString()} " +
            $"passed: {result.GetProperty("passed")} score: {result.GetProperty("score")}");
    }
}

完了するまでポーリングし、その後、ステータスと、Foundry ポータルで結果を開くためのレポート URL を出力します。

let run = evalRun;
while (!["completed", "failed"].includes(run.status)) {
  run = await client.evals.runs.retrieve(run.id, {
    eval_id: evaluation.id,
  });
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

console.log(`Status: ${run.status}`);
console.log(`Report URL: ${run.report_url}`);

実行レベルでは、各エバリュエーターの成功と失敗の集計カウントを確認できます。

console.log(JSON.stringify(run.result_counts));
for (const criteria of run.per_testing_criteria_results) {
  console.log(
    criteria.testing_criteria,
    "passed:",
    criteria.passed,
    "failed:",
    criteria.failed,
  );
}

{"errored":0,"failed":0,"passed":1,"total":1,"skipped":0}
Intent Resolution passed: 1 failed: 0
Task Adherence passed: 1 failed: 0

行レベルの詳細については、出力項目を一覧表示します。 各結果には、エバリュエーター名、成功または失敗、スコアが含まれます。

for await (const item of client.evals.runs.outputItems.list(run.id, {
  eval_id: evaluation.id,
})) {
  for (const result of item.results) {
    console.log(item.id, result.name, "passed:", result.passed, "score:", result.score);
  }
}