Microsoft Foundry SDK を使用してデプロイされたモデルとエージェントの会話を評価する (プレビュー)

Application Insights でキャプチャされた完全な運用会話を評価して、特定の対話やデプロイされたエージェントトラフィックのサンプルを調査します。

前提条件

クラウド評価の前提条件とクライアントのセットアップを完了します。
プレビュートレース評価ワークフローでは、Python SDK バージョン 2.7.0 (pip install "azure-ai-projects==2.7.0") または JavaScript SDK バージョン 2.7.0 (npm install "@azure/ai-projects@2.7.0") を使用します。
Application Insights でのトレースされた運用会話。
選択した評価レベルをサポートする会話レベルのエバリュエーター。

この例では、「SDK クライアントのセットアップ」で構成された SDK クライアントを使用します。

トレースからの ID による会話の評価

Application Insights からの特定の会話を評価するために、会話 ID を指定します。このオプションを使用して、問題の根本原因を特定したり、特定の対話に関する修正を確認したりします。たとえば、アラートによってフラグ付けされた会話を調査したり、既知の問題の修正プログラムを確認したりできます。

会話 ID を検索する場所

会話 ID は次の中から検索できます。

Application Insights トレースログ UI - 興味深いトレースを参照し、トレースの詳細で conversation_id フィールドを見つけます。
アプリケーションのログ出力 — エージェントの応答を作成するときに conversation_id を明示的に設定した場合は、ログから取得します。
OpenTelemetry トレースコンテキスト — エージェントが標準のトレースコンテキスト伝達を使用している場合、 conversation_id は traceparent ヘッダーから派生することもあります。

Note

ツール定義は、トレースから自動的に取得されるか、エージェントレジストリから照会されます。要求で指定する必要はありません。

会話ID検索のパラメーター

パラメーター	必須	説明
`conversation_ids`	はい	評価対象の会話IDの配列。
`lookback_hours`	いいえ	`end_time`から遡って検索する時間数。既定値は 7 日 (168 時間) です。
`start_time`	いいえ	明示的な検索ウィンドウの開始 (ISO 8601 形式)。 ID ベースの検索では、`start_time` と `end_time` の両方を指定して、`lookback_hours` ではなく明示的なウィンドウを使用してください。
`end_time`	いいえ	検索ウィンドウの末尾 (ISO 8601 形式)。既定値は現在の時刻です。 `start_time` を指定して、明示的なウィンドウを使用します。

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

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

# Provide conversation IDs or trace IDs from App Insights
conversation_ids = ["conversation_1234", "conversation_5678"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="output_quality",
            evaluator_name="builtin.output_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="tool_use_quality",
            evaluator_name="builtin.tool_use_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="deflection_rate",
            evaluator_name="builtin.deflection_rate",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    # Create evaluation with traces scenario
    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (by ID)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Run evaluation on specific conversation IDs
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-trace-by-id-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": {
                "type": "conversation_id_source",
                "conversation_ids": conversation_ids,
            },
        },
        extra_body={"evaluation_level": "conversation"},
    )

データスキーマとエバリュエーターの定義に関するページのdataSourceConfig値とtestingCriteria値を使用します。

    string[] conversationIds = ["conversation_1234", "conversation_5678"];
    BinaryData evaluationData = BinaryData.FromObjectAsJson(new
    {
      name = "Multi-turn Trace Evaluation (by ID)",
      data_source_config = new
      {
        type = "azure_ai_source",
        scenario = "traces"
      },
      testing_criteria = testingCriteria
    });
    using BinaryContent evaluationContent = BinaryContent.Create(evaluationData);
    ClientResult evaluation = await evaluationClient.CreateEvaluationAsync(
      evaluationContent);
    string evaluationId = GetString(evaluation, "id");

    BinaryData runData = BinaryData.FromObjectAsJson(new
    {
      name = "multiturn-trace-by-id-run",
      evaluation_level = "conversation",
      data_source = new
      {
        type = "azure_ai_trace_data_source_preview",
        trace_source = new
        {
          type = "conversation_id_source",
          conversation_ids = conversationIds,
          lookback_hours = 24
        }
      }
    });
    using BinaryContent runContent = BinaryContent.Create(runData);
    ClientResult evaluationRun = await evaluationClient.CreateEvaluationRunAsync(
      evaluationId: evaluationId,
      content: runContent);
    Console.WriteLine($"Evaluation run created: {GetString(evaluationRun, "id")}");

リファレンス: EvaluationClient プロトコルメソッド

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

const projectEndpoint =
  process.env.AZURE_AI_PROJECT_ENDPOINT ?? "<project endpoint>";
const modelDeploymentName =
  process.env.AZURE_AI_MODEL_DEPLOYMENT_NAME ?? "<model deployment name>";
const conversationIds = ["conversation_1234", "conversation_5678"];

const projectClient = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);
const openAIClient = projectClient.getOpenAIClient();

const evaluator = (name: string, includeToolDefinitions = false) => ({
  type: "azure_ai_evaluator",
  name,
  evaluator_name: `builtin.${name}`,
  initialization_parameters: { model: modelDeploymentName },
  data_mapping: includeToolDefinitions
    ? {
        messages: "{{item.messages}}",
        tool_definitions: "{{item.tool_definitions}}",
      }
    : { messages: "{{item.messages}}" },
});

const testingCriteria = [
  evaluator("output_quality", true),
  evaluator("tool_use_quality", true),
  evaluator("deflection_rate", true),
  evaluator("customer_satisfaction"),
  evaluator("task_completion"),
  evaluator("coherence"),
  evaluator("groundedness"),
];

const evaluation = await openAIClient.evals.create({
  name: "Multi-turn Trace Evaluation (by ID)",
  data_source_config: {
    type: "azure_ai_source",
    scenario: "traces",
  } as any,
  testing_criteria: testingCriteria as any,
});

const evaluationRun = await openAIClient.evals.runs.create(evaluation.id, {
  name: "multiturn-trace-by-id-run",
  data_source: {
    type: "azure_ai_trace_data_source_preview",
    trace_source: {
      type: "conversation_id_source",
      conversation_ids: conversationIds,
      lookback_hours: 24,
    },
  },
  evaluation_level: "conversation",
} as any);

console.log(`Evaluation run created: ${evaluationRun.id}`);

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "conversation-trace-eval",
    "evaluation_level": "conversation",
    "data_source": {
      "type": "azure_ai_trace_data_source_preview",
      "trace_source": {
        "type": "conversation_id_source",
        "conversation_ids": ["conversation_1234", "conversation_5678"],
        "lookback_hours": 24,
        "end_time": "2026-05-21T00:00:00Z"
      }
    }
  }'

Note

Application Insights のデータインジェストにより、トレースが生成されてから評価に使用できるようになるまでの間に遅延が発生する可能性があります。クエリでトレースが見つからない場合は、数分待ってから再試行してください。
明示的な時間枠を指定しない場合、トレースクエリの既定値は過去 7 日間 (168 時間) です。過去の期間またはカスタム間隔に対してクエリを実行するには、Application Insights のリテンション期間に従って、start_time と end_time を指定します。

実行可能な完全な例については、GitHub の Python SDK バージョン 2.7.0 の sample_multiturn_trace_evaluation_by_id.py を参照してください。

エージェントフィルターによるサンプリングされた会話の評価

エージェント名をフィルター処理して、Application Insights からサンプリングされた会話のセットを評価します。このオプションを使用して、運用環境のトラフィック全体におけるエージェントの品質を評価します。たとえば、定期的な品質評価を実行したり、運用環境での品質低下を監視したりします。

フィルター処理に指定するエージェントは、マルチエージェント会話の一部にすることができます。このフィルターは、そのエージェントが参加したすべての会話と一致します。

Note

ツール定義は、トレースから自動的に取得されるか、エージェントレジストリから照会されます。要求で指定する必要はありません。

エージェント ID フィールド

次のいずれかの形式を使用して、フィルター処理するエージェントを指定します。

Format	Example	説明
`agent_name` + `agent_version`	`"agent_name": "my-agent", "agent_version": "1"`	2 つの異なるフィールド。 `agent_version`を省略した場合は、最新バージョンを使用します。
`agent_id`	`"agent_id": "my-agent:1"`	`"name:version"`形式の 1 つの文字列。

フィルター戦略

戦略	説明
`random_sampling`	(既定値) 最大 `max_traces` 件の会話を一様ランダムにサンプリングします。
`smart_filtering`	潜在的な問題、エッジケース、または異常を含む会話などの「興味深い」トレースを優先する傾向のある、サービス管理型ヒューリスティック。

Parameters

パラメーター	必須	説明
`agent_name`	はい	トレースをフィルター処理するエージェント名。
`agent_version`	いいえ	エージェントのバージョン。省略した場合は、最新バージョンを使用します。
`agent_id`	いいえ	`agent_name` + `agent_version`に代わるもの。 `"name:version"`形式の 1 つの文字列。
`start_time`	はい	時間ウィンドウの開始（Unixエポック秒数、UTC）。
`end_time`	いいえ	時間ウィンドウの終了（Unixエポック秒数、UTC）。既定値は現在の UTC 時刻です。ウィンドウ境界でのインジェストの遅延を回避するために、+600 秒の余裕を持たせます。
`max_traces`	いいえ	サンプリングする最大会話数。既定値は 1,000 です。
`filter_strategy`	いいえ	`"random_sampling"` (既定) または `"smart_filtering"` (関心のあるトレースに偏るサービス管理ヒューリスティック)。

Important

時間枠 (end_time - start_time) は 、少なくとも 15 分 (900 秒) である必要があります。この要件が存在するのは、会話レベルのクエリでは、部分的な会話を回避するために、各エッジに 5 分間の非アクティブバッファーが適用されるためです。

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ.get("FOUNDRY_AGENT_VERSION", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="output_quality",
            evaluator_name="builtin.output_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="tool_use_quality",
            evaluator_name="builtin.tool_use_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="deflection_rate",
            evaluator_name="builtin.deflection_rate",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (Agent Filter)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Compute time window in unix seconds
    # Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
    now_unix = int(time.time())
    end_time = now_unix + 600
    start_time = now_unix - (24 * 3600)  # 24 hours lookback

    # Build trace_source with agent filter
    trace_source = {
        "type": "agent_filter",
        "agent_name": agent_name,
        "start_time": start_time,
        "end_time": end_time,
        "max_traces": 5,
    }
    if agent_version:
        trace_source["agent_version"] = agent_version

    # Run evaluation on sampled agent conversations
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-agent-filter-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": trace_source,
        },
        extra_body={"evaluation_level": "conversation"},
    )

データスキーマとエバリュエーターの定義に関するページのtestingCriteria値を使用します。 FOUNDRY_AGENT_NAMEを設定します。特定のエージェントバージョンを評価するには、 FOUNDRY_AGENT_VERSIONも設定します。それ以外の場合は、最新バージョンが使用されます。

var agentName = Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")
  ?? throw new InvalidOperationException("FOUNDRY_AGENT_NAME isn't set.");
var agentVersion = Environment.GetEnvironmentVariable(
  "FOUNDRY_AGENT_VERSION");
long now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
var traceSource = new Dictionary<string, object>
{
  ["type"] = "agent_filter",
  ["agent_name"] = agentName,
  ["start_time"] = now - (24 * 3600),
  ["end_time"] = now + 600,
  ["max_traces"] = 5,
  ["filter_strategy"] = "random_sampling"
};
if (!string.IsNullOrWhiteSpace(agentVersion))
{
  traceSource["agent_version"] = agentVersion;
}

BinaryData evaluationData = BinaryData.FromObjectAsJson(new
{
  name = "Multi-turn Trace Evaluation (Agent Filter)",
  data_source_config = new
  {
    type = "azure_ai_source",
    scenario = "traces"
  },
  testing_criteria = testingCriteria
});
using BinaryContent evaluationContent = BinaryContent.Create(evaluationData);
ClientResult evaluation = await evaluationClient.CreateEvaluationAsync(
  evaluationContent);
string evaluationId = GetString(evaluation, "id");

BinaryData runData = BinaryData.FromObjectAsJson(new
{
  name = "multiturn-agent-filter-run",
  evaluation_level = "conversation",
  data_source = new
  {
    type = "azure_ai_trace_data_source_preview",
    trace_source = traceSource
  }
});
using BinaryContent runContent = BinaryContent.Create(runData);
ClientResult evaluationRun = await evaluationClient.CreateEvaluationRunAsync(
  evaluationId: evaluationId,
  content: runContent);
Console.WriteLine($"Evaluation run created: {GetString(evaluationRun, "id")}");

リファレンス: EvaluationClient プロトコルメソッド

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

const projectEndpoint =
  process.env.AZURE_AI_PROJECT_ENDPOINT ?? "<project endpoint>";
const modelDeploymentName =
  process.env.AZURE_AI_MODEL_DEPLOYMENT_NAME ?? "<model deployment name>";
const agentName = process.env.FOUNDRY_AGENT_NAME ?? "<agent name>";
const agentVersion = process.env.FOUNDRY_AGENT_VERSION ?? "";

const projectClient = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);
const openAIClient = projectClient.getOpenAIClient();

const evaluator = (name: string, includeToolDefinitions = false) => ({
  type: "azure_ai_evaluator",
  name,
  evaluator_name: `builtin.${name}`,
  initialization_parameters: { model: modelDeploymentName },
  data_mapping: includeToolDefinitions
    ? {
        messages: "{{item.messages}}",
        tool_definitions: "{{item.tool_definitions}}",
      }
    : { messages: "{{item.messages}}" },
});

const testingCriteria = [
  evaluator("output_quality", true),
  evaluator("tool_use_quality", true),
  evaluator("deflection_rate", true),
  evaluator("customer_satisfaction"),
  evaluator("task_completion"),
  evaluator("coherence"),
  evaluator("groundedness"),
];

const evaluation = await openAIClient.evals.create({
  name: "Multi-turn Trace Evaluation (Agent Filter)",
  data_source_config: {
    type: "azure_ai_source",
    scenario: "traces",
  } as any,
  testing_criteria: testingCriteria as any,
});

const now = Math.floor(Date.now() / 1000);
const traceSource: Record<string, unknown> = {
  type: "agent_filter",
  agent_name: agentName,
  start_time: now - 24 * 60 * 60,
  end_time: now + 10 * 60,
  max_traces: 100,
  filter_strategy: "random_sampling",
  ...(agentVersion ? { agent_version: agentVersion } : {}),
};

const evaluationRun = await openAIClient.evals.runs.create(evaluation.id, {
  name: "multiturn-agent-filter-run",
  data_source: {
    type: "azure_ai_trace_data_source_preview",
    trace_source: traceSource,
  },
  evaluation_level: "conversation",
} as any);

console.log(`Evaluation run created: ${evaluationRun.id}`);

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-quality-eval",
    "evaluation_level": "conversation",
    "data_source": {
      "type": "azure_ai_trace_data_source_preview",
      "trace_source": {
        "type": "agent_filter",
        "agent_name": "my-support-agent",
        "agent_version": "1",
        "start_time": 1743465600,
        "end_time": 1743552600,
        "max_traces": 100,
        "filter_strategy": "random_sampling"
      }
    }
  }'

Note

明示的な時間枠を指定しない場合、トレースクエリの既定値は過去 7 日間 (168 時間) です。エージェントフィルタークエリでは、start_time が正確に適用されます。 end_timeを省略すると、サービスは現在の UTC 時刻を使用します。 Application Insights のリテンション期間の制限内で、過去の期間またはカスタム間隔に対してクエリを実行できます。

次のステップ

完了するまでポーリングして結果を解釈するには、「クラウド評価結果を取得する」を参照してください。
実行可能な完全な例については、GitHub 上の Python SDK バージョン 2.7.0 の sample_multiturn_trace_evaluation_agent_filter.py を参照してください。
保存されている会話を評価するには、「会話データセットを評価する」を参照してください。
合成会話を生成するには、「エージェントの会話をシミュレートする」を参照してください。

フィードバック

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

最終更新: 2026-10-08

Microsoft Foundry SDK を使用してデプロイされたモデルとエージェントの会話を評価する (プレビュー)

前提条件

トレースからの ID による会話の評価

会話 ID を検索する場所

会話ID検索のパラメーター

エージェント フィルターによるサンプリングされた会話の評価

エージェント ID フィールド

フィルター戦略

Parameters

次のステップ

フィードバック

その他のリソース

エージェントフィルターによるサンプリングされた会話の評価