Quickstart: Uw gehoste agent evalueren

Vanuit uw projectmap azd controleert u of de agent is geïnstalleerd en kan worden aangeroepen:

azd ai agent show

Een testprompt verzenden:

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

U ziet binnen een paar seconden een antwoord.

1. Open de Foundry-portal en ga naar uw project.
2. Selecteer uw agent en selecteer vervolgens het tabblad Speeltuin .
3. Een testprompt verzenden, zoals Write a haiku about deploying cloud applications.

U ziet binnen een paar seconden een antwoord.

Installeer de Foundry SDK:

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

Stel twee omgevingsvariabelen in en maak vervolgens de projectclient. Stel FOUNDRY_PROJECT_ENDPOINT in op het eindpunt van je project en FOUNDRY_MODEL_NAME op een chat-completion-implementatie die als beoordelingsmodel moet worden gebruikt. In de volgende codevoorbeelden wordt ervan uitgegaan dat u deze in deze context uitvoert:

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

Controleer of uw geïmplementeerde agent geregistreerd en beschikbaar is. Vervang door <your-agent-name> de naam van uw gehoste agent:

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

De aanroep retourneert de agent als deze bestaat, of genereert een fout als de naam onjuist is of als de agent niet is gedeployed.

Installeer de Foundry SDK en de OpenAI evals-client:

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

Stel twee omgevingsvariabelen in en maak vervolgens de clients. Stel FOUNDRY_PROJECT_ENDPOINT in op het eindpunt van je project en FOUNDRY_MODEL_NAME op een chat-completion-implementatie die als beoordelingsmodel moet worden gebruikt. In de volgende codevoorbeelden wordt ervan uitgegaan dat u deze in deze context uitvoert:

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

Controleer of uw geïmplementeerde agent geregistreerd en beschikbaar is. Vervang door <your-agent-name> de naam van uw gehoste agent:

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

De aanroep retourneert de agent als deze bestaat, of genereert een fout als de naam onjuist is of als de agent niet is gedeployed.

Installeer de Foundry SDK:

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

Stel twee omgevingsvariabelen in en maak vervolgens de projectclient. Stel FOUNDRY_PROJECT_ENDPOINT in op het eindpunt van je project en FOUNDRY_MODEL_NAME op een chat-completion-implementatie die als beoordelingsmodel moet worden gebruikt. In de volgende codevoorbeelden wordt ervan uitgegaan dat u deze in deze context uitvoert:

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

Controleer of uw geïmplementeerde agent geregistreerd en beschikbaar is. Vervang door <your-agent-name> de naam van uw gehoste agent:

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

De aanroep retourneert de agent als deze bestaat, of genereert een fout als de naam onjuist is of als de agent niet is gedeployed.

Referentie: AIProjectClient-klasse

Maak eerst een JSONL-bestand met testquery's voor uw agent. Elke regel is een JSON-object met een query veld. Sla deze op in de bronmap van uw agent, zoals src/<your-agent-name>/tests/queries.jsonl:

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

Maak vervolgens een eval.yaml bestand in dezelfde bronmap van de agent, als src/<your-agent-name>/eval.yaml. Deze verwijst naar uw gegevensset en vermeldt de ingebouwde evaluators die moeten worden toegepast. Het dataset.local_uri-pad is relatief aan deze map. Vervang <your-agent-name> door de naam van uw gehoste agent en <your-chat-completion-deployment> door de implementatie van het beoordelaarsmodel:

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

De eval_model waarde is het rechtermodel dat reacties beoordeelt. U kunt de implementatie die uw agent al gebruikt, opnieuw gebruiken.

1. Open uw agent in de Foundry-portal en selecteer het tabblad Evaluatie en selecteer vervolgens Maken.
2. Selecteer Agent voor Evaluatiedoel selecteren.
3. Voor Evaluatiebereik selecteren, selecteert u Afzonderlijke beurten.
4. Voor Gegevensbron selecteren selecteert u Bestaande gegevensset en kiest u een CSV- of JSONL-bestand met testquery's uit de gegevensassets van uw project.
5. Als de stap Agents configureren wordt weergegeven, controleert u de agent en accepteert u de standaardprompt {{item.query}}van de gebruiker. Pas deze alleen aan als uw agent een andere invoerindeling verwacht.
6. Voor Testcriteria selecteren selecteert u een of meer agentbeoordelaars, zoals Taaknaleving en Intentherkenning.

Houd de wizard geopend. U dient de evaluatie in de volgende stap in.

Maak eerst een JSONL-bestand met testquery's voor uw agent. Elke regel is een JSON-object met een query veld. Sla het op als queries.jsonl:

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

Upload het bestand als een gegevensset in uw project:

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

Kies vervolgens ingebouwde evaluators en wijs hun invoer toe. De data_mapping parameter vertelt elke evaluator waar de query en het agentantwoord moeten worden gevonden. AI-ondersteunde evaluators hebben een beoordelingsmodel nodig in initialization_parameters; de waarde moet een chat-completion-implementatie in uw project zijn.

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

Maak de evaluatie. Het definieert het testgegevensschema en testcriteria en fungeert als een container voor een of meer uitvoeringen:

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

Maak eerst een JSONL-bestand met testquery's voor uw agent. Elke regel is een JSON-object met een query veld. Sla het op als queries.jsonl:

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

Upload het bestand als een gegevensset in uw project:

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

Kies vervolgens ingebouwde evaluators en wijs hun invoer toe. De data_mapping parameter vertelt elke evaluator waar de query en het agentantwoord moeten worden gevonden. AI-ondersteunde evaluators hebben een beoordelingsmodel nodig in initialization_parameters; de waarde moet een chat-completion-implementatie in uw project zijn.

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

Maak de evaluatie. Het definieert het testgegevensschema en testcriteria en fungeert als een container voor een of meer uitvoeringen:

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

Maak eerst een JSONL-bestand met testquery's voor uw agent. Elke regel is een JSON-object met een query veld. Sla het op als queries.jsonl:

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

Upload het bestand als een gegevensset in uw project:

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

Kies vervolgens ingebouwde evaluators en wijs hun invoer toe. De data_mapping parameter vertelt elke evaluator waar de query en het agentantwoord moeten worden gevonden. AI-ondersteunde evaluators hebben een beoordelingsmodel nodig in initialization_parameters; de waarde moet een chat-completion-implementatie in uw project zijn.

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

Maak de evaluatie. Het definieert het testgegevensschema en testcriteria en fungeert als een container voor een of meer uitvoeringen:

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

Voer de evaluatie uit vanuit de hoofdmap van de azd-werkruimte:

azd ai agent eval run --config eval.yaml

De opdracht leest eval.yaml, verzendt elke query naar uw agent, beoordeelt de antwoorden en drukt een samenvatting af wanneer deze is voltooid:

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. Voer in de stap Controleren en verzenden een naam in voor de evaluatie.
2. Bekijk het doel, het bereik, de gegevensbron en de geselecteerde evaluators.
3. Selecteer Verzenden om de uitvoering te starten.

Maak een uitvoering waarmee elke testquery naar uw agent wordt verzonden en de evaluators worden toegepast. Vervang door <your-agent-name> de naam van uw gehoste agent:

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

Maak een uitvoering waarmee elke testquery naar uw agent wordt verzonden en de evaluators worden toegepast. Vervang door <your-agent-name> de naam van uw gehoste agent:

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

Maak een uitvoering waarmee elke testquery naar uw agent wordt verzonden en de evaluators worden toegepast. Vervang door <your-agent-name> de naam van uw gehoste agent:

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

Lijst met recente evaluaties:

azd ai agent eval list

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

* = active eval in current environment

Geef de meest recente evaluatie en de bijbehorende runs weer:

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

Gebruik de resultaten om te controleren welke agentversie is geëvalueerd en welke evaluatorscores zijn geproduceerd. Als u details per evaluator en een koppeling naar het rapport in de Foundry-portal wilt bekijken, voert u de opdracht uit azd ai agent eval show <eval-id> --eval-run-id <run-id>.

1. Op de detailpagina ziet u het doel, de gegevensset, de status, het tokengebruik en een statistische score voor elke evaluator.
2. Selecteer de uitvoeringsnaam om resultaten op rijniveau weer te geven: elke query, het agentantwoord, de beoordelingsscore en de uitleg van de score.

Peiling voor voltooiing en druk vervolgens de status en de rapport-URL af waarmee de resultaten worden geopend in de Foundry-portal:

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

Op het niveau van de uitvoering ziet u het totaalaantal geslaagde en mislukte pogingen voor elke evaluator:

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

Geef voor detail op rijniveau de uitvoeritems weer. Elk resultaat bevat de naam van de evaluator, geslaagd of mislukt en een 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)

Peiling voor voltooiing en druk vervolgens de status en de rapport-URL af waarmee de resultaten worden geopend in de Foundry-portal:

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

Op het niveau van de uitvoering ziet u het totaalaantal geslaagde en mislukte pogingen voor elke evaluator:

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

Geef voor detail op rijniveau de uitvoeritems weer. Elk resultaat bevat de naam van de evaluator, geslaagd of mislukt en een 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")}");
    }
}

Peiling voor voltooiing en druk vervolgens de status en de rapport-URL af waarmee de resultaten worden geopend in de Foundry-portal:

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

Op het niveau van de uitvoering ziet u het totaalaantal geslaagde en mislukte pogingen voor elke evaluator:

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

Geef voor detail op rijniveau de uitvoeritems weer. Elk resultaat bevat de naam van de evaluator, geslaagd of mislukt en een 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);
  }
}