Evaluación de los agentes de IA (versión preliminar)

En este proceso, evaluar cada paso del flujo de trabajo y la calidad y seguridad de la salida final es fundamental. Formulamos estos aspectos de evaluación en los siguientes evaluadores para agentes:

• Resolución de Intención: Mide si el agente identifica correctamente la intención del usuario.
• Precisión de las llamadas de herramientas: mide si el agente realizó las llamadas correctas de herramientas funcionales según la solicitud de un usuario.
• Cumplimiento de tareas: mide si la respuesta final del agente se adhiere a sus tareas asignadas, según su mensaje del sistema y los pasos anteriores.

Evalúe otros aspectos de calidad y seguridad de los flujos de trabajo agente mediante nuestro completo conjunto de evaluadores integrados. En general, los agentes emiten mensajes de agente. La transformación de mensajes del agente en los datos de evaluación correctos para nuestros evaluadores puede ser difícil. Si compila el agente mediante Servicio de agente de Fundición, puede evaluarlo sin problemas a través de nuestra compatibilidad con convertidores. Si compila el agente fuera del Servicio de agente de Fundición, puede seguir usando nuestros evaluadores según corresponda para el flujo de trabajo de agente mediante el análisis de los mensajes del agente en los formatos de datos necesarios. Vea ejemplos de evaluación de otros agentes.

Como procedimiento recomendado, es fundamental realizar lo siguiente:

• Evaluación del sistema: evalúe la calidad general y la eficacia del flujo de trabajo del agente; y
• Evaluación de procesos: evalúe los pasos de invocación de la herramienta del workflow.

Consulte evaluadores de agentes para obtener información detallada sobre el caso de uso de las dos prácticas y un ejemplo de cada evaluador de agentes.

También puede evaluar otros aspectos de calidad y seguridad de los flujos de trabajo agente mediante nuestro completo conjunto de evaluadores integrados o escribir evaluadores personalizados.

Si va a crear agentes de Foundry, puede evaluarlos sin problemas.

Si desarrollas los agentes fuera de Foundry, puedes seguir usando nuestros evaluadores según corresponda a tu flujo de trabajo de agentes, mediante el procesamiento de los mensajes de tu agente en los formatos de datos necesarios. Consulte los detalles de Evaluación de otros agentes.

Instale el paquete de evaluadores desde el SDK de evaluación de Azure AI:

pip install azure-ai-evaluation

Instale el paquete desde el SDK de evaluación de Azure AI:

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

Establezca estas variables de entorno en un archivo .env con sus valores.

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.

Si usa el Foundry Agent Service, puede evaluar a sus agentes sin problemas utilizando nuestra compatibilidad con convertidores para agentes de Microsoft Foundry y Kernel Semántico. Los siguientes evaluadores admiten los datos de evaluación devueltos por el convertidor: IntentResolution, ToolCallAccuracy, TaskAdherence, Relevancey Groundedness.

Compatibilidad del modelo con evaluadores asistidos por IA

Los modelos de razonamiento de AzureOpenAI y OpenAI, y los modelos no de razonamiento, respaldan la evaluación de LLM dependiendo de los evaluadores:

Para una evaluación compleja que requiere un razonamiento refinado, use un modelo de razonamiento sólido como 4.1-mini para un equilibrio de rendimiento de razonamiento y rentabilidad.

Apoyo en la evaluación de llamadas de herramientas

ToolCallAccuracyEvaluator admite la evaluación en Microsoft Foundry Agent para las siguientes herramientas:

• Búsqueda de archivos
• Azure AI Search
• Fundamentos de Bing
• Bing Custom Search
• Puesta en tierra de SharePoint
• Intérprete de código
• Agente de datos de Fabric
• OpenAPI
• Function Tool (herramientas definidas por el usuario)

Sin embargo, si se utiliza una herramienta no compatible en la ejecución del agente, el evaluador emite un "aprobado" y una razón por la que no se admite la evaluación de las herramientas invocadas, para facilitar el filtrado de estos casos. Para habilitar la evaluación, encapsula las herramientas no admitidas como herramientas definidas por el usuario.

En este ejemplo se muestra cómo compilar y evaluar un agente de Microsoft Foundry. Por separado de la evaluación, el servicio Foundry Agent requiere pip install azure-ai-projects azure-identity, una cadena de conexión del proyecto Foundry y los modelos admitidos.

Creación de subprocesos de agente y ejecuciones

Los agentes pueden usar herramientas. Este es un ejemplo de creación de herramientas personalizadas para que el agente lo use (mediante una función meteorológica simulada como ejemplo):

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"

Si usa un proyecto Foundry (no Hub) cree un agente con el conjunto de herramientas como se indica a continuación:

Cree un agente con el conjunto de herramientas de la manera siguiente:

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

Evaluación de una sola ejecución de agente

Después de crear ejecuciones de agente, puede usar nuestro convertidor para transformar los datos del subproceso del agente de Microsoft Foundry en los datos de evaluación necesarios que los evaluadores pueden comprender.

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)

Eso es todo. converted_data contiene todas las entradas necesarias para estos evaluadores. No es necesario leer los requisitos de entrada de cada evaluador ni realizar ningún trabajo para analizar las entradas. Seleccione el evaluador y llame al evaluador en esta única ejecución. Se admiten modelos de razonamiento de Azure OpenAI o OpenAI y modelos de no razonamiento para el juez en función de los evaluadores:

En el caso de las tareas complejas que requieren un razonamiento refinado para la evaluación, se recomienda un modelo de razonamiento sólido como o3-mini o los mini modelos de la serie O publicados después con un equilibrio entre el rendimiento del razonamiento y la eficiencia de los costos.

Armamos una lista de evaluadores de calidad y seguridad en quality_evaluators y safety_evaluators y hacemos referencia a ellos al evaluar varias ejecuciones de agentes o un hilo.

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

Formato de salida

Los evaluadores de calidad asistidos por IA devuelven un resultado para un par de consultas y respuestas. El resultado es un diccionario que incluye:

• {metric_name}: proporciona una puntuación numérica, en una escala likert (entero de 1 a 5) o un float entre 0 y 1.
• {metric_name}_label: proporciona una etiqueta binaria (si la métrica genera naturalmente una puntuación binaria).
• {metric_name}_reason: explica por qué se ha proporcionado una determinada puntuación o etiqueta para cada punto de datos.
• details: salida opcional que contiene información de depuración sobre la calidad de la ejecución de un único agente.

Para mejorar la claridad, todos los evaluadores aceptan un umbral binario (a menos que sus salidas ya sean binarias) y generen dos claves nuevas. Para el umbral de binarización, se establece un valor predeterminado, que el usuario puede invalidar. Las dos claves nuevas son:

• {metric_name}_result: una cadena "pass" o "fail" basada en un umbral de binarización.
• {metric_name}_threshold: umbral de binarización numérico establecido de forma predeterminada o por el usuario.

Consulte la siguiente salida de ejemplo para algunos evaluadores:

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

Evaluación de varias ejecuciones o subprocesos del agente

Para evaluar varias ejecuciones o subprocesos del agente, use la API por lotes evaluate() para la evaluación asincrónica. En primer lugar, convierta los datos del subproceso del agente en un archivo mediante nuestro soporte de conversión.

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

Con los datos de evaluación preparados en una línea de código, puede seleccionar los evaluadores con el fin de evaluar la calidad del agente y realizar una evaluación por lotes. En el ejemplo siguiente, hacemos referencia a la misma lista de evaluadores de calidad y seguridad en la sección Evaluación de una sola ejecución de agentequality_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")}')

Después de seleccionar la dirección URL, se le redirigirá a Foundry. Vea los resultados de la evaluación en el proyecto Foundry y depure la aplicación. Use los campos de motivo y los resultados de paso o error para evaluar la calidad y el rendimiento de seguridad de las aplicaciones. Puede ejecutar y comparar varias ejecuciones para probar la regresión o las mejoras.

Use la biblioteca cliente del SDK de evaluación de Azure AI para evaluar los agentes de Microsoft Foundry con compatibilidad con convertidores, lo que permite la observabilidad y la transparencia en los flujos de trabajo del agente.

Puede evaluar sin problemas los agentes de Foundry mediante evaluadores en Evaluadores de agente y Evaluadores RAG. En esta sección se explica cómo crear un agente y evaluarlo.

Prerrequisitos

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

Configure un agente con el conjunto de herramientas y cree una ejecución de respuesta para evaluar.

Cree un agente con el conjunto de herramientas de la manera siguiente:

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

Interpretación de los resultados

Para obtener un único ejemplo de datos, todos los evaluadores siempre generan el esquema siguiente:

• Etiqueta: una etiqueta binaria "pass" o "fail", similar a la salida de una prueba unitaria. Use este resultado para facilitar las comparaciones entre evaluadores.
• Puntuación: una puntuación de la escala natural de cada evaluador. Algunos evaluadores usan una referencia específica, la puntuación en una escala de 5 puntos (evaluadores de calidad) o una escala de 7 puntos (evaluadores de seguridad de contenido). Otros, como evaluadores de similitud textual, usan puntuaciones F1, que son números flotantes entre 0 y 1. El campo "label" binariza cualquier "score" no binario a "aprobado" o "con errores" basado en el "umbral".
• Umbral: las puntuaciones no binarias se binarizan para "pasar" o "fallar" basándose en un umbral predeterminado, que se puede modificar en la experiencia del SDK.
• Motivo: con el fin de mejorar la inteligibilidad, todos los evaluadores de LLM también generan un campo de justificación para explicar por qué se da una puntuación determinada.
• Detalles: (opcional) Para algunos evaluadores, como tool_call_accuracy, puede haber un campo o marcas de "detalles" que contengan información adicional para ayudar a los usuarios a depurar sus aplicaciones. Para obtener resultados agregados en varios ejemplos de datos (un conjunto de datos), la tasa media de los ejemplos con un "aprobado" forma la tasa de aprobación de ese conjunto de datos.

Después de la dirección URL, se le redirigirá a Foundry. Puede ver los resultados de evaluación en el proyecto Foundry y depurar la aplicación. Utilice los campos de "motivo" y de "aprobado/reprobado" para evaluar el rendimiento de calidad y seguridad de sus aplicaciones. Puede ejecutar y comparar varias ejecuciones para probar la regresión o las mejoras.

Use la biblioteca cliente de Python del SDK de Microsoft Foundry para evaluar los agentes de Microsoft Foundry, lo que permite la observabilidad y la transparencia en los flujos de trabajo del agente.

Si usa agentes fuera del servicio del agente, puede evaluarlos preparando los datos adecuados para los evaluadores de su elección.

Normalmente, los agentes emiten mensajes para interactuar con un usuario u otros agentes. Los evaluadores integrados aceptan tipos de datos simples, como cadenas en query, responsey ground_truth según los requisitos de entrada de datos de un solo turno. Sin embargo, extraer estos tipos de datos simples de los mensajes del agente puede ser difícil debido a los patrones de interacción complejos de agentes y diferencias de marco. Por ejemplo, una sola consulta de usuario puede desencadenar una larga lista de mensajes de agente, normalmente con varias llamadas de herramienta invocadas.

Normalmente, los agentes emiten mensajes para interactuar con un usuario u otros agentes. Nuestros evaluadores integrados pueden aceptar tipos de datos simples, como cadenas en query, responsey ground_truth según los requisitos de entrada de datos de un solo turno. Sin embargo, puede ser un desafío extraer estos tipos de datos simples de los mensajes del agente, debido a los patrones de interacción complejos de agentes y diferencias de marco. Por ejemplo, una sola consulta de usuario puede desencadenar una larga lista de mensajes de agente, normalmente con varias llamadas de herramienta invocadas. Se muestran ejemplos de esquema de mensajes del agente en el esquema de mensajes del agente con tool_definitions y tool_calls incrustados en query y response.

Como se muestra en el ejemplo siguiente, habilitamos la compatibilidad de mensajes del agente con los siguientes evaluadores integrados para evaluar estos aspectos del flujo de trabajo agente. Estos evaluadores pueden tomar tool_calls o tool_definitions como parámetros únicos para los agentes al evaluar agentes.

• Message: dict mensaje de estilo OpenAI que describe las interacciones del agente con un usuario, donde query debe incluir un mensaje del sistema como primer mensaje.
• ToolCall: dict que especifica las llamadas de herramienta invocadas durante las interacciones del agente con un usuario.
• ToolDefinition: dict que describe las herramientas disponibles para un agente.

Para ToolCallAccuracyEvaluator, debe proporcionar response o tool_calls.

GroundednessEvaluator requiere que tool_definitions evalúe la fundamentación de las respuestas del agente con respecto a los resultados que el agente recibe de la herramienta.

En los ejemplos siguientes se muestran los dos formatos de datos: datos simples del agente y mensajes del agente. Sin embargo, debido a los requisitos únicos de estos evaluadores, se recomienda hacer referencia a los cuadernos de ejemplo, que ilustran las posibles rutas de acceso de entrada para cada evaluador.

Todos los evaluadores de calidad integrados asistidos por IA generan un pase o no para cada entrada.

Datos simples del agente

En un formato de datos de agente simple, query y response son cadenas simples de Python. Por ejemplo:

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

Consulte la salida siguiente (consulte Formato de salida para obtener más información):

{
    "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.",
}

Consulte los ejemplos siguientes de tool_calls y tool_definitions para ToolCallAccuracyEvaluator:

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

Consulte la salida siguiente (formato de salida de referencia para obtener más información):

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

Consulte los ejemplos siguientes de tool_calls y tool_definitions para tool_call_accuracy:

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."
            }
        ]
    }
]

Vea un ejemplo de evaluación de los mensajes del agente con 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))

Consulte la salida siguiente (formato de salida de referencia para obtener más información):

{
    "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."
            }
        ]
    }
]

Más ejemplos de mensajes del agente:

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. 
    # ...
]

Pruebe un ejemplo para cada uno de estos evaluadores:

• Resolución de intenciones
• Precisión de la llamada a la herramienta
• Cumplimiento de tareas
• Integridad de la respuesta
• Evaluación del agente de Microsoft Foundry de un extremo a otro

Pruebe un ejemplo para cada uno de estos evaluadores en el repositorio de ejemplo.

• Documentación de referencia del cliente del SDK de Python de evaluación de AZURE AI
• Guía de solución de problemas del SDK de evaluación de Azure AI
• Más información sobre las métricas de evaluación
• Evaluación de aplicaciones de IA generativas de forma remota en la nube
• Más información sobre la simulación de conjuntos de datos de prueba para la evaluación
• Ver los resultados de la evaluación en un proyecto Foundry
• Introducción a la creación de una aplicación de chat mediante el SDK de Microsoft Foundry
• Introducción a los ejemplos de evaluación

• Guía de solución de problemas del SDK de evaluación de Azure AI
• Evaluación de aplicaciones de IA generativas de forma remota en la nube
• Ver los resultados de la evaluación en un proyecto Foundry