Avaliar seus agentes de IA (versão prévia)

Nesse processo, a avaliação de cada etapa do fluxo de trabalho e a qualidade e a segurança da saída final são cruciais. Formulamos esses aspectos 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 de chamada de ferramenta: mede se o agente fez as chamadas corretas de ferramenta funcional para uma solicitação de um usuário.
• Adesão à tarefa: mede se a resposta final do agente adere às tarefas atribuídas, de acordo com sua mensagem do sistema e as etapas anteriores.

Avalie outros aspectos de qualidade e segurança de seus fluxos de trabalho agente usando nosso conjunto abrangente de avaliadores internos. Em geral, os agentes emitem mensagens do agente. Transformar mensagens de agente nos dados de avaliação corretos para nossos avaliadores pode ser desafiador. Se você criar seu agente usando o Serviço do Foundry Agent, poderá avaliá-lo perfeitamente por meio do nosso suporte de conversor. Se você criar seu agente fora do Serviço de Agentes da Fábrica, ainda poderá usar nossos avaliadores conforme apropriado para seu fluxo de trabalho com agentes autônomos, analisando as mensagens do agente nos formatos de dados obrigatórios. Veja exemplos na avaliação de outros agentes.

Como prática recomendada, é crucial executar:

• Avaliação do sistema: avalie a qualidade geral e a eficiência do fluxo de trabalho do agente; e
• Avaliação do processo: avaliar as etapas de chamada da ferramenta do fluxo de trabalho.

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

Você também pode avaliar outros aspectos de qualidade e segurança de seus fluxos de trabalho agênticos, usando nosso conjunto abrangente de avaliadores internos ou criar avaliadores personalizados.

Se você estiver criando os agentes Foundry, poderá avaliá-los facilmente.

Se você criar seus agentes fora do Foundry, ainda poderá usar nossas ferramentas de avaliação conforme apropriado para o fluxo de trabalho dos agentes, analisando as mensagens do agente nos formatos de dados necessários. Consulte os detalhes na avaliação de outros agentes.

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

pip install azure-ai-evaluation

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

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

Defina essas variáveis de ambiente com seus valores em um .env arquivo:

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 você usar o Serviço do Foundry Agent, poderá avaliar perfeitamente seus agentes usando nosso suporte de conversor para agentes do Microsoft Foundry e agentes kernel semânticos. Os seguintes avaliadores dão suporte aos dados de avaliação retornados pelo conversor: IntentResolution, ToolCallAccuracy, TaskAdherence, Relevance e Groundedness.

Suporte de modelo para avaliadores assistidos por IA

Os modelos de raciocínio e os modelos sem raciocínio do AzureOpenAI e do OpenAI suportam o LLM-judge, dependendo dos avaliadores:

Para uma avaliação complexa que requer raciocínio refinado, use um modelo de raciocínio forte, como 4.1-mini para um equilíbrio de desempenho de raciocínio e eficiência de custo.

Suporte à avaliação de chamada de ferramenta

ToolCallAccuracyEvaluator dá suporte à avaliação no Microsoft Foundry Agent para as seguintes ferramentas:

• Pesquisa de Arquivo
• Pesquisa de IA do Azure 
• Fundamento do Bing
• Pesquisa Personalizada do Bing
• Fundamentos do SharePoint
• Interpretador de Código
• Agente de Dados do Fabric
• OpenAPI
• Ferramenta de Função (ferramentas definidas pelo usuário)

No entanto, se você usar uma ferramenta sem suporte na execução do agente, o avaliador produzirá um "passe" e um motivo pelo qual não há suporte para avaliar as ferramentas invocadas, para facilitar a filtragem desses casos. Para habilitar a avaliação, encapsule ferramentas sem suporte como ferramentas definidas pelo usuário.

Este exemplo mostra como criar e avaliar um agente do Microsoft Foundry. Separadamente da avaliação, o Serviço de Agente da Fábrica requer pip install azure-ai-projects azure-identity, uma cadeia de conexão de projeto da Fábrica, e os modelos com suporte.

Criar conversas e execuções de agentes

Os agentes podem usar ferramentas. Aqui está um exemplo de criação de ferramentas personalizadas para o agente usar (usando uma função de clima 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 você 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 uma única execução de agente

Depois de criar as execuções do agente, você pode usar nosso conversor para transformar os dados da thread do agente Microsoft Foundry nos dados de avaliação necessários que os avaliadores podem entender.

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 esses avaliadores. Você não precisa ler os requisitos de entrada para cada avaliador ou fazer qualquer trabalho para analisar as entradas. Selecione o avaliador e chame o avaliador nesta única execução. Oferecemos suporte aos modelos de raciocínio Azure OpenAI ou OpenAI e aos modelos sem raciocínio 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 ou os mini modelos da série o posteriormente lançados, com um equilíbrio de desempenho de raciocínio e eficiência de custo.

Configuramos uma lista de avaliadores de qualidade e segurança em quality_evaluators e safety_evaluators e os referenciamos em avaliar várias execuções de agente ou um 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 da saída

Os avaliadores de qualidade assistidos por IA retornam 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 1 a 5) ou um float entre 0 e 1.
• {metric_name}_label: fornece um rótulo binário (se a métrica naturalmente gerar uma pontuação binária).
• {metric_name}_reason: explica por que uma determinada pontuação ou rótulo foi fornecido para cada ponto de dados.
• details: saída opcional que contém informações de depuração sobre a qualidade de uma única execução de agente.

Para melhorar a clareza, todos os avaliadores aceitam um limite binário (a menos que 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 "aprovado" ou "reprovado" com base em um limite de binarização.
• {metric_name}_threshold: um limite de binarização numérica definido por padrão ou pelo usuário.

Confira o exemplo de saída a seguir 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
}

Avaliar várias execuções ou conversas de agentes

Para avaliar várias execuções ou threads de agentes, use a API evaluate() em lote para avaliação assíncrona. Primeiro, converta os dados de thread do agente em um arquivo usando nosso suporte de conversor:

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 única execução 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")}')

Depois de selecionar a URL, você será redirecionado para o Foundry. Exiba os resultados da avaliação em seu projeto do Foundry e depure seu aplicativo. Use campos de motivo e resultados de aprovação/falha para avaliar o desempenho de qualidade e segurança de seus aplicativos. Você pode executar e comparar várias execuções para testar a regressão ou melhorias.

Use a biblioteca cliente do SDK de Avaliação de IA do Azure para avaliar seus agentes do Microsoft Foundry com suporte para conversor, habilitando a observabilidade e a transparência nos fluxos de trabalho dos agentes.

Você pode avaliar de forma integrada os agentes do Foundry usando avaliadores em Agente Avaliadores e avaliadores de RAG. Esta seção explica 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

Configure um agente com o conjunto de ferramentas e crie 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 sempre geram o seguinte esquema:

• Rótulo: um rótulo binário "aprovado" ou "reprovado", semelhante à saída de um teste de unidade. Use esse resultado para facilitar comparações entre avaliadores.
• Pontuação: uma pontuação da escala natural de cada avaliador. Alguns avaliadores usam uma rubrica refinada, pontuando em uma escala de 5 pontos (avaliadores de qualidade) ou uma escala de 7 pontos (avaliadores de segurança de conteúdo). Outros, como avaliadores de similaridade textual, usam as pontuações F1, que são valores flutuantes entre 0 e 1. O campo “rótulo” binariza qualquer “pontuação” não binária para “aprovado” ou “reprovado” com base no “limite”.
• Limite: todas as pontuações não binárias são binárias para "passar" ou "falhar" com base em um limite padrão, que você pode substituir na experiência do SDK.
• Motivo: para melhorar a inteligibilidade, todos os avaliadores LLM-judge também geram um campo de raciocínio para explicar por que uma determinada pontuação é atribuída.
• Detalhes: (opcional) Para alguns avaliadores, como tool_call_accuracy, pode haver um campo "detalhes" ou sinalizadores que contêm informações adicionais para ajudar os usuários a depurar seus aplicativos. Para resultados agregados sobre vários exemplos de dados (um conjunto de dados), a taxa média dos exemplos com “aprovação” forma a taxa de aprovação para esse conjunto de dados.

Após a URL, você será redirecionado para o Foundry. Você pode exibir os resultados da avaliação em seu projeto do Foundry e depurar seu aplicativo. Use os campos "reason" e "pass/fail" para avaliar a qualidade e o desempenho de segurança de seus aplicativos. Você pode executar e comparar várias execuções para testar a regressão ou melhorias.

Use a biblioteca de clientes python do SDK do Microsoft Foundry para avaliar seus agentes do Microsoft Foundry, permitindo a observabilidade e a transparência nos fluxos de trabalho do agente.

Se você usar agentes fora do Serviço de Agente, ainda poderá avaliá-los preparando os dados certos para os avaliadores de sua escolha.

Normalmente, os agentes emitem mensagens para interagir com um usuário ou outros agentes. Os avaliadores internos aceitam tipos de dados simples, como cadeias de caracteres, queryresponsee ground_truth de acordo com os requisitos de entrada de dados de turno único. No entanto, extrair esses tipos de dados simples de mensagens de agente pode ser desafiador devido aos padrões de interação complexos de agentes e diferenças de estrutura. Por exemplo, uma única consulta de usuário pode disparar uma longa lista de mensagens de agente, normalmente com várias chamadas de ferramenta invocadas.

Normalmente, os agentes emitem mensagens para interagir com um usuário ou outros agentes. Nossos avaliadores internos podem aceitar tipos de dados simples, como cadeias de caracteresqueryresponse, e ground_truth de acordo com os requisitos de entrada de dados de turno único. No entanto, pode ser um desafio extrair esses tipos de dados simples de mensagens de agente, devido aos padrões de interação complexos de agentes e diferenças de estrutura. Por exemplo, uma única consulta de usuário pode disparar uma longa lista de mensagens de agente, normalmente com várias chamadas de ferramenta invocadas. Mostramos exemplos de esquema de mensagens do agente no esquema de mensagens do Agente com tool_definitions e tool_calls inseridos em query e response.

Conforme ilustrado no exemplo a seguir, habilitamos o suporte a mensagens do agente para os seguintes avaliadores internos para avaliar esses aspectos do fluxo de trabalho agente. Esses avaliadores podem usar tool_calls ou tool_definitions como parâmetros exclusivos para agentes ao avaliar agentes.

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

Para ToolCallAccuracyEvaluator, você deve fornecer response ou tool_calls.

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

Os exemplos a seguir mostram os dois formatos de dados: dados de agente simples e mensagens de agente. No entanto, devido aos requisitos exclusivos desses avaliadores, recomendamos fazer referência aos blocos de anotações de exemplo, que ilustram os possíveis caminhos de entrada para cada avaliador.

Todos os avaliadores de qualidade integrados assistidos por IA retornam um resultado de aprovação ou reprovação para cada entrada.

Dados simples do agente

No formato de dados do agente simples, query e response são cadeias de caracteres simples do Python. 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))

Consulte a saída a seguir (consulte o formato de saída para obter 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))

Veja a saída a seguir (consulte o formato de saída para obter mais 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))

Veja a saída a seguir (consulte o formato de saída para obter mais 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 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. 
    # ...
]

Experimente um exemplo para cada um desses avaliadores:

• Resolução de intenção
• Precisão da chamada de ferramenta
• Adesão à tarefa
• Integridade da resposta
• Avaliação de agente do Microsoft Foundry de ponta a ponta

Experimente um exemplo para cada um desses avaliadores no repositório de exemplo.

• Documentação de referência do cliente do SDK Python de avaliação da IA do Azure
• Guia de solução de problemas do cliente do SDK de Avaliação de IA do Azure
• Saiba mais sobre as métricas de avaliação
• Avaliar aplicativos de IA do Generative remotamente na nuvem
• Saiba mais sobre como simular conjuntos de dados de teste para avaliação
• Exibir resultados de avaliação em um projeto do Foundry
• Introdução à criação de um aplicativo de chat usando o SDK do Microsoft Foundry
• Comece com os exemplos de avaliação

• Guia de solução de problemas do cliente do SDK de Avaliação de IA do Azure
• Avaliar aplicativos de IA do Generative remotamente na nuvem
• Exibir resultados de avaliação em um projeto do Foundry