Lokale Bewertung Ihrer KI-Agenten (Vorschau)

In diesem Prozess ist die Bewertung der einzelnen Schritte des Workflows sowie die Qualität und Sicherheit der endgültigen Ausgabe von entscheidender Bedeutung. Wir formulieren diese Bewertungsaspekte in die folgenden Bewerter für Agenten:

• Absichtsauflösung: Misst, ob der Agent die Absicht der benutzenden Person korrekt identifiziert.
• Toolaufrufgenauigkeit: Misst, ob der Agent das richtige Funktionstool aufruft, um die Anforderung einer benutzenden Person aufzurufen.
• Einhaltung der Aufgabe: Misst, ob die endgültige Antwort des Agenten den zugewiesenen Aufgaben gemäß seiner Systemnachricht und den vorherigen Schritten entspricht.

Bewerten Sie andere Qualitäts- und Sicherheitsaspekte Ihrer agentischen Workflows mithilfe unserer umfassenden Suite integrierter Bewerter. Im Allgemeinen emittieren Agenten Agentnachrichten. Das Transformieren von Agentnachrichten in die richtigen Auswertungsdaten für unsere Bewerter kann eine Herausforderung darstellen. Wenn Sie Ihren Agent mit dem Foundry Agent Service erstellen, können Sie ihn nahtlos über unseren Konvertersupport auswerten. Wenn Sie Ihren Agent außerhalb des Foundry Agent Service erstellen, können Sie unsere Auswertungen weiterhin entsprechend Ihrem agentischen Workflow verwenden, indem Sie Ihre Agentnachrichten in die erforderlichen Datenformate analysieren. Beispiele finden Sie unter Auswerten anderer Agents.

Als bewährte Methode ist es von entscheidender Bedeutung, folgendes auszuführen:

• Systembewertung: Bewertung der Gesamtqualität und Effizienz des Arbeitsablaufs des Agenten; und
• Prozessauswertung: Auswerten von Toolaufrufschritten des Workflows.

Detaillierte Informationen zum Anwendungsfall der beiden Methoden und eine Stichprobe der einzelnen Agent-Auswertungen finden Sie unter Agent-Evaluatoren .

Sie können auch andere Qualitäts- und Sicherheitsaspekte Ihrer agentischen Workflows bewerten, indem Sie unsere umfassende Suite integrierter Bewerter verwenden oder benutzerdefinierte Bewerter schreiben.

Wenn Sie Foundry Agents erstellen, können Sie sie nahtlos auswerten.

Wenn Sie Ihre Agenten außerhalb von Foundry erstellen, können Sie unsere Auswertungen weiterhin entsprechend Ihrem agentischen Workflow verwenden, indem Sie Ihre Agentnachrichten in die erforderlichen Datenformate analysieren. Weitere Informationen finden Sie unter Bewerten anderer Agents.

Installieren Sie das Evaluators-Paket aus dem Azure AI Evaluation SDK:

pip install azure-ai-evaluation

Installieren Sie das Paket aus dem Azure AI Evaluation SDK:

pip install "azure-ai-projects>=2.0.0b1" azure-identity python-dotenv

Legen Sie diese Umgebungsvariablen mit Ihren Werten in einer .env Datei fest:

AZURE_AI_PROJECT_ENDPOINT="<your-endpoint>" # The Azure AI Project project endpoint, as found in the Home page of your Microsoft Foundry portal.
AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment-name>" # The deployment name of the AI model, as found under the "Build" page in the "Models" tab in your Foundry project.

Wenn Sie den Foundry Agent Service verwenden, können Sie Ihre Agents nahtlos auswerten, indem Sie unseren Konvertersupport für Microsoft Foundry-Agents und semantische Kernel-Agents verwenden. Die folgenden Auswerter unterstützen die Bewertung der vom Konverter zurückgegebenen Daten: IntentResolution, ToolCallAccuracy, TaskAdherence, Relevance und Groundedness.

Modellunterstützung für KI-unterstützte Bewerter

Begründungsmodelle und Nicht-Begründungsmodelle von AzureOpenAI und OpenAI unterstützen den LLM-Judge, abhängig von den Auswertern.

Verwenden Sie für eine komplexe Auswertung, die verfeinertes Denken erfordert, ein starkes Modell für logisches Denken wie 4.1-mini für ein ausgewogenes Verhältnis zwischen Leistungsfähigkeit und Kosteneffizienz.

Unterstützung der Toolanrufeauswertung

ToolCallAccuracyEvaluator unterstützt die Auswertung in Microsoft Foundry Agent für die folgenden Tools:

• Dateisuche
• Azure KI-Suche
• Bing-Verankerung
• Benutzerdefinierte Bing-Suche
• SharePoint-Grundierung
• Codedolmetscher
• Fabric-Datenagent
• OpenAPI
• Funktionstool (benutzerdefinierte Tools)

Wenn Sie jedoch ein nicht unterstütztes Tool in der Agentenausführung verwenden, gibt der Evaluator eine "Genehmigung" aus und nennt einen Grund, warum die Auswertung der aufgerufenen Tools nicht unterstützt wird, um das Herausfiltern dieser Fälle zu erleichtern. Um die Auswertung zu aktivieren, schließen Sie nicht unterstützte Tools als benutzerdefinierte Tools ein.

In diesem Beispiel wird gezeigt, wie Sie einen Microsoft Foundry-Agent erstellen und auswerten. Getrennt von der Auswertung erfordert Foundry Agent Service pip install azure-ai-projects azure-identity, eine Foundry-Projektverbindungszeichenfolge und die unterstützten Modelle.

Erstellen von Agent-Threads und -Ausführungen

Agents können Tools verwenden. Hier sehen Sie ein Beispiel für das Erstellen von benutzerdefinierten Tools, die der Agent verwenden kann, mithilfe einer simulierten Wetterfunktion als Beispiel.

from azure.ai.projects.models import FunctionTool, ToolSet
from typing import Set, Callable, Any
import json

# Define a custom Python function.
def fetch_weather(location: str) -> str:
    """
    Fetches the weather information for the specified location.

    :param location (str): The location to fetch weather for.
    :return: Weather information as a JSON string.
    :rtype: str
    """
    # In a real-world scenario, you'd integrate with a weather API.
    # In the following code snippet, we mock the response.
    mock_weather_data = {"Seattle": "Sunny, 25°C", "London": "Cloudy, 18°C", "Tokyo": "Rainy, 22°C"}
    weather = mock_weather_data.get(location, "Weather data not available for this location.")
    weather_json = json.dumps({"weather": weather})
    return weather_json

user_functions: Set[Callable[..., Any]] = {
    fetch_weather,
}

# Add tools that the agent will use. 
functions = FunctionTool(user_functions)

toolset = ToolSet()
toolset.add(functions)

AGENT_NAME = "Seattle Tourist Assistant"

Wenn Sie ein Foundry-Projekt (non-Hub) verwenden, erstellen Sie einen Agent mit dem Toolset wie folgt:

Erstellen Sie einen Agent mit dem Toolset wie folgt:

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

# Create an Azure AI Client from an endpoint, copied from your Foundry project.
# You need to login to Azure subscription via Azure CLI and set the environment variables
# Foundry project endpoint, example: AZURE_AI_PROJECT=https://your-account.services.ai.azure.com/api/projects/your-project
project_endpoint = os.environ["AZURE_AI_PROJECT"]  # Ensure the PROJECT_ENDPOINT environment variable is set

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=project_endpoint,
    credential=DefaultAzureCredential(),  # Use Azure Default Credential for authentication
)


# Create an agent with the toolset 
agent = project_client.agents.create_agent(
    model=os.environ["MODEL_DEPLOYMENT_NAME"],  # Model deployment name
    name="my-agent",  # Name of the agent
    instructions="You are a helpful agent",  # Instructions for the agent
    toolset=toolset
)
print(f"Created agent, ID: {agent.id}")

# Create a thread for communication
thread = project_client.agents.threads.create()
print(f"Created thread, ID: {thread.id}")

# Add a message to the thread
message = project_client.agents.messages.create(
    thread_id=thread.id,
    role="user",  # Role of the message sender
    content="What is the weather in Seattle today?",  # Message content
)
print(f"Created message, ID: {message['id']}")

# Create and process an agent run
run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
print(f"Run finished with status: {run.status}")

# Check if the run failed
if run.status == "failed":
    print(f"Run failed: {run.last_error}")

# Fetch and log all messages
messages = project_client.agents.messages.list(thread_id=thread.id)
for message in messages:
    print(f"Role: {message.role}, Content: {message.content}")

Auswerten einer einzelnen Agent-Ausführung

Nachdem Sie Agent-Durchläufe erstellt haben, können Sie unseren Konverter verwenden, um die Threaddaten des Microsoft Foundry-Agenten in die erforderlichen Auswertungsdaten zu transformieren, die von den Evaluatoren verstanden werden können.

import json, os
from azure.ai.evaluation import AIAgentConverter, IntentResolutionEvaluator

# Initialize the converter for Microsoft Foundry agents.
converter = AIAgentConverter(project_client)

# Specify the thread and run ID.
thread_id = thread.id
run_id = run.id

converted_data = converter.convert(thread_id, run_id)

Das ist alles! converted_data enthält alle Eingaben, die für diese Bewerter erforderlich sind. Sie müssen die Eingabeanforderungen für jeden Evaluator nicht lesen oder die Eingaben analysieren. Wählen Sie Ihren Auswerter aus, und rufen Sie den Auswerter in dieser einzelnen Ausführung auf. Wir unterstützen Azure OpenAI- oder OpenAI-Begründungsmodelle und Nicht-Begründungsmodelle für die Beurteilung, abhängig von den Evaluatoren.

Bei komplexen Aufgaben, die eine verfeinerte Begründung für die Auswertung erfordern, empfehlen wir ein starkes Begründungsmodell wie o3-mini oder die anschließend veröffentlichten o-Serie-Minimodelle mit einem ausgewogenen Verhältnis von Leistungsfähigkeit und Kosteneffizienz.

Wir richten eine Liste der Qualitäts- und Sicherheitsbewertung in quality_evaluators und safety_evaluators ein und verweisen darauf in Auswertung mehrerer Agent-Ausführungen oder eines Threads.

# This is specific to agentic workflows.
from azure.ai.evaluation import IntentResolutionEvaluator, TaskAdherenceEvaluator, ToolCallAccuracyEvaluator 
# Other quality, risk, and safety metrics:
from azure.ai.evaluation import RelevanceEvaluator, CoherenceEvaluator, CodeVulnerabilityEvaluator, ContentSafetyEvaluator, IndirectAttackEvaluator, FluencyEvaluator
from azure.identity import DefaultAzureCredential

import os
from dotenv import load_dotenv
load_dotenv()

model_config = {
    "azure_deployment": os.getenv("AZURE_DEPLOYMENT_NAME"),
    "api_key": os.getenv("AZURE_API_KEY"),
    "azure_endpoint": os.getenv("AZURE_ENDPOINT"),
    "api_version": os.getenv("AZURE_API_VERSION"),
}

# example config for a reasoning model
reasoning_model_config = {
    "azure_deployment": "o3-mini",
    "api_key": os.getenv("AZURE_API_KEY"),
    "azure_endpoint": os.getenv("AZURE_ENDPOINT"),
    "api_version": os.getenv("AZURE_API_VERSION"),
}

# Evaluators you might want to use with reasoning models 
quality_evaluators = {evaluator.__name__: evaluator(model_config=reasoning_model_config, is_reasoning_model=True) for evaluator in [IntentResolutionEvaluator, TaskAdherenceEvaluator, ToolCallAccuracyEvaluator]}

# Other evaluators you might NOT want to use with reasoning models 
quality_evaluators.update({ evaluator.__name__: evaluator(model_config=model_config) for evaluator in [CoherenceEvaluator, FluencyEvaluator, RelevanceEvaluator]})

## Using Foundry (non-Hub) project endpoint, example: AZURE_AI_PROJECT=https://your-account.services.ai.azure.com/api/projects/your-project
azure_ai_project = os.environ.get("AZURE_AI_PROJECT")

safety_evaluators = {evaluator.__name__: evaluator(azure_ai_project=azure_ai_project, credential=DefaultAzureCredential()) for evaluator in [ContentSafetyEvaluator, IndirectAttackEvaluator, CodeVulnerabilityEvaluator]}

# Reference the quality and safety evaluator list above.
quality_and_safety_evaluators = {**quality_evaluators, **safety_evaluators}

for name, evaluator in quality_and_safety_evaluators.items():
    result = evaluator(**converted_data)
    print(name)
    print(json.dumps(result, indent=4)) 

Ausgabeformat

KI-unterstützte Qualitätsbewertungen geben ein Ergebnis für ein Abfrage- und Antwortpaar zurück. Das Ergebnis ist ein Wörterbuch, das Folgendes umfasst:

• {metric_name}: Stellt eine numerische Bewertung auf einer Likert-Skala (ganze Zahl 1 bis 5) oder einen Gleitkommawert zwischen 0 und 1 bereit.
• {metric_name}_label: Stellt eine binäre Beschriftung bereit (wenn die Metrik natürlich eine Binärbewertung ausgibt).
• {metric_name}_reason: Erläutert, warum für jeden Datenpunkt eine bestimmte Bewertung oder Beschriftung angegeben wurde.
• details: Optionale Ausgabe mit Debuginformationen über die Qualität eines einzelnen Agentendurchlaufs.

Um die Klarheit zu verbessern, akzeptieren alle Bewerter einen binären Schwellenwert (es sei denn, ihre Ausgaben sind bereits binär) und generieren zwei neue Schlüssel. Für den Binarisierungsschwellenwert wird eine Standardeinstellung festgelegt, die der Benutzer außer Kraft setzen kann. Die beiden neuen Schlüssel sind:

• {metric_name}_result: Eine "pass"- oder "fail"-Zeichenfolge basierend auf einem Binarisierungsschwellenwert.
• {metric_name}_threshold: Ein numerischer Binarisierungsschwellenwert, der standardmäßig oder vom Benutzer festgelegt wird.

Sehen Sie sich die folgende Beispielausgabe für einige Evaluatoren an.

{
    "intent_resolution": 5.0, # likert scale: 1-5 integer 
    "intent_resolution_threshold": 3,
    "intent_resolution_result": "pass", # pass because 5 > 3 the threshold
    "intent_resolution_reason": "The assistant correctly understood the user's request to fetch the weather in Seattle. It used the appropriate tool to get the weather information and provided a clear and accurate response with the current weather conditions in Seattle. The response fully resolves the user's query with all necessary information."
}
{
    "task_adherence": 5.0, # likert scale: 1-5 integer 
    "task_adherence_threshold": 3,
    "task_adherence_result": "pass", # pass because 5 > 3 the threshold
    "task_adherence_reason": "The response accurately follows the instructions, fetches the correct weather information, and relays it back to the user without any errors or omissions."
}
{
    "tool_call_accuracy": 5,  # a score between 1-5, higher is better
    "tool_call_accuracy_threshold": 3,
    "tool_call_accuracy_result": "pass", # pass because 5 > 3 the threshold
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

Auswerten mehrerer Agent-Ausführungen oder -Threads

Verwenden Sie die Batch-API evaluate() für die asynchrone Auswertung, um mehrere Agentausführungen oder Threads auszuwerten. Konvertieren Sie zunächst Ihre Agentthreaddaten mithilfe unserer Konverterunterstützung in eine Datei:

import json
from azure.ai.evaluation import AIAgentConverter

# Initialize the converter.
converter = AIAgentConverter(project_client)

# Specify a file path to save the agent output (evaluation input data) to.
filename = os.path.join(os.getcwd(), "evaluation_input_data.jsonl")

evaluation_data = converter.prepare_evaluation_data(thread_ids=thread_id, filename=filename) 

print(f"Evaluation data saved to {filename}")

Mit den in einer Codezeile vorbereiteten Auswertungsdaten können Sie die Evaluatoren auswählen, um die Qualität der Agenten zu bewerten und einen Batch-Bewertungslauf zu starten. Im folgenden Beispiel verweisen wir auf die gleiche Liste der Qualitäts- und Sicherheitsauswerter im Abschnitt Auswerten einer einzelnen Agentausführungquality_and_safety_evaluators:

import os
from dotenv import load_dotenv
load_dotenv()


# Batch evaluation API (local):
from azure.ai.evaluation import evaluate

response = evaluate(
    data=filename,
    evaluation_name="agent demo - batch run",
    evaluators=quality_and_safety_evaluators,
    # optionally, log your results to your Foundry project for rich visualization 
    azure_ai_project=os.environ.get("AZURE_AI_PROJECT"),  # example: https://your-account.services.ai.azure.com/api/projects/your-project
)
# Inspect the average scores at a high level.
print(response["metrics"])
# Use the URL to inspect the results on the UI.
print(f'Foundry URL: {response.get("studio_url")}')

Nachdem Sie die URL ausgewählt haben, werden Sie zu Foundry umgeleitet. Zeigen Sie die Auswertungsergebnisse in Ihrem Foundry-Projekt an, und debuggen Sie Ihre Anwendung. Verwenden Sie Grundfelder und Pass-/Fail-Ergebnisse, um die Qualität und Sicherheitsleistung Ihrer Anwendungen zu bewerten. Sie können mehrere Läufe ausführen und vergleichen, um Regressionen oder Verbesserungen zu testen.

Verwenden Sie die Azure AI Evaluation SDK-Clientbibliothek, um Ihre Microsoft Foundry-Agenten mit Konverterunterstützung auszuwerten, wodurch die Beobachtbarkeit und Transparenz von Agent-Workflows ermöglicht werden.

Sie können Gießerei-Agenten nahtlos bewerten, indem Sie Evaluatoren in Agenten-Evaluatoren und RAG-Evaluatoren verwenden. Dieser Abschnitt führt Sie durch das Erstellen eines Agents und die Auswertung.

Voraussetzungen

import json
from azure.ai.projects.models import Tool, FunctionTool

# Define a function tool for the model to use
func_tool = fetch_weather(
    name="fetch_weather",
    parameters={
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to fetch weather for.",
            },
        },
        "required": ["location"],
        "additionalProperties": False,
    },
    description="Get the current weather for a location.",
    strict=True,
)

tools: list[Tool] = [func_tool]

# Define a custom Python function.
async def fetch_weather(location: str) -> str:
    """
    Fetches the weather information for the specified location.

    :param location (str): The location to fetch weather for.
    :return: Weather information as a JSON string.
    :rtype: str
    """
    # In a real-world scenario, you'd integrate with a weather API.
    # In the following code snippet, we mock the response.
    mock_weather_data = {"Seattle": "Sunny, 25°C", "London": "Cloudy, 18°C", "Tokyo": "Rainy, 22°C"}
    weather = mock_weather_data.get(location, "Weather data not available for this location.")
    weather_json = json.dumps({"weather": weather})
    return weather_json

Richten Sie einen Agent mit dem Toolset ein, und erstellen Sie eine Antwortausführung zur Auswertung.

Erstellen Sie einen Agent mit dem Toolset wie folgt:

import os
import json
from dotenv import load_dotenv
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential
from openai.types.responses.response_input_param import FunctionCallOutput, ResponseInputParam

credential = DefaultAzureCredential()


project_client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

with project_client:

    openai_client = project_client.get_openai_client()

    agent = await project_client.agents.create_version(
        agent_name="MyAgent",
        definition=PromptAgentDefinition(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
            instructions="You are a helpful assistant that can use function tools.",
            tools=tools,
        ),
    )

    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    conversation = openai_client.conversations.create(
        items=[{"type": "message", "role": "user", "content": "What is the weather in Seattle?"}],
    )
    print(f"Created conversation with initial user message (id: {conversation.id})")

    response = openai_client.responses.create(
        conversation=conversation.id,
        extra_body={"agent": {"name": agent.name, "type": "agent_reference"}},
    )
    print(f"Response output: {response.output_text} (id: {response.id})")


    # Now create evaluation for the response
    data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

    # add your desired evaluators here
    testing_criteria = [
        {"type": "azure_ai_evaluator", "name": "task_adherence", "evaluator_name": "builtin.task_adherence"},
        {"type": "azure_ai_evaluator", "name": "groundedness", "evaluator_name": "builtin.groundedness"},
    ]
    eval_object = openai_client.evals.create(
        name="Agent Response Evaluation",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )
    print(f"Evaluation created (id: {eval_object.id}, name: {eval_object.name})")

    data_source = {
        "type": "azure_ai_responses",
        "item_generation_params": {
            "type": "response_retrieval",
            "data_mapping": {"response_id": "{{item.resp_id}}"},
            "source": {"type": "file_content", "content": [{"item": {"resp_id": response.id}}]},
        },
    }

    response_eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id, name=f"Evaluation Run for Agent {agent.name}", data_source=data_source
    )
    print(f"Evaluation run created (id: {response_eval_run.id})")

    while response_eval_run.status not in ["completed", "failed"]:
        response_eval_run = openai_client.evals.runs.retrieve(run_id=response_eval_run.id, eval_id=eval_object.id)
        print(f"Waiting for eval run to complete... current status: {response_eval_run.status}")
        time.sleep(5)

    if response_eval_run.status == "completed":
        print("\n✓ Evaluation run completed successfully!")
        print(f"Result Counts: {response_eval_run.result_counts}")
        print(f"Eval Run Report URL: {response_eval_run.report_url}")
        output_items = list(
            openai_client.evals.runs.output_items.list(run_id=response_eval_run.id, eval_id=eval_object.id)
        )
        print(f"\nOUTPUT ITEMS (Total: {len(output_items)})")
        print(f"{'-'*60}")
        pprint(output_items)
        print(f"{'-'*60}")
    else:
        print("\n✗ Evaluation run failed.")

Interpretation der Ergebnisse

Für ein einzelnes Datenbeispiel geben alle Auswertungen immer das folgende Schema aus:

• Beschriftung: eine binäre "Pass"- oder "fail"-Bezeichnung, ähnlich der Ausgabe eines Komponententests. Verwenden Sie dieses Ergebnis, um Vergleiche über Evaluatoren hinweg zu vereinfachen.
• Bewertung: eine Bewertung aus der natürlichen Skala des einzelnen Evaluators. Einige Bewerter verwenden eine feinkörnige Rubrik, eine Bewertung auf einer 5-Punkt-Skala (Qualitätsbewertungen) oder eine 7-Punkt-Skala (Inhaltssicherheits-Evaluatoren). Andere, wie textbezogene Ähnlichkeitsbewertungen, verwenden F1-Bewertungen, die zwischen 0 und 1 schweben. Das Feld „Beschriftung“ binarisiert alle nicht-binären „Bewertungen“ in „bestanden“ oder „nicht bestanden“, basierend auf „Schwellenwert“.
• Schwellenwert: Alle nicht binären Bewertungen werden basierend auf einem Standardschwellenwert, den Sie in der SDK-Erfahrung überschreiben können, binär in „bestanden“ oder „nicht bestanden“ binarisiert.
• Grund: Um die Verständlichkeit zu verbessern, geben alle LLM-Richter-Evaluatoren auch ein Begründungsfeld aus, um zu erläutern, warum eine bestimmte Bewertung angegeben wird.
• Details: (optional) Bei einigen Bewertern, z. B. tool_call_accuracy, gibt es möglicherweise ein "Details"-Feld oder Flags, das zusätzliche Informationen enthält, um Benutzern beim Debuggen ihrer Anwendungen zu helfen. Bei über mehrere Datenbeispiele (ein Dataset) aggregierten Ergebnissen bildet die durchschnittliche Rate der Beispiele mit der Bewertung „bestanden“ die Erfolgsquote für dieses Dataset.

Nach der URL werden Sie zu Foundry umgeleitet. Sie können Die Auswertungsergebnisse in Ihrem Foundry-Projekt anzeigen und Ihre Anwendung debuggen. Verwenden Sie Begründungsfelder und die Angabe „Bestanden“/„Nicht Bestanden“, um die Leistung im Hinblick auf Qualität und Sicherheit Ihrer Anwendungen zu bewerten. Sie können mehrere Läufe ausführen und vergleichen, um Regressionen oder Verbesserungen zu testen.

Verwenden Sie die Microsoft Foundry SDK Python-Clientbibliothek, um Ihre Microsoft Foundry-Agents auszuwerten und die Observability und Transparenz in Agentworkflows zu ermöglichen.

Wenn Sie Agents außerhalb des Agentendiensts verwenden, können Sie diese weiterhin auswerten, indem Sie die richtigen Daten für die Auswertungen Ihrer Wahl vorbereiten.

Agents geben in der Regel Nachrichten aus, um mit einem Benutzer oder anderen Agents zu interagieren. Integrierte Bewerter akzeptieren einfache Datentypen wie Zeichenfolgen in query, response und ground_truth gemäß den Anforderungen an die einfache Dateneingabe. Das Extrahieren dieser einfachen Datentypen aus Agentnachrichten kann jedoch aufgrund der komplexen Interaktionsmuster von Agents und Framework-Unterschieden schwierig sein. Beispielsweise kann eine einzelne Benutzerabfrage eine lange Liste von Agentnachrichten auslösen, in der Regel mit mehreren aufgerufenen Toolaufrufen.

Agents geben in der Regel Nachrichten aus, um mit einem Benutzer oder anderen Agents zu interagieren. Unsere integrierten Bewerter können einfache Datentypen wie z. B. Zeichenfolgen in query, responseund ground_truth entsprechend den Anforderungen für die Eingabe von Einzeldaten akzeptieren. Es kann jedoch eine Herausforderung sein, diese einfachen Datentypen aus Agentnachrichten zu extrahieren, aufgrund der komplexen Interaktionsmuster von Agents und Framework-Unterschieden. Beispielsweise kann eine einzelne Benutzerabfrage eine lange Liste von Agentnachrichten auslösen, in der Regel mit mehreren aufgerufenen Toolaufrufen.

Wie im folgenden Beispiel dargestellt, aktivieren wir die Unterstützung von Agentnachrichten für die folgenden integrierten Evaluatoren, um diese Aspekte des agentischen Workflows auszuwerten. Diese Evaluatoren könnten tool_calls oder tool_definitions als spezifische Parameter für Agenten annehmen, wenn sie Agenten bewerten.

• Message: dict OpenAI-Formatnachricht, die Agentinteraktionen mit einem Benutzer beschreibt, wobei die query Systemnachricht als erste Nachricht enthalten muss.
• ToolCall: dict gibt Toolaufrufe an, die während agent-Interaktionen mit einem Benutzer aufgerufen werden.
• ToolDefinition: dict beschreibt die tools, die für einen Agent verfügbar sind.

Für ToolCallAccuracyEvaluator müssen Sie entweder response oder tool_calls bereitstellen.

GroundednessEvaluator erfordert tool_definitions, um die Fundiertheit der Antworten des Agents mit Bezug auf die vom Agent empfangenen Toolausgaben zu bewerten.

Die folgenden Beispiele zeigen die beiden Datenformate: einfache Agentdaten und Agentnachrichten. Aufgrund der eindeutigen Anforderungen dieser Bewerter empfehlen wir jedoch, auf die Beispielnotizbücher zu verweisen, die die möglichen Eingabepfade für jeden Evaluator veranschaulichen.

Wie andere integrierte KI-unterstützte QualitätsbewertungenIntentResolutionEvaluator und TaskAdherenceEvaluator eine Likert-Bewertung ausgeben (ganze Zahl 1 bis 5; höhere Bewertungen sind besser). ToolCallAccuracyEvaluator gibt die Erfolgsquote aller ausgeführten Toolaufrufe (eine Gleitkommazahl zwischen 0 und 1) auf Grundlage der Benutzeranfrage aus. Um die Verständlichkeit weiter zu verbessern, akzeptieren alle Bewerter einen binären Schwellenwert und geben zwei neue Schlüssel aus. Für den Binarisierungsschwellenwert wird ein Standardwert festgelegt, und Sie können ihn überschreiben. Die beiden neuen Schlüssel sind:

• {metric_name}_result: Eine "pass"- oder "fail"-Zeichenfolge basierend auf einem Binarisierungsschwellenwert.
• {metric_name}_threshold: Ein numerischer Binarisierungsschwellenwert, der standardmäßig oder vom Benutzer festgelegt wird.

Einfache Agentdaten

Im einfachen Agent-Datenformat query und response handelt es sich um einfache Python-Zeichenfolgen. Beispiel:

import os
import json
from azure.ai.evaluation import AzureOpenAIModelConfiguration
from azure.identity import DefaultAzureCredential
from azure.ai.evaluation import IntentResolutionEvaluator, ResponseCompletenessEvaluator

model_config = AzureOpenAIModelConfiguration(
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
    azure_deployment=os.environ["MODEL_DEPLOYMENT_NAME"],
)

intent_resolution_evaluator = IntentResolutionEvaluator(model_config)

# Evaluate the query and response as strings.
# The following is a positive example. Intent is identified and understood and the response correctly resolves user intent.
result = intent_resolution_evaluator(
    query="What are the opening hours of the Eiffel Tower?",
    response="Opening hours of the Eiffel Tower are 9:00 AM to 11:00 PM.",
)
print(json.dumps(result, indent=4))

Siehe die folgende Ausgabe (Details finden Sie im Ausgabeformat):

{
    "intent_resolution": 5.0,
    "intent_resolution_result": "pass",
    "intent_resolution_threshold": 3,
    "intent_resolution_reason": "The response provides the opening hours of the Eiffel Tower, which directly addresses the user's query. The information is clear, accurate, and complete, fully resolving the user's intent.",
}

Sehen Sie sich die folgenden Beispiele zu tool_calls und tool_definitions für ToolCallAccuracyEvaluator an

import json 

query = "How is the weather in Seattle?"
tool_calls = [{
                    "type": "tool_call",
                    "tool_call_id": "call_CUdbkBfvVBla2YP3p24uhElJ",
                    "name": "fetch_weather",
                    "arguments": {
                        "location": "Seattle"
                    }
            },
            {
                    "type": "tool_call",
                    "tool_call_id": "call_CUdbkBfvVBla2YP3p24uhElJ",
                    "name": "fetch_weather",
                    "arguments": {
                        "location": "London"
                    }
            }]

tool_definitions = [{
                    "name": "fetch_weather",
                    "description": "Fetches the weather information for the specified location.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "The location to fetch weather for."
                            }
                        }
                    }
                }]

from azure.ai.evaluation import ToolCallAccuracyEvaluator

tool_call_accuracy = ToolCallAccuracyEvaluator(model_config) # reuse the config defined above
response = tool_call_accuracy(query=query, tool_calls=tool_calls, tool_definitions=tool_definitions)
print(json.dumps(response, indent=4))

Sehen Sie sich die folgende Ausgabe an (Einzelheiten finden Sie unter Ausgabeformat):

{
    "tool_call_accuracy": 3,  # a score between 1-5, higher is better
    "tool_call_accuracy_result": "fail",
    "tool_call_accuracy_threshold": 4,
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

Sehen Sie sich die folgenden Beispiele zu tool_calls und tool_definitions für tool_call_accuracy an

import json 

query = "How is the weather in Seattle?"
tool_calls = [{
                    "type": "tool_call",
                    "tool_call_id": "call_CUdbkBfvVBla2YP3p24uhElJ",
                    "name": "fetch_weather",
                    "arguments": {
                        "location": "Seattle"
                    }
            },
            {
                    "type": "tool_call",
                    "tool_call_id": "call_CUdbkBfvVBla2YP3p24uhElJ",
                    "name": "fetch_weather",
                    "arguments": {
                        "location": "London"
                    }
            }]

tool_definitions = [{
                    "name": "fetch_weather",
                    "description": "Fetches the weather information for the specified location.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "The location to fetch weather for."
                            }
                        }
                    }
                }]

query = [
    {
        "role": "system",
        "content": "You are an AI assistant interacting with Azure Maps services to serve user requests."
    },
    {
        "createdAt": "2025-04-25T23:55:43Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Find the address for coordinates 41.8781,-87.6298."
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:45Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "call_nqNyhOFRw4FmF50jaCCq2rDa",
                "name": "azure_maps_reverse_address_search",
                "arguments": {
                    "lat": "41.8781",
                    "lon": "-87.6298"
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:47Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "tool_call_id": "call_nqNyhOFRw4FmF50jaCCq2rDa",
        "role": "tool",
        "content": [
            {
                "type": "tool_result",
                "tool_result": {
                    "address": "300 South Federal Street, Chicago, IL 60604",
                    "position": {
                        "lat": "41.8781",
                        "lon": "-87.6298"
                    }
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:48Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The address for the coordinates 41.8781, -87.6298 is 300 South Federal Street, Chicago, IL 60604."
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:50Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What timezone corresponds to 41.8781,-87.6298?"
            }
        ]
    },
]

response = [
    {
        "createdAt": "2025-04-25T23:55:52Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "call_qi2ug31JqzDuLy7zF5uiMbGU",
                "name": "azure_maps_timezone",
                "arguments": {
                    "lat": 41.878100000000003,
                    "lon": -87.629800000000003
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:54Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "tool_call_id": "call_qi2ug31JqzDuLy7zF5uiMbGU",
        "role": "tool",
        "content": [
            {
                "type": "tool_result",
                "tool_result": {
                    "ianaId": "America/Chicago",
                    "utcOffset": None,
                    "abbreviation": None,
                    "isDaylightSavingTime": None
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:55Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The timezone for the coordinates 41.8781, -87.6298 is America/Chicago."
            }
        ]
    }
]

Sehen Sie sich ein Beispiel für die Auswertung der Agentnachrichten mit ToolCallAccuracyEvaluator:

import json

# The user asked a question.
query = [
    {
        "role": "system",
        "content": "You are a friendly and helpful customer service agent."
    },
    # Past interactions are omitted. 
    # ...
    {
        "createdAt": "2025-03-14T06:14:20Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Hi, I need help with the last 2 orders on my account #888. Could you please update me on their status?"
            }
        ]
    }
]
# The agent emits multiple messages to fulfill the request.
response = [
    {
        "createdAt": "2025-03-14T06:14:30Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "Hello! Let me quickly look up your account details."
            }
        ]
    },
    {
        "createdAt": "2025-03-14T06:14:35Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "tool_call_20250310_001",
                "name": "get_orders",
                "arguments": {
                    "account_number": "888"
                }
            }
        ]
    },
    # Many more messages are omitted. 
    # ...
    # Here is the agent's final response:
    {
        "createdAt": "2025-03-14T06:15:05Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The order with ID 123 has been shipped and is expected to be delivered on March 15, 2025. However, the order with ID 124 is delayed and should now arrive by March 20, 2025. Is there anything else I can help you with?"
            }
        ]
    }
]

# An example of tool definitions available to the agent:
tool_definitions = [
    {
        "name": "get_orders",
        "description": "Get the list of orders for a given account number.",
        "parameters": {
            "type": "object",
            "properties": {
                "account_number": {
                    "type": "string",
                    "description": "The account number to get the orders for."
                }
            }
        }
    },
    # Other tool definitions are omitted. 
    # ...
]

result = tool_call_accuracy(
    query=query,
    response=response,
    tool_definitions=tool_definitions 
)
print(json.dumps(result, indent=4))

Sehen Sie sich die folgende Ausgabe an (Einzelheiten finden Sie unter Ausgabeformat):

{
    "tool_call_accuracy": 2,  # a score between 1-5, higher is better
    "tool_call_accuracy_result": "fail",
    "tool_call_accuracy_threshold": 3,
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

query = [
    {
        "role": "system",
        "content": "You are an AI assistant interacting with Azure Maps services to serve user requests."
    },
    {
        "createdAt": "2025-04-25T23:55:43Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Find the address for coordinates 41.8781,-87.6298."
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:45Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "call_nqNyhOFRw4FmF50jaCCq2rDa",
                "name": "azure_maps_reverse_address_search",
                "arguments": {
                    "lat": "41.8781",
                    "lon": "-87.6298"
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:47Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "tool_call_id": "call_nqNyhOFRw4FmF50jaCCq2rDa",
        "role": "tool",
        "content": [
            {
                "type": "tool_result",
                "tool_result": {
                    "address": "300 South Federal Street, Chicago, IL 60604",
                    "position": {
                        "lat": "41.8781",
                        "lon": "-87.6298"
                    }
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:48Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The address for the coordinates 41.8781, -87.6298 is 300 South Federal Street, Chicago, IL 60604."
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:50Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What timezone corresponds to 41.8781,-87.6298?"
            }
        ]
    },
]

response = [
    {
        "createdAt": "2025-04-25T23:55:52Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "call_qi2ug31JqzDuLy7zF5uiMbGU",
                "name": "azure_maps_timezone",
                "arguments": {
                    "lat": 41.878100000000003,
                    "lon": -87.629800000000003
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:54Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "tool_call_id": "call_qi2ug31JqzDuLy7zF5uiMbGU",
        "role": "tool",
        "content": [
            {
                "type": "tool_result",
                "tool_result": {
                    "ianaId": "America/Chicago",
                    "utcOffset": None,
                    "abbreviation": None,
                    "isDaylightSavingTime": None
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:55Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The timezone for the coordinates 41.8781, -87.6298 is America/Chicago."
            }
        ]
    }
]

Weitere Beispiele für Agentnachrichten:

import json

# The user asked a question.
query = [
    {
        "role": "system",
        "content": "You are a friendly and helpful customer service agent."
    },
    # Past interactions are omitted. 
    # ...
    {
        "createdAt": "2025-03-14T06:14:20Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Hi, I need help with the last 2 orders on my account #888. Could you please update me on their status?"
            }
        ]
    }
]
# The agent emits multiple messages to fulfill the request.
response = [
    {
        "createdAt": "2025-03-14T06:14:30Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "Hello! Let me quickly look up your account details."
            }
        ]
    },
    {
        "createdAt": "2025-03-14T06:14:35Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "tool_call_20250310_001",
                "name": "get_orders",
                "arguments": {
                    "account_number": "888"
                }
            }
        ]
    },
    # Many more messages are omitted. 
    # ...
    # Here is the agent's final response:
    {
        "createdAt": "2025-03-14T06:15:05Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The order with ID 123 has been shipped and is expected to be delivered on March 15, 2025. However, the order with ID 124 is delayed and should now arrive by March 20, 2025. Is there anything else I can help you with?"
            }
        ]
    }
]

# An example of tool definitions available to the agent:
tool_definitions = [
    {
        "name": "get_orders",
        "description": "Get the list of orders for a given account number.",
        "parameters": {
            "type": "object",
            "properties": {
                "account_number": {
                    "type": "string",
                    "description": "The account number to get the orders for."
                }
            }
        }
    },
    # Other tool definitions are omitted. 
    # ...
]

Probieren Sie eine Probe für jeden dieser Evaluatoren aus.

• Intent-Auflösung
• Genauigkeit des Toolaufrufs
• Aufgabentreue
• Vollständigkeit der Antwort
• End-to-End-Auswertung des Microsoft Foundry-Agents

Probieren Sie ein Beispiel für jedes dieser Bewertungsprogramme im Beispiel-Repository aus.

• Referenzdokumentation zum Python-SDK-Client von Azure KI Auswertung
• Handbuch zur Problembehandlung beim Azure AI Evaluation SDK
• Informationen zu den Auswertungsmetriken
• Auswerten von generativen KI-Anwendungen remote in der Cloud
• Informationen zum Simulieren von Testdatensätzen für die Auswertung
• Anzeigen von Auswertungsergebnissen in einem Foundry-Projekt
• Erste Schritte beim Erstellen einer Chat-App mit dem Microsoft Foundry SDK
• Erste Schritte mit Auswertungsbeispielen

• Handbuch zur Problembehandlung beim Azure AI Evaluation SDK
• Auswerten von generativen KI-Anwendungen remote in der Cloud
• Anzeigen von Auswertungsergebnissen in einem Foundry-Projekt