Guida introduttiva: Valuta l'agente ospitato

Dalla directory del progetto azd, verificare che l'agente sia distribuito e richiamabile:

azd ai agent show

Inviare una richiesta di test:

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

Verrà visualizzata una risposta entro pochi secondi.

1. Aprire il portale Foundry e vai al tuo progetto.
2. Selezionare l'agente e quindi selezionare la scheda Playground .
3. Inviare una richiesta di test, ad esempio Write a haiku about deploying cloud applications.

Verrà visualizzata una risposta entro pochi secondi.

Installare l'SDK Foundry:

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

Impostare due variabili di ambiente e quindi creare il client del progetto. Impostare FOUNDRY_PROJECT_ENDPOINT sull'endpoint del progetto e FOUNDRY_MODEL_NAME su una distribuzione per il completamento della chat da usare come modello di valutazione. Gli esempi di codice seguenti presuppongono che vengano eseguiti in questo contesto:

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

Verificare che l'agente distribuito sia registrato e disponibile. Sostituire <your-agent-name> con il nome dell'agente ospitato:

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

La chiamata restituisce l'agente se esiste oppure genera un errore se il nome è errato o l'agente non è stato distribuito.

Installare l'SDK Foundry:

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

Impostare due variabili di ambiente e quindi creare il client del progetto. Impostare FOUNDRY_PROJECT_ENDPOINT sull'endpoint del progetto e FOUNDRY_MODEL_NAME su una distribuzione per il completamento della chat da usare come modello di valutazione. Gli esempi di codice seguenti presuppongono che vengano eseguiti in questo contesto:

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

Verificare che l'agente distribuito sia registrato e disponibile. Sostituire <your-agent-name> con il nome dell'agente ospitato:

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

La chiamata restituisce l'agente se esiste oppure genera un errore se il nome è errato o l'agente non è stato distribuito.

Riferimento: classe AIProjectClient

Creare prima di tutto un file JSONL di query di test per l'agente. Ogni riga è un oggetto JSON con un query campo. Salvarlo all'interno della cartella di origine dell'agente, come src/<your-agent-name>/tests/queries.jsonl:

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

Creare quindi un eval.yaml file nella stessa cartella di origine dell'agente, come src/<your-agent-name>/eval.yaml. Punta al set di dati ed elenca gli analizzatori predefiniti da applicare. Il percorso dataset.local_uri è relativo a questa cartella. Sostituire <your-agent-name> con il nome dell'agente ospitato e <your-chat-completion-deployment> con la distribuzione del modello di valutazione:

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

Il valore eval_model è il modello di valutazione che assegna i punti alle risposte. È possibile riutilizzare la distribuzione che l'agente usa già.

1. Nel portale Foundry, apri il tuo agente e seleziona la scheda Valutazione, quindi seleziona Crea.
2. Per Seleziona obiettivo della valutazione, seleziona Agente.
3. Per Seleziona l'ambito di valutazione, seleziona Turni individuali.
4. In Seleziona origine dati, selezionare Set di dati esistente e scegliere un file CSV o JSONL di query di test nelle risorse dati del progetto.
5. Se viene visualizzato il passaggio Configura agenti , esaminare l'agente e accettare il prompt dell'utente predefinito, {{item.query}}. Regolarlo solo se l'agente prevede un formato di input diverso.
6. In Seleziona i criteri di test, seleziona uno o più valutatori dell'agente, ad esempio Aderenza all'attività e Risoluzione dell'intento.

Mantenere aperta la procedura guidata. Si invia la valutazione nel passaggio successivo.

Creare prima di tutto un file JSONL di query di test per l'agente. Ogni riga è un oggetto JSON con un query campo. Salvalo con il nome queries.jsonl:

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

Caricare il file come set di dati nel progetto:

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

Scegliere quindi analizzatori predefiniti ed eseguire il mapping degli input. Il data_mapping parametro indica a ogni analizzatore dove trovare la query e la risposta dell'agente. I valutatori assistiti dall'IA richiedono un modello giudice in initialization_parameters; il valore deve essere una distribuzione per il completamento della chat nel progetto.

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

Creare la valutazione. Definisce lo schema dei dati di test e i criteri di test e funge da contenitore per una o più esecuzioni:

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

Creare prima di tutto un file JSONL di query di test per l'agente. Ogni riga è un oggetto JSON con un query campo. Salvalo con il nome queries.jsonl:

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

Caricare il file come set di dati nel progetto:

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

Scegliere quindi analizzatori predefiniti ed eseguire il mapping degli input. Il data_mapping parametro indica a ogni analizzatore dove trovare la query e la risposta dell'agente. I valutatori assistiti dall'IA richiedono un modello giudice in initialization_parameters; il valore deve essere una distribuzione per il completamento della chat nel progetto.

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

Creare la valutazione. Definisce lo schema dei dati di test e i criteri di test e funge da contenitore per una o più esecuzioni:

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

Eseguire la valutazione dalla radice dell'area di lavoro azd:

azd ai agent eval run --config eval.yaml

Il comando legge eval.yaml, invia ogni query all'agente, assegna un punteggio alle risposte e stampa un riepilogo al 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. Nel passaggio Rivedi e invia immettere un nome per la valutazione.
2. Esaminare la destinazione, l'ambito, l'origine dati e gli analizzatori selezionati.
3. Selezionare Invia per avviare l'esecuzione.

Creare un'esecuzione che invii ogni query di test all'agente e applichi i valutatori. Sostituire <your-agent-name> con il nome dell'agente ospitato:

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

Creare un'esecuzione che invii ogni query di test all'agente e applichi i valutatori. Sostituire <your-agent-name> con il nome dell'agente ospitato:

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

Elencare le valutazioni recenti:

azd ai agent eval list

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

* = active eval in current environment

Mostrare la valutazione più recente e le relative esecuzioni:

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

Usa i risultati per verificare quale versione dell'agente è stata valutata e quali punteggi del valutatore sono stati prodotti. Per visualizzare i dettagli di ciascun valutatore e un collegamento al report nel portale Foundry, esegui azd ai agent eval show <eval-id> --eval-run-id <run-id>.

1. La pagina dei dettagli mostra la destinazione, il set di dati, lo stato, l'utilizzo dei token e un punteggio di aggregazione per ogni analizzatore.
2. Seleziona il nome dell'esecuzione per visualizzare i risultati a livello di singola riga: ogni query, la risposta dell'agente, il punteggio del valutatore e la spiegazione del punteggio.

Eseguire il polling per il completamento, quindi stampare lo stato e l'URL del report che apre i risultati nel portale 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}")

A livello di run, puoi visualizzare i conteggi aggregati degli esiti positivi e negativi per ciascun valutatore:

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

Per i dettagli a livello di riga, elencare gli elementi di output. Ogni risultato include il nome dell'analizzatore, il passaggio o l'esito negativo e un punteggio:

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)

Esegui il polling fino al completamento, quindi stampa lo stato e l'URL del report che apre i risultati nel portale 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}`);

A livello di run, puoi visualizzare i conteggi aggregati degli esiti positivi e negativi per ciascun valutatore:

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

Per i dettagli a livello di riga, elencare gli elementi di output. Ogni risultato include il nome dell'analizzatore, il passaggio o l'esito negativo e un punteggio:

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