Valutare le conversazioni di modelli e agenti distribuite con Microsoft Foundry SDK (anteprima)

Valuta le intere conversazioni di produzione acquisite tramite Application Insights per analizzare interazioni specifiche o campionare il traffico degli agenti distribuiti.

Prerequisiti

Completare i prerequisiti di valutazione cloud e la configurazione del client.
Per il workflow di valutazione delle tracce in anteprima, usare Python SDK versione 2.7.0 (pip install "azure-ai-projects==2.7.0") o JavaScript SDK versione 2.7.0 (npm install "@azure/ai-projects@2.7.0").
Conversazioni di produzione tracciate in Application Insights.
Valutatori a livello di conversazione che supportano il livello di valutazione selezionato.

Gli esempi usano il client SDK configurato in Configurare il client SDK.

Valutare le conversazioni in base all'ID dalle tracce

Valuta conversazioni specifiche in Application Insights fornendo i relativi ID di conversazione. Usare questa opzione per risolvere i problemi di causa radice o verificare le correzioni per interazioni specifiche. Ad esempio, è possibile analizzare una conversazione contrassegnata da un avviso o verificare una correzione per un problema noto.

Dove trovare gli ID della conversazione

Trovare gli ID delle conversazioni in:

Interfaccia utente dei registri delle tracce di Application Insights — Accedi alle tracce di tuo interesse e individua il campo conversation_id nei dettagli della traccia.
I dati di log della tua applicazione — Se hai impostato esplicitamente conversation_id durante la creazione delle risposte dell'agente, recuperali dai tuoi log.
Contesto di traccia OpenTelemetry — Il conversation_id può anche essere derivato dall'intestazione traceparent se l'agente utilizza la propagazione standard del contesto di traccia.

Annotazioni

Le definizioni degli strumenti vengono recuperate automaticamente dalle tracce o richieste al registro dell'agente. Non è necessario specificarli nella richiesta.

Parametri per la ricerca dell'ID della conversazione

Parametro	Obbligatorio	Descrizione
`conversation_ids`	Yes	Matrice di ID delle conversazioni da valutare.
`lookback_hours`	No	Ore da ricercare a partire da `end_time`. Il valore predefinito è sette giorni (168 ore).
`start_time`	No	Inizio di una finestra di ricerca esplicita (formato ISO 8601). Per la ricerca basata su ID, specificare sia `start_time` che `end_time` per usare una finestra esplicita anziché `lookback_hours`.
`end_time`	No	Fine della finestra di ricerca (formato ISO 8601). L'impostazione predefinita è l'ora corrente. Fornirlo con `start_time` per usare una finestra esplicita.

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"},
    )

Usare i valori dataSourceConfig e testingCriteria da Definire lo schema dei dati e i valutatori.

    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")}");

Riferimento: EvaluationClient metodi di protocollo

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"
      }
    }
  }'

Annotazioni

L'inserimento dati di Application Insights può causare un ritardo tra quando vengono generate tracce e quando sono disponibili per la valutazione. Se la query non trova tracce, attendere alcuni minuti e riprovare.
Per impostazione predefinita, le query di traccia si riferiscono agli ultimi 7 giorni (168 ore) quando non si specifica un intervallo di tempo esplicito. Per eseguire query su un intervallo precedente o personalizzato, specificare start_time e end_time, soggetto alla conservazione di Application Insights.

Per un esempio eseguibile completo, vedere sample_multiturn_trace_evaluation_by_id.py da Python SDK versione 2.7.0 in GitHub.

Valutare le conversazioni campionate in base al filtro dell'agente

Valutare un set campionato di conversazioni da Application Insights filtrando il nome dell'agente. Utilizza questa opzione per valutare la qualità complessiva degli agenti sul traffico di produzione. Ad esempio, eseguire valutazioni di qualità regolari o monitorare la riduzione della qualità nell'ambiente di produzione.

L'agente specificato per il filtro può far parte di una conversazione multi-agente. Il filtro corrisponde a qualsiasi conversazione in cui l'agente ha partecipato.

Annotazioni

Le definizioni degli strumenti vengono recuperate automaticamente dalle tracce o richieste al registro dell'agente. Non è necessario specificarli nella richiesta.

Campi dell'identità dell'agente

Specificare l'agente da filtrare usando uno dei formati seguenti:

Format	Example	Descrizione
`agent_name` + `agent_version`	`"agent_name": "my-agent", "agent_version": "1"`	Due campi separati. Se `agent_version` viene omesso, usare la versione più recente.
`agent_id`	`"agent_id": "my-agent:1"`	Stringa singola in `"name:version"` formato.

Strategie di filtro

Strategy	Descrizione
`random_sampling`	(Impostazione predefinita) Campione casuale uniforme fino a `max_traces` conversazioni.
`smart_filtering`	Euristica gestita dal servizio che privilegia le tracce "interessanti" - conversazioni con potenziali problemi, casi limite o anomalie.

Parameters

Parametro	Obbligatorio	Descrizione
`agent_name`	Yes	Nome dell'agente per cui filtrare le tracce.
`agent_version`	No	Versione dell'agente. Se omesso, usa la versione più recente.
`agent_id`	No	Alternativa a `agent_name` + `agent_version`. Stringa singola in formato `"name:version"`.
`start_time`	Yes	Inizio dell'intervallo di tempo (secondi dell'epoca Unix, UTC).
`end_time`	No	Fine dell'intervallo di tempo (secondi dell'epoca Unix, UTC). Il valore predefinito è l'ora UTC corrente. Aggiungere 600 secondi di margine per evitare il ritardo di acquisizione al limite della finestra.
`max_traces`	No	Numero massimo di conversazioni da campionare. Il valore predefinito è 1.000.
`filter_strategy`	No	`"random_sampling"` (predefinito) o `"smart_filtering"` (euristica gestita dal servizio che privilegia le tracce interessanti).

Importante

L'intervallo di tempo (end_time - start_time) deve essere di almeno 15 minuti (900 secondi). Questo requisito è previsto perché le query a livello di conversazione applicano un intervallo di inattività di 5 minuti su ogni nodo per evitare conversazioni incomplete.

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"},
    )

Utilizzare il valore testingCriteria da Definire lo schema dei dati e i valutatori. Imposta FOUNDRY_AGENT_NAME. Per valutare una versione specifica dell'agente, impostare anche FOUNDRY_AGENT_VERSION; in caso contrario, viene utilizzata la versione più recente.

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")}");

Riferimento: EvaluationClient metodi di protocollo

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"
      }
    }
  }'

Annotazioni

Per impostazione predefinita, le query di traccia si riferiscono agli ultimi 7 giorni (168 ore) quando non si specifica un intervallo di tempo esplicito. Le query di filtro agente rispettano start_time esattamente. Se si omette end_time, il servizio usa l'ora UTC corrente. È possibile eseguire query su intervalli precedenti o personalizzati entro i limiti di conservazione di Application Insights.

Passaggi successivi

Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati della valutazione cloud.
Per un esempio eseguibile completo, vedere sample_multiturn_trace_evaluation_agent_filter.py da Python SDK versione 2.7.0 in GitHub.
Per valutare le conversazioni archiviate, vedere Valutare i set di dati delle conversazioni.
Per generare conversazioni sintetiche, vedere Simulare le conversazioni degli agenti.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-10-08

Valutare le conversazioni di modelli e agenti distribuite con Microsoft Foundry SDK (anteprima)

Prerequisiti

Valutare le conversazioni in base all'ID dalle tracce

Dove trovare gli ID della conversazione

Parametri per la ricerca dell'ID della conversazione

Valutare le conversazioni campionate in base al filtro dell'agente

Campi dell'identità dell'agente

Strategie di filtro

Parameters

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive