Démarrage rapide : Évaluer votre agent hébergé

À partir de votre azd répertoire de projet, vérifiez que l’agent est déployé et invoquable :

azd ai agent show

Envoyez une invite de test :

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

Vous devriez voir une réponse en quelques secondes.

1. Ouvrez le portail Foundry et accédez à votre projet.
2. Sélectionnez votre agent, puis sélectionnez l’onglet Terrain de jeu .
3. Envoyer une invite de test, par exemple Write a haiku about deploying cloud applications.

Vous devriez voir une réponse en quelques secondes.

Installez le Kit de développement logiciel (SDK) Foundry :

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

Définissez deux variables d’environnement, puis créez le client de projet. Définissez FOUNDRY_PROJECT_ENDPOINT sur le point de terminaison de votre projet et FOUNDRY_MODEL_NAME sur un déploiement de complétion de conversation à utiliser comme modèle d’évaluation. Les exemples de code suivants supposent que vous les exécutez dans ce contexte :

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()

Vérifiez que votre agent déployé est inscrit et disponible. Remplacez <your-agent-name> par le nom de votre agent hébergé :

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

L’appel renvoie l’agent s’il existe, ou génère une erreur si le nom est incorrect ou si l’agent n’est pas déployé.

Installez le Kit de développement logiciel (SDK) Foundry et le client OpenAI evals :

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

Définissez deux variables d’environnement, puis créez les clients. Définissez FOUNDRY_PROJECT_ENDPOINT sur le point de terminaison de votre projet et FOUNDRY_MODEL_NAME sur un déploiement de complétion de conversation à utiliser comme modèle d’évaluation. Les exemples de code suivants supposent que vous les exécutez dans ce contexte :

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

Vérifiez que votre agent déployé est inscrit et disponible. Remplacez <your-agent-name> par le nom de votre agent hébergé :

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

L’appel renvoie l’agent s’il existe, ou génère une erreur si le nom est incorrect ou si l’agent n’est pas déployé.

Installez le Kit de développement logiciel (SDK) Foundry :

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

Définissez deux variables d’environnement, puis créez le client de projet. Définissez FOUNDRY_PROJECT_ENDPOINT sur le point de terminaison de votre projet et FOUNDRY_MODEL_NAME sur un déploiement de complétion de conversation à utiliser comme modèle d’évaluation. Les exemples de code suivants supposent que vous les exécutez dans ce contexte :

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();

Vérifiez que votre agent déployé est inscrit et disponible. Remplacez <your-agent-name> par le nom de votre agent hébergé :

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

L’appel renvoie l’agent s’il existe, ou génère une erreur si le nom est incorrect ou si l’agent n’est pas déployé.

Référence : classe AIProjectClient

Tout d’abord, créez un fichier JSONL de requêtes de test pour votre agent. Chaque ligne est un objet JSON avec un query champ. Enregistrez-le dans le dossier source de votre agent, sous src/<your-agent-name>/tests/queries.jsonl :

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

Créez ensuite un eval.yaml fichier dans le même dossier source de l’agent, comme src/<your-agent-name>/eval.yaml. Il pointe vers votre jeu de données et répertorie les évaluateurs intégrés à appliquer. Le dataset.local_uri chemin d’accès est relatif à ce dossier. Remplacez <your-agent-name> par le nom de votre agent hébergé et <your-chat-completion-deployment> par le déploiement du modèle juge :

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

La valeur eval_model est le modèle juge qui évalue les réponses ; vous pouvez réutiliser le déploiement déjà utilisé par votre agent.

1. Dans le portail Foundry, ouvrez votre agent et sélectionnez l’onglet Évaluation , puis sélectionnez Créer.
2. Pour sélectionner la cible d’évaluation, sélectionnez Agent.
3. Pour sélectionner l’étendue d’évaluation, sélectionnez Sélection individuelle.
4. Pour Sélectionner une source de données, sélectionnez Jeu de données existant et choisissez un fichier CSV ou JSONL de requêtes de test à partir des ressources de données de votre projet.
5. Si l’étape Configurer les agents s’affiche, passez en revue l’agent et acceptez l’invite utilisateur par défaut. {{item.query}} Ajustez-le uniquement si votre agent attend un autre format d’entrée.
6. Pour sélectionner des critères de test, sélectionnez un ou plusieurs évaluateurs d’agent, tels que l’adhésion aux tâches et la résolution d’intention.

Laissez l’Assistant ouvert. Vous soumettez l’évaluation à l’étape suivante.

Tout d’abord, créez un fichier JSONL de requêtes de test pour votre agent. Chaque ligne est un objet JSON avec un query champ. Enregistrez-le sous queries.jsonl :

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

Chargez le fichier en tant que jeu de données dans votre projet :

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

Ensuite, choisissez les évaluateurs intégrés et mappez leurs entrées. Le data_mapping paramètre indique à chaque évaluateur où trouver la requête et la réponse de l’agent. Les évaluateurs assistés par l’IA ont besoin d’un modèle de juge dans initialization_parameters ; la valeur doit être un déploiement d’achèvement de conversation dans votre projet.

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

Créez l’évaluation. Il définit le schéma de données de test et les critères de test, et sert de conteneur pour une ou plusieurs exécutions :

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

Tout d’abord, créez un fichier JSONL de requêtes de test pour votre agent. Chaque ligne est un objet JSON avec un query champ. Enregistrez-le sous queries.jsonl :

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

Chargez le fichier en tant que jeu de données dans votre projet :

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

Ensuite, choisissez les évaluateurs intégrés et mappez leurs entrées. Le data_mapping paramètre indique à chaque évaluateur où trouver la requête et la réponse de l’agent. Les évaluateurs assistés par l’IA ont besoin d’un modèle de juge dans initialization_parameters ; la valeur doit être un déploiement d’achèvement de conversation dans votre projet.

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

Créez l’évaluation. Il définit le schéma de données de test et les critères de test, et sert de conteneur pour une ou plusieurs exécutions :

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

Tout d’abord, créez un fichier JSONL de requêtes de test pour votre agent. Chaque ligne est un objet JSON avec un query champ. Enregistrez-le sous queries.jsonl :

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

Chargez le fichier en tant que jeu de données dans votre projet :

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

Ensuite, choisissez les évaluateurs intégrés et mappez leurs entrées. Le data_mapping paramètre indique à chaque évaluateur où trouver la requête et la réponse de l’agent. Les évaluateurs assistés par l’IA ont besoin d’un modèle de juge dans initialization_parameters ; la valeur doit être un déploiement d’achèvement de conversation dans votre projet.

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}}",
    },
  },
];

Créez l’évaluation. Il définit le schéma de données de test et les critères de test, et sert de conteneur pour une ou plusieurs exécutions :

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

Exécutez l’évaluation à partir de la racine de l’espace de travail azd :

azd ai agent eval run --config eval.yaml

La commande lit eval.yaml, envoie chaque requête à votre agent, note les réponses et imprime un résumé lorsqu’il se termine :

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. À l’étape Vérifier et envoyer , entrez un nom pour l’évaluation.
2. Passez en revue la cible, l’étendue, la source de données et les évaluateurs sélectionnés.
3. Sélectionnez Envoyer pour démarrer l’exécution.

Créez une exécution qui envoie chaque requête de test à votre agent et applique les évaluateurs. Remplacez <your-agent-name> par le nom de votre agent hébergé :

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

Créez une exécution qui envoie chaque requête de test à votre agent et applique les évaluateurs. Remplacez <your-agent-name> par le nom de votre agent hébergé :

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

Créez une exécution qui envoie chaque requête de test à votre agent et applique les évaluateurs. Remplacez <your-agent-name> par le nom de votre agent hébergé :

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

Répertorier les évaluations récentes :

azd ai agent eval list

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

* = active eval in current environment

Affichez l’évaluation la plus récente et ses exécutions :

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

Utilisez les résultats pour confirmer la version de l’agent évaluée et les scores de l’évaluateur générés. Pour afficher les détails par évaluateur et un lien vers le rapport dans le portail Foundry, exécutez azd ai agent eval show <eval-id> --eval-run-id <run-id>.

1. La page de détails affiche la cible, le jeu de données, l’état, l’utilisation des jetons et un score agrégé pour chaque évaluateur.
2. Sélectionnez le nom d’exécution pour afficher les résultats au niveau des lignes : chaque requête, la réponse de l’agent, le score de l’évaluateur et l’explication du score.

Attendez la fin de l’opération, puis affichez l’état et l’URL du rapport permettant d’ouvrir les résultats dans le portail Foundry :

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

Au niveau de l’exécution, vous pouvez voir les nombres agrégés de réussites et d’échecs pour chaque évaluateur :

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

Pour obtenir un niveau de détail ligne par ligne, listez les éléments de sortie. Chaque résultat inclut le nom, la réussite ou l’échec de l’évaluateur et un score :

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)

Vérifiez régulièrement si l’opération est terminée, puis affichez l’état et l’URL du rapport permettant d’ouvrir les résultats dans le portail Foundry :

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

Au niveau de l’exécution, vous pouvez voir les nombres agrégés de réussites et d’échecs pour chaque évaluateur :

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

Pour obtenir un niveau de détail ligne par ligne, listez les éléments de sortie. Chaque résultat inclut le nom, la réussite ou l’échec de l’évaluateur et un score :

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

Vérifiez régulièrement si l’opération est terminée, puis affichez l’état et l’URL du rapport permettant d’ouvrir les résultats dans le portail Foundry :

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

Au niveau de l’exécution, vous pouvez voir les nombres agrégés de réussites et d’échecs pour chaque évaluateur :

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

Pour obtenir un niveau de détail ligne par ligne, listez les éléments de sortie. Chaque résultat inclut le nom, la réussite ou l’échec de l’évaluateur et un score :

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