Avalie os seus agentes de IA (pré-visualização)

Neste processo, avaliar cada etapa do fluxo de trabalho e a qualidade e segurança do resultado final é crucial. Formulamos estes aspetos de avaliação nos seguintes avaliadores para agentes:

• Resolução de intenção: mede se o agente identifica corretamente a intenção do usuário.
• Precisão da chamada de ferramenta: mede se o agente fez as chamadas de ferramenta de função corretas para a solicitação de um usuário.
• Adesão à tarefa: Mede se a resposta final do agente está de acordo com as tarefas atribuídas, de acordo com a mensagem do sistema e as etapas anteriores.

Avalie outros aspetos de qualidade e segurança dos seus fluxos de trabalho agentivos utilizando a nossa abrangente suite de avaliadores integrados. Em geral, os agentes emitem mensagens dos agentes. Transformar as mensagens dos agentes nos dados corretos de avaliação para os nossos avaliadores pode ser um desafio. Se construir o seu agente usando o Foundry Agent Service, poderá avaliá-lo perfeitamente por meio do nosso suporte de conversão. Se você criar seu agente fora do Foundry Agent Service, ainda poderá usar nossos avaliadores conforme apropriado para seu fluxo de trabalho de agente, analisando as mensagens do agente nos formatos de dados necessários. Veja exemplos na avaliação de outros agentes.

Como boa prática, é crucial realizar:

• Avaliação do Sistema: avaliar a qualidade e eficiência global do fluxo de trabalho do agente; e
• Avaliação de Processos: avalie as etapas de chamada de ferramentas no fluxo de trabalho.

Consulte os avaliadores de agentes para informações detalhadas sobre o caso de uso das duas práticas e uma amostra de cada avaliador de agentes.

Também pode avaliar outros aspetos de qualidade e segurança dos seus fluxos de trabalho agêncicos, utilizando o nosso conjunto abrangente de avaliadores integrados ou escrever avaliadores personalizados.

Se estiver a construir Foundry Agents, pode avaliá-los sem problemas.

Se construir os seus agentes fora do Foundry, pode ainda usar os nossos avaliadores de forma apropriada ao fluxo de trabalho dos seus agentes, processando as mensagens dos seus agentes nos formatos de dados necessários. Veja os detalhes em Avaliação de outros agentes.

Instale o pacote de avaliadores do SDK de avaliação da IA do Azure:

pip install azure-ai-evaluation

Instale o pacote a partir do Azure AI Evaluation SDK:

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

Defina estas variáveis de ambiente com os seus valores num .env ficheiro:

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.

Se usar o Foundry Agent Service, pode avaliar os seus agentes de forma fluida utilizando o nosso suporte de conversores para agentes Microsoft Foundry e agentes Semantic Kernel. Os seguintes avaliadores suportam dados de avaliação devolvidos pelo conversor: IntentResolution, ToolCallAccuracy, TaskAdherence, Relevance, e Groundedness.

Suporte de modelo para avaliadores assistidos por IA

Modelos de raciocínio AzureOpenAI e OpenAI e modelos não-raciocínios suportam o juiz LLM dependendo dos avaliadores:

Para avaliações complexas que requerem raciocínio refinado, use um modelo de raciocínio forte, como 4.1-mini para equilibrar o desempenho do raciocínio e a eficiência de custos.

Apoio à avaliação de utilização de ferramentas

ToolCallAccuracyEvaluator suporta a avaliação no Microsoft Foundry Agent para as seguintes ferramentas:

• Pesquisa de Ficheiros
• Pesquisa de IA do Azure
• Aterramento do Bing
• Pesquisa Personalizada do Bing
• Fundamentação do SharePoint
• Intérprete de código
• Agente de Dados de Rede
• OpenAPI
• Ferramenta de função (ferramentas definidas pelo usuário)

No entanto, se usar uma ferramenta não suportada na execução do agente, o avaliador emite um "pass" e uma explicação indicando que avaliar as ferramentas invocadas não é suportado, para facilitar a exclusão destes casos. Para permitir a avaliação, envolva ferramentas não suportadas como ferramentas definidas pelo utilizador.

Este exemplo mostra como construir e avaliar um agente Microsoft Foundry. Independentemente da avaliação, o Foundry Agent Service requer pip install azure-ai-projects azure-identity, uma string de conexão do projeto Foundry e os modelos suportados.

Criar threads e execuções de agente

Os agentes podem usar ferramentas. Aqui está um exemplo de criação de ferramentas personalizadas para o agente usar (usando uma função meteorológica simulada como exemplo):

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"

Se usar um projeto Foundry (não Hub), crie um agente com o conjunto de ferramentas da seguinte forma:

Crie um agente com o conjunto de ferramentas da seguinte maneira:

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

Avaliar a execução de um único agente

Depois de criar execuções de agentes, pode usar o nosso conversor para transformar os dados do thread de agentes do Microsoft Foundry nos dados de avaliação necessários que os avaliadores possam compreender.

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)

É isso! converted_data contém todas as entradas necessárias para estes avaliadores. Não precisas de ler os requisitos de entrada de cada avaliador nem de fazer qualquer trabalho para analisar as entradas. Selecione o seu avaliador e chame-o nesta única passagem. Suportamos modelos de raciocínio Azure OpenAI ou OpenAI e modelos não-raciocínios para o juiz, dependendo dos avaliadores:

Para tarefas complexas que exigem raciocínio refinado para a avaliação, recomendamos um modelo de raciocínio forte, como o3-mini os modelos mini da série O, lançados posteriormente, com um equilíbrio entre desempenho de raciocínio e eficiência de custos.

Criámos uma lista de avaliadores de qualidade e segurança em quality_evaluators e safety_evaluators e referenciámo-los na avaliação de múltiplas execuções de agentes ou uma thread.

# 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 saída

Avaliadores de qualidade assistidos por IA devolvem um resultado para um par de consulta e resposta. O resultado é um dicionário que inclui:

• {metric_name}: Fornece uma pontuação numérica, em uma escala Likert (inteiro de 1 a 5) ou um flutuador entre 0 e 1.
• {metric_name}_label: Fornece um rótulo binário (se a métrica produz naturalmente uma pontuação binária).
• {metric_name}_reason: Explica por que uma determinada pontuação ou rótulo foi dado para cada ponto de dados.
• details: Saída opcional contendo informações de depuração sobre a qualidade da execução de um único agente.

Para melhorar a clareza, todos os avaliadores aceitam um limiar binário (a menos que as suas saídas já sejam binárias) e geram duas novas chaves. Para o limite de binarização, um padrão é definido, que o usuário pode substituir. As duas novas chaves são:

• {metric_name}_result: Uma cadeia de caracteres "pass" ou "fail" com base num limiar de binarização.
• {metric_name}_threshold: Um limite de binarização numérica definido por padrão ou pelo usuário.

Veja o seguinte exemplo de saída para alguns avaliadores:

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

Avalie múltiplas execuções ou threads de agentes

Para avaliar múltiplas execuções ou threads de agentes, utilize a API batch evaluate() para avaliação assíncrona. Primeiro, converta os dados do seu thread de agente num ficheiro usando a nossa ferramenta de conversão:

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

Com os dados de avaliação preparados em uma linha de código, você pode selecionar os avaliadores para avaliar a qualidade do agente e enviar uma execução de avaliação em lote. No exemplo a seguir, fazemos referência à mesma lista de avaliadores de qualidade e segurança na seção Avaliar uma execuçãoquality_and_safety_evaluators de agente único:

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

Depois de selecionares o URL, és redirecionado para o Foundry. Veja os resultados da sua avaliação no projeto Foundry e depure a sua aplicação. Use campos de razão e resultados de sucesso/insucesso para avaliar a qualidade e o desempenho em segurança das suas aplicações. Você pode executar e comparar várias execuções para testar a regressão ou melhorias.

Use a biblioteca cliente Azure AI Evaluation SDK para avaliar os seus agentes Microsoft Foundry com suporte a conversores, permitindo observabilidade e transparência nos fluxos de trabalho dos agentes.

Pode avaliar os agentes da Foundry de forma fluida utilizando avaliadores nos Agent Evaluators e RAG. Esta secção guia-o como criar um agente e avaliá-lo.

Pré-requisitos

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

Configura um agente com o conjunto de ferramentas e cria uma execução de resposta para avaliar.

Crie um agente com o conjunto de ferramentas da seguinte maneira:

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

Interpretação dos resultados

Para um único exemplo de dados, todos os avaliadores apresentam sempre o seguinte esquema:

• Rótulo: um rótulo binário de "passar" ou "falhar", semelhante à saída de um teste unitário. Use este resultado para facilitar comparações entre avaliadores.
• Pontuação: uma pontuação da escala natural de cada avaliador. Alguns avaliadores utilizam uma rubrica detalhada, avaliando numa escala de 5 pontos (avaliadores de qualidade) ou numa escala de 7 pontos (avaliadores de segurança de conteúdos). Outros, como os avaliadores de similaridade textual, usam pontuações F1, que são flutuantes entre 0 e 1. O campo "label" binariza qualquer "pontuação" não-binária para "pass" ou "fail" com base no "limiar".
• Limiar: quaisquer pontuações não-binárias são binarizadas para "passar" ou "reprovar" com base num limiar padrão, que podes sobrepor na experiência SDK.
• Razão: Para melhorar a inteligibilidade, todos os avaliadores de juízes LLM também produzem um campo de raciocínio para explicar porque é atribuída uma certa pontuação.
• Detalhes: (opcional) Para alguns avaliadores, como o tool_call_accuracy, pode haver um campo "detalhes" ou flags que contêm informação adicional para ajudar os utilizadores a depurar as suas aplicações. Para resultados agregados em múltiplos exemplos de dados (um conjunto de dados), a proporção média dos exemplos que conseguiram 'aprovação' forma a taxa de aprovação desse conjunto de dados.

Depois do URL, és redirecionado para o Foundry. Pode ver os resultados da sua avaliação no seu projeto Foundry e depurar a sua aplicação. Use campos de "razão" e aprovar/reprovar para avaliar a qualidade e o desempenho em segurança das suas candidaturas. Você pode executar e comparar várias execuções para testar a regressão ou melhorias.

Use a biblioteca cliente Python do Microsoft Foundry SDK para avaliar os seus agentes Microsoft Foundry, permitindo observabilidade e transparência nos fluxos de trabalho dos agentes.

Se utilizar agentes externos ao Serviço de Agentes, pode ainda assim avaliá-los preparando os dados certos para os avaliadores da sua escolha.

Os agentes normalmente emitem mensagens para interagir com um usuário ou outros agentes. Os avaliadores incorporados aceitam tipos de dados simples, como cadeias em query, response, e ground_truth de acordo com os requisitos de entrada de dados de uma volta. No entanto, extrair estes tipos de dados simples das mensagens dos agentes pode ser desafiante devido aos padrões complexos de interação dos agentes e às diferenças no framework. Por exemplo, uma única consulta de usuário pode disparar uma longa lista de mensagens de agente, geralmente com várias chamadas de ferramenta invocadas.

Os agentes normalmente emitem mensagens para interagir com um usuário ou outros agentes. Os nossos avaliadores incorporados podem aceitar tipos de dados simples, como cadeias em query, response, e ground_truth de acordo com os requisitos de entrada de dados de uma volta. No entanto, pode ser um desafio extrair esses tipos de dados simples das mensagens do agente, devido aos complexos padrões de interação dos agentes e às diferenças de estrutura. Por exemplo, uma única consulta de usuário pode disparar uma longa lista de mensagens de agente, geralmente com várias chamadas de ferramenta invocadas. Mostramos exemplos de esquema de mensagens de agente em esquema de mensagens de agente com tool_definitions e tool_calls embutidos em query e response.

Conforme ilustrado no exemplo a seguir, habilitamos o suporte a mensagens de agente para os seguintes avaliadores internos para avaliar esses aspetos do fluxo de trabalho agentico. Estes avaliadores podem tomar tool_calls ou tool_definitions como parâmetros únicos dos agentes ao avaliar agentes.

• Message: dict Mensagem no estilo OpenAI que descreve as interações do agente com um utilizador, onde deve incluir uma mensagem do query sistema como a primeira mensagem.
• ToolCall: dict que especifica as chamadas de ferramenta invocadas durante as interações do agente com um usuário.
• ToolDefinition: dict que descreve as ferramentas disponíveis para um agente.

Para ToolCallAccuracyEvaluator, deve fornecer response ou tool_calls.

GroundednessEvaluator requer tool_definitions avaliar a fundamentação das respostas do agente relativamente aos resultados da ferramenta que o agente recebe.

Os exemplos seguintes mostram os dois formatos de dados: dados simples de agente e mensagens de agente. No entanto, devido aos requisitos únicos destes avaliadores, recomendamos que consulte os cadernos de amostras, que ilustram os possíveis caminhos de entrada para cada avaliador.

Todos os avaliadores de qualidade integrados com assistência de IA apresentam uma nota de aprovação ou reprovação para cada entrada.

Dados simples do agente

Em formato de dados de agente simples, query e response são cadeias de caracteres Python simples. Por exemplo:

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

Veja a seguinte saída (consulte o formato de saída para detalhes):

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

Veja os seguintes exemplos de tool_calls e 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 a seguinte saída (referência Formato de saída para obter detalhes):

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

Veja os seguintes exemplos de tool_calls e 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."
            }
        ]
    }
]

Veja um exemplo de avaliação das mensagens do agente com 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 a seguinte saída (referência Formato de saída para obter detalhes):

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

Mais exemplos de mensagens de agentes:

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

Experimente um exemplo para cada um destes avaliadores:

• Resolução de intenções
• Precisão da chamada da ferramenta
• Adesão à tarefa
• Exaustividade da resposta
• Avaliação de agentes Microsoft Foundry de ponta a ponta

Experimente uma amostra para cada um destes avaliadores no repositório de amostras.

• Documentação de referência do cliente para o SDK do Azure AI Evaluation em Python
• Guia de solução de problemas do cliente do Azure AI Evaluation SDK
• Saiba mais sobre as métricas de avaliação
• Avaliar aplicações de IA generativa remotamente na cloud
• Aprenda sobre a simulação de conjuntos de dados de teste para avaliação
• Ver resultados de avaliação num projeto Foundry
• Comece a construir uma aplicação de chat usando o Microsoft Foundry SDK
• Introdução às amostras de avaliação

• Guia de solução de problemas do cliente do Azure AI Evaluation SDK
• Avaliar aplicações de IA generativa remotamente na cloud
• Ver resultados de avaliação num projeto Foundry