Avaliadores de agentes

Os agentes de IA são assistentes de produtividade poderosos que conseguem criar fluxos de trabalho para as necessidades do negócio. No entanto, a observabilidade pode ser um desafio devido aos seus padrões complexos de interação. Os avaliadores de agentes fornecem observabilidade sistemática nos fluxos de trabalho agentes, medindo qualidade, segurança e desempenho.

Um fluxo de trabalho de agente normalmente envolve raciocinar através das intenções do utilizador, chamar ferramentas relevantes e usar resultados de ferramentas para completar tarefas como atualizar uma base de dados ou elaborar um relatório. Para construir aplicações agenticas prontas para produção, é necessário avaliar não só o resultado final, mas também a qualidade e eficiência de cada etapa do fluxo de trabalho.

A Foundry fornece avaliadores de agentes incorporados que funcionam como testes unitários para sistemas agentes—recebem mensagens de agentes como entradas e saídas de pontuações binárias de Aprovação/Reprovação (ou pontuações escaladas convertidas em pontuações binárias com base em limiares). Estes avaliadores apoiam duas boas práticas para avaliação de agentes:

• Avaliação do sistema - para examinar os resultados de ponta a ponta do sistema agente.
• Avaliação de processos - verificar a execução passo a passo para alcançar os resultados.

Avaliação do sistema

A avaliação do sistema examina a qualidade do resultado final do seu fluxo de trabalho agente. Estes avaliadores são aplicáveis a agentes individuais e, em sistemas multi-agente, ao orquestrador principal ou ao agente final responsável pela conclusão da tarefa:

• Conclusão da Tarefa - O agente completou totalmente a tarefa solicitada?
• Satisfação do Cliente - Quão satisfeito ficaria um utilizador com o desempenho do agente?
• Cumprimento da Tarefa - O agente seguiu as regras e restrições das suas instruções?
• Eficiência na Navegação de Tarefas - O agente realizou os passos esperados de forma eficiente?
• Resolução de Intenções - O agente identificou e abordou corretamente as intenções do utilizador?

Especificamente, para saídas textuais de agentes, pode também aplicar avaliadores de qualidade RAG, como Relevance e Groundedness que recebem inputs agentivos para avaliar a qualidade final da resposta.

Examples:

• Amostra de conclusão de tarefa (pré-visualização)
• Amostra de adesão à tarefa
• Exemplo de eficiência de navegação de tarefas
• Amostra de resolução de intenção

Avaliação de processos

A avaliação de processos examina a qualidade e eficiência de cada etapa no seu fluxo de trabalho agente. Estes avaliadores focam-se nas chamadas de ferramenta executadas num sistema para completar tarefas:

• Precisão das chamadas de ferramenta - O agente fez as chamadas corretas com os parâmetros corretos sem redundância?
• Seleção de Ferramentas - O agente selecionou as ferramentas corretas e necessárias?
• Precisão da Introdução de Ferramentas - O agente forneceu os parâmetros corretos para as chamadas de ferramenta?
• Utilização da Saída da Ferramenta - O agente usou corretamente os resultados da chamada de ferramenta na sua raciocínio e resposta final?
• Sucesso na Chamada de Ferramenta - As chamadas de ferramenta tiveram sucesso sem erros técnicos?

Examples:

• Amostra de precisão da chamada de ferramenta
• Exemplo de seleção de ferramentas
• Amostra de precisão de entrada da ferramenta
• Amostra de utilização da saída da ferramenta
• Amostra de sucesso da chamada de ferramenta

Avaliação de qualidade (obsoleta)

O Quality Grader avaliava a qualidade global da resposta de um assistente de IA ao nível da turnação. Examinou múltiplas dimensões da qualidade da resposta:

• Relevância - A resposta é relevante para a questão do utilizador?
• Abstenção - O agente abstém-se adequadamente quando não pode ou não deve responder?
• Completude da resposta - A resposta responde totalmente à pergunta do utilizador?

Quando foi fornecido contexto, o Quality Grader também avaliou:

• Fundamentação - A resposta está fundamentada no contexto fornecido?
• Cobertura do contexto - A resposta utiliza a informação relevante no contexto?

Avaliadores compostos (pré-visualização)

Os avaliadores compostos medem várias dimensões de qualidade numa única chamada de juiz de LLM. Use-os para reduzir o custo e a latência de executar os avaliadores incorporados correspondentes separadamente, mantendo uma pontuação e a razão para cada dimensão de qualidade.

Qualidade de Saída

O avaliador de Qualidade de Saída (builtin.output_quality) avalia a qualidade da resposta de um agente e o seu sucesso em abordar a tarefa do utilizador. Agrupa os seguintes avaliadores numa única chamada de juiz LLM:

Qualidade do Uso da Ferramenta

O avaliador de Qualidade de Utilização de Ferramentas (builtin.tool_use_quality) avalia o processo de utilização de ferramentas de um agente desde a seleção da ferramenta até à utilização do resultado devolvido. Agrupa os seguintes avaliadores numa única chamada de juiz LLM:

Resultados compostos

O primário output_quality ou tool_use_quality resultado só passa quando todos os componentes aplicáveis passam. Um componente que não é aplicável é omitido e não faz com que o resultado principal falhe. Se todos os componentes forem saltados, o resultado primário é not_applicable.

Cada avaliador composto devolve um resultado binário primário e os resultados dos seus avaliadores componentes. Use o resultado primário para uma porta de qualidade estrita e use os resultados dos componentes para identificar a dimensão de qualidade que causou uma falha.

Por exemplo, um resultado de Qualidade de Saída falha quando Fluência, Coerência, Resolução de Intenções, Adesão à Tarefa e Conclusão de Tarefa são aprovadas, mas Groundedness falha. Identifica output_quality_reason o Groundedness como o componente falhado e groundedness_reason explica a sua pontuação.

Configurar avaliadores compostos

Ambos os avaliadores compostos apoiam a avaliação por turnos e ao nível da conversa. A forma de entrada determina o nível de avaliação por defeito:

• Mapa query e response para avaliação por turnos.
• Mapa messages para avaliação ao nível da conversa.

Defina o evaluation_level parâmetro de inicialização para turn ou conversation para sobrepor este comportamento.

A configuração seguinte executa ambos os avaliadores compostos ao nível da curva. A resposta contém mensagens de agente com chamadas de ferramenta e resultados de ferramenta, e as definições de ferramentas descrevem as ferramentas disponíveis para o agente.

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "output_quality",
        "evaluator_name": "builtin.output_quality",
        "initialization_parameters": {
            "deployment_name": model_deployment,
            "evaluation_level": "turn",
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "tool_use_quality",
        "evaluator_name": "builtin.tool_use_quality",
        "initialization_parameters": {
            "deployment_name": model_deployment,
            "evaluation_level": "turn",
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
    },
]

Referência: Executar avaliações do SDK

Para avaliar uma conversa completa, mapeie a conversa completa para messages e omita evaluation_level ou defina-a para conversation:

"initialization_parameters": {
    "deployment_name": model_deployment,
    "evaluation_level": "conversation",
},
"data_mapping": {
    "messages": "{{item.messages}}",
    "tool_definitions": "{{item.tool_definitions}}",
},

Referência: Mensagens com chamadas de ferramenta

Suporte a modelos e ferramentas

Para avaliadores assistidos por IA, pode usar Azure modelos de raciocínio OpenAI ou OpenAI e modelos não raciocínios para o juiz do LLM.

Ferramentas suportadas

Os avaliadores de agentes suportam as seguintes ferramentas:

• Pesquisa de ficheiros
• Ferramenta de Função (ferramentas definidas pelo utilizador)
• MCP
• MCP baseado no conhecimento

As seguintes ferramentas têm atualmente suporte limitado. Evite usar tool_call_accuracy, tool input accuracy, tool_output_utilization, tool_call_success, ou groundedness avaliadores se a conversa do seu agente incluir chamadas para estas ferramentas:

• Pesquisa de IA do Azure
• Bing Grounding
• Pesquisa Personalizada do Bing
• Fundamentos do SharePoint
• Intérprete de código
• Agente de Dados Fabric
• Pesquisa na Web

Utilização de avaliadores de agentes

Os avaliadores de agentes avaliam quão bem os agentes de IA executam tarefas, seguem instruções e utilizam ferramentas de forma eficaz. Cada avaliador requer mapeamentos de dados e parâmetros específicos:

A avaliação por turnos avalia a resposta individual do agente; a avaliação ao nível da conversa avalia a interação completa. Use evaluation_level para selecionar o nível quando o avaliador suporta ambos. Para a estrutura da mensagem, veja Mensagens com chamadas de ferramenta.

Exemplo de entrada

O seu conjunto de dados de teste deve conter os campos referenciados nos seus mapeamentos de dados. Exemplos do formato abaixo:

{"query": "What's the weather in Seattle?", "response": "The weather in Seattle is rainy, 14°C."}
{"query": "Book a flight to Paris for next Monday", "response": "I've booked your flight to Paris departing next Monday at 9:00 AM."}
{"messages": [{"role": "user", "content": "Book a flight to Paris."}, {"role": "assistant", "content": "I booked your flight to Paris."}]}

Para interações mais complexas de agentes com chamadas de ferramenta, use arrays de mensagens para query e response. Estes arrays utilizam a mesma estrutura de mensagens OpenAI que o esquema preferido messages . Veja Formato separado de consulta e resposta. A mensagem do sistema é opcional, mas útil para avaliadores que avaliam o comportamento do agente em função de instruções, incluindo task_adherence, task_completion, tool_call_accuracy, tool_selection, tool_input_accuracy, tool_output_utilization, , e groundedness:

{
    "query": [
        {"role": "system", "content": "You are a travel booking agent."},
        {"role": "user", "content": "Book a flight to Paris for next Monday"}
    ],
    "response": [
        {"role": "assistant", "content": [{"type": "tool_call", "tool_call_id": "call_123", "name": "search_flights", "arguments": {"destination": "Paris", "date": "next Monday"}}]},
        {"role": "tool", "tool_call_id": "call_123", "content": [{"type": "tool_result", "tool_result": {"flight": "AF123", "time": "9:00 AM"}}]},
        {"role": "assistant", "content": "I've booked flight AF123 to Paris departing next Monday at 9:00 AM."}
    ]
}

Formato de definições de ferramentas

O tool_definitions campo descreve as ferramentas disponíveis para o agente. Contém uma lista de objetos ferramenta com um nameobjeto , description, e JSON Schema parameters :

[
  {
    "name": "search_flights",
    "description": "Search for available flights to a destination on a given date.",
    "parameters": {
      "type": "object",
      "properties": {
        "destination": { "type": "string", "description": "The destination city." },
        "date": { "type": "string", "description": "The travel date in YYYY-MM-DD format." }
      },
      "required": ["destination", "date"]
    }
  }
]

Inclua esta lista como campo tool_definitions no seu conjunto de dados de teste ao lado query de e response.

Exemplo de configuração

Sintaxe do mapeamento de dados:

• {{item.field_name}} Referências a campos do seu conjunto de dados de teste (por exemplo, {{item.query}}).
• {{sample.output_items}} Referências à saída estruturada do agente, incluindo chamadas de ferramentas e resultados. Use isto para avaliadores que necessitem de contexto de interação completo (task_adherence, tool_call_accuracy, tool_selection, tool_input_accuracy, tool_output_utilization).
• {{sample.output_text}} Referência à resposta do agente em texto simples. Use isto para avaliadores que esperam uma resposta em cadeia (por exemplo, coherence, violence).

Aqui está um exemplo de configuração para a Adesão às Tarefas:

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {"deployment_name": model_deployment},
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
]

Consulte Run evaluations from the SDK para detalhes sobre avaliações em execução e configuração de fontes de dados.

Exemplo de saída

Os avaliadores de agentes devolvem resultados de Aprovado/Reprovado com raciocínio. Campos-chave de saída:

{
    "type": "azure_ai_evaluator",
    "name": "Task Adherence",
    "metric": "task_adherence",
    "label": "pass",
    "reason": "Agent followed system instructions correctly",
    "threshold": 3,
    "passed": true
}

Para avaliadores que utilizam uma escala de 1–5 antes do limiar (como intent_resolution e tool_call_accuracy), o resultado inclui um campo numérico score ao lado do resultado de aprovação/reprovação:

{
    "type": "azure_ai_evaluator",
    "name": "Intent Resolution",
    "metric": "intent_resolution",
    "label": "pass",
    "score": 4,
    "reason": "Agent correctly identified the user's intent to book a flight to Paris",
    "threshold": 3,
    "passed": true
}

Eficiência da navegação de tarefas

A Eficiência de Navegação de Tarefas mede se o agente realizou uma sequência ótima de ações comparando com uma sequência esperada (verdade de base). Use este avaliador para otimização de fluxos de trabalho e testes de regressão.

{
    "type": "azure_ai_evaluator",
    "name": "task_navigation_efficiency",
    "evaluator_name": "builtin.task_navigation_efficiency",
    "initialization_parameters": {
        "matching_mode": "exact_match"  # Options: "exact_match", "in_order_match", "any_order_match"
    },
    "data_mapping": {
        "actions": "{{item.actions}}",
        "expected_actions": "{{item.expected_actions}}"
    },
}

Modos de correspondência:

Formato das ações:

Mapeie ou actions com messagesexpected_actions. O actions campo aceita uma cadeia de caracteres ou uma lista de objetos de mensagem. O messages campo aceita a interação completa como um array de objetos de mensagem. Cada mensagem de ação representa um passo que o agente deu durante a conversa:

actions = [
    {
        "role": "assistant",
        "content": [
            {"type": "function_call", "name": "call_tool_A", "arguments": "{\"param\": \"value\"}"}
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "function_call", "name": "call_tool_B", "arguments": "{}"}
        ]
    },
]

Para fornecer a interação com o agente como mensagens em vez de actions, mapeie messages e expected_actions:

"data_mapping": {
    "messages": "{{item.messages}}",
    "expected_actions": "{{item.expected_actions}}",
}

Formato esperado das ações:

Esta expected_actions pode ser uma lista simples de passos esperados:

expected_actions = ["identify_tools_to_call", "call_tool_A", "call_tool_B", "response_synthesis"]

Ou uma tupla com nomes de ferramentas e parâmetros para validação mais detalhada:

expected_actions = (
    ["func_name1", "func_name2"],
    {
        "func_name1": {"param_key": "param_value"},
        "func_name2": {"param_key": "param_value"},
    }
)

Output:

Devolve um resultado binário de aprovação/reprovação mais precisão, recordação e pontuações F1:

{
    "type": "azure_ai_evaluator",
    "name": "task_navigation_efficiency",
    "passed": true,
    "details": {
        "precision_score": 0.85,
        "recall_score": 1.0,
        "f1_score": 0.92
    }
}

Esquema de mensagens do agente

Os avaliadores de agentes utilizam matrizes de mensagens quando necessitam de instruções, chamadas de ferramentas e resultados de ferramentas. Para a estrutura canónica de mensagens, definições de papéis e dados de exemplo, veja Mensagens com chamadas de ferramenta e Formato separado de consulta e resposta.

Conteúdo relacionado

• Mais exemplos para avaliadores de qualidade de agentes
• Avalie os seus agentes de IA
• Como realizar a avaliação em lote
• Como otimizar o RAG agentico