AI エージェントを評価する

評価は、デプロイ前にエージェントが品質および安全基準を満たしていることを確認するために不可欠です。開発中に評価を実行することで、エージェントのパフォーマンスのベースラインを確立し、ユーザーにリリースする前に、85% タスクの準拠合格率などの受け入れしきい値を設定できます。

この記事では、品質、安全性、およびエージェントの動作のために組み込みのエバリュエーターを使用して、 Foundry エージェントまたはホステッドエージェントに対してエージェントを対象とした評価を実行する方法について説明します。具体的には、次の手順を実行します。

評価用に SDK クライアントを設定します。
評価者を品質、安全性、エージェントの動作に基づいて選択します。
テストデータセットを作成し、評価を実行します。
結果を解釈し、ワークフローに統合します。

ヒント

カスタムエバリュエーター、さまざまなデータソース、追加の SDK オプションなど、生成型 AI モデルとアプリケーションの汎用評価については、「 SDK から評価を実行する」を参照してください。

前提条件

Python 3.8 以降。
エージェントまたはホステッドエージェントを含む Foundry プロジェクト。
チャットの完了をサポートする GPT モデルを使用した Azure OpenAI デプロイ (たとえば、gpt-4oや gpt-4o-mini)。
Foundry プロジェクトのFoundry Userロール。

重要

Foundry RBAC ロールの名前が最近変更されました。 Foundry User, Foundry Owner, Foundry Account Owner、および Foundry Project Manager は、以前は、AZURE AI ユーザー、Azure AI 所有者、Azure AI アカウント所有者、および AZURE AI Project Manager という名前でした。名前の変更がロールアウトされている間、以前の名前が表示される場合があります。ロール ID とコアアクセス許可は、名前の変更によって変更されません。

メモ

一部の評価機能には、地域的な制限があります。詳細については、サポートされているリージョンを参照してください。

クライアントを設定する

Foundry SDK をインストールし、認証を設定します。

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

プロジェクトクライアントを作成します。次のコードサンプルでは、このコンテキストで実行することを前提としています。

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

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

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

エバリュエーターの選択

エバリュエーターは、エージェントの応答を評価する関数です。評価者の中には、AI モデルをジャッジとして使用するものもあれば、ルールやアルゴリズムを使用するエバリュエーターもあります。エージェントの評価については、次のセットを検討してください。

エバリュエーター	測定対象
タスクの準拠	エージェントはシステムの指示に従っていますか?
コヒーレンス	応答は論理的で適切に構造化されていますか?
暴力	応答に暴力コンテンツが含まれていますか?

その他の組み込みエバリュエーターについては、以下を参照してください。

エージェントエバリュエーター - エージェントがタスク、ツール、およびユーザー意図を効果的に処理する方法を評価します。
品質エバリュエーター — 生成された応答の全体的な品質を測定します。
テキスト類似性エバリュエーター - NLP メトリックを使用して、生成されたテキストを参照回答と比較します。
安全性エバリュエーター — 生成された出力の潜在的なコンテンツとセキュリティリスクを特定します。

独自のエバリュエーターを構築するには、「カスタムエバリュエーター」を参照してください。

テストデータセットを作成する

エージェントのテストクエリを含む JSONL ファイルを作成します。各行には、 query フィールドを持つ JSON オブジェクトが含まれています。

{"query": "What's the weather in Seattle?"}
{"query": "Book a flight to Paris"}
{"query": "Tell me a joke"}

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

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

評価を実行する

評価を実行すると、サービスは各テストクエリをエージェントに送信し、応答をキャプチャし、選択したエバリュエーターを適用して結果をスコア付けします。

まず、エバリュエーターを構成します。各エバリュエーターには、入力を検索する場所を示すデータマッピングが必要です。

{{item.X}} は、 queryなど、テストデータからフィールドを参照します。
{{sample.output_items}} は、ツール呼び出しを含む完全なエージェント応答を参照します。
{{sample.output_text}} は、応答メッセージテキストのみを参照します。

タスクの準拠やコヒーレンスなどの AI 支援エバリュエーターには、 initialization_parametersのモデルデプロイ名が必要です。この値は、プロジェクト内の GPT デプロイ名と一致する必要があります。これは、応答のスコア付けに使用されるジャッジモデルです。エバリュエーターによっては、 ground_truth やツール定義など、追加のフィールドが必要になる場合があります。詳細については、エバリュエーターのドキュメントを参照してください。

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "Task Adherence",
        "evaluator_name": "builtin.task_adherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

次に、評価を作成します。評価では、テストデータスキーマとテスト条件が定義されます。これは、複数の実行のコンテナーとして機能します。すべての実行が同じ評価で同じスキーマに準拠し、同じメトリックのセットが生成されます。この一貫性は、実行間で結果を比較するために重要です。

data_source_config = {
    "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,
)

最後に、テストクエリをエージェントに送信し、エバリュエーターを適用する実行を作成します。

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": "my-agent",  # Replace with your agent name
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

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

ヒント

このサンプルは、プロンプトエージェントと、応答プロトコルを使用するホステッドエージェントの両方で機能します。呼び出しプロトコルを使用するホスト型エージェントの場合、 input_messages 形式は異なります。構造化テンプレートの代わりにフリーフォーム JSON オブジェクトを提供します。詳細とコードサンプルについては、クラウド評価ガイドの「Hosted Agent の呼び出しプロトコル」を参照してください。

ヒント

Application Insights のトレースを使用して既に発生したエージェントの相互作用を評価するには、クラウド評価ガイドの「トレース評価」を参照してください。

結果を解釈する

通常、評価はクエリの数に応じて数分で完了します。完了までポーリングを実行し、レポート URL を取り出して、Microsoft Foundry ポータルのEvaluationsタブで結果を表示します。

import time

# Wait for completion
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}")

集計された結果

実行レベルでは、成功と失敗の数、モデルごとのトークンの使用状況、エバリュエーターごとの結果など、集計されたデータを確認できます。

{
    "result_counts": {
        "total": 3,
        "passed": 1,
        "failed": 2,
        "errored": 0
    },
    "per_model_usage": [
        {
            "model_name": "gpt-4o-mini-2024-07-18",
            "invocation_count": 6,
            "total_tokens": 9285,
            "prompt_tokens": 8326,
            "completion_tokens": 959
        },
        ...
    ],
    "per_testing_criteria_results": [
        {
            "testing_criteria": "Task Adherence",
            "passed": 1,
            "failed": 2
        },
        ... // remaining testing criteria
    ]
}

行レベルの出力

各評価実行では、テストデータセット内の行ごとに出力項目が返され、エージェントのパフォーマンスが詳細に表示されます。出力項目には、元のクエリ、エージェントの応答、スコアと推論を含む個々のエバリュエーターの結果、トークンの使用が含まれます。

{
    "object": "eval.run.output_item",
    "id": "1",
    "run_id": "evalrun_abc123",
    "eval_id": "eval_xyz789",
    "status": "completed",
    "datasource_item": {
        "query": "What's the weather in Seattle?",
        "response_id": "resp_abc123",
        "agent_name": "my-agent",
        "agent_version": "10",
        "sample.output_text": "I'd be happy to help with the weather! However, I need to check the current conditions. Let me look that up for you.",
        "sample.output_items": [
            ... // agent response messages with tool calls
        ]
    },
    "results": [
        {
            "type": "azure_ai_evaluator",
            "name": "Task Adherence",
            "metric": "task_adherence",
            "label": "pass",
            "reason": "Agent followed system instructions correctly",
            "threshold": 3,
            "passed": true,
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        ... // remaining evaluation results
    ]
}

ワークフローに統合する

CI/CD パイプライン: デプロイパイプラインで品質ゲートとして評価を使用します。詳細な統合については、「Run evaluations with GitHub Actions」を参照してください。
運用環境の監視: 継続的な評価を使用して、運用環境のエージェントを監視します。セットアップ手順については、「継続的評価の設定」を参照してください。

バージョンの最適化と比較

評価を活用してエージェントを反復的に改善します。

評価を実行して弱い領域を特定します。クラスター分析を使用して、パターンとエラーを見つけます。
結果に基づいてエージェントの指示またはツールを調整します。
実行を再評価して比較し、改善を測定します。
品質しきい値が満たされるまで繰り返します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-19