Avaliadores de Agentes

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

Um fluxo de trabalho do agente normalmente envolve o raciocínio por meio de intenções do usuário, a chamada de ferramentas relevantes e o uso de resultados de ferramentas para concluir tarefas como atualizar um banco de dados ou elaborar um relatório. Para criar aplicativos agente prontos para produção, você precisa avaliar não apenas a saída final, mas também a qualidade e a eficiência de cada etapa no fluxo de trabalho.

A Foundry fornece avaliadores de agente internos que funcionam como testes de unidade para sistemas agente— eles levam mensagens de agente como pontuações de passagem/falha binárias de entrada e saída (ou pontuações dimensionadas convertidas em pontuações binárias com base nos limites). Esses avaliadores dão suporte a duas práticas recomendadas para avaliação do agente:

• Avaliação do sistema – para examinar os resultados de ponta a ponta do sistema agente.
• Avaliação do processo – para verificar a execução passo a passo para obter os resultados.

Avaliação do sistema

A avaliação do sistema examina a qualidade do resultado final do fluxo de trabalho agente. Esses avaliadores são aplicáveis a agentes únicos e, em sistemas de vários agentes, ao orquestrador principal ou ao agente final responsável pela conclusão da tarefa:

• Conclusão da tarefa – O agente concluiu totalmente a tarefa solicitada?
• Satisfação do cliente – Qual seria o nível de satisfação do usuário com o desempenho do agente?
• Adesão à tarefa - O agente seguiu as regras e restrições em suas instruções?
• Eficiência de Navegação de Tarefas – O agente executou as etapas esperadas com eficiência?
• Resolução de intenção – o agente identificou e abordou corretamente as intenções do usuário?

Especificamente, para saídas textuais de agentes, você também pode aplicar avaliadores de qualidade RAG, como Relevance e Groundedness que usam entradas agente para avaliar a qualidade da resposta final.

Exemplos:

• exemplo de conclusão Task (versão prévia)
• exemplo de adesão Task
• exemplo de eficiência de navegação Task
• exemplo de resolução Intent

Avaliação do processo

A avaliação do processo examina a qualidade e a eficiência de cada etapa em seu fluxo de trabalho agente. Esses avaliadores se concentram nas chamadas de ferramenta executadas em um sistema para concluir tarefas:

• Precisão de Chamada de Ferramenta – O agente fez as chamadas de ferramenta certas com parâmetros corretos sem redundância?
• Seleção de Ferramentas – O agente selecionou as ferramentas corretas e necessárias?
• Precisão de entrada da ferramenta – o agente forneceu parâmetros corretos para chamadas de ferramenta?
• Utilização da saída da ferramenta – o agente usou corretamente os resultados da chamada de ferramenta em seu raciocínio e resposta final?
• Êxito na chamada de ferramenta – as chamadas da ferramenta tiveram êxito sem erros técnicos?

Exemplos:

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

Avaliação de qualidade (preterida)

O Quality Grader avaliou a qualidade geral da resposta de um assistente de IA no nível da curva. Ele examinou várias dimensões da qualidade da resposta:

• Relevância – A resposta é relevante para a consulta do usuário?
• Abstenção - O agente se abstém adequadamente quando não pode ou não deve responder?
• Integridade da resposta – A resposta aborda totalmente a pergunta do usuário?

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

• Aterramento - A resposta está fundamentada no contexto fornecido?
• Cobertura de contexto – A resposta usa as informações relevantes no contexto?

Avaliadores compostos (versão prévia)

Os avaliadores compostos medem várias dimensões de qualidade em uma chamada de juiz LLM. Use-os para reduzir o custo e a latência de executar os avaliadores internos correspondentes separadamente, mantendo uma pontuação e um motivo 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 seu sucesso em lidar com a tarefa do usuário. Ele agrupa os seguintes avaliadores em uma chamada de juiz llm:

Qualidade de Uso da Ferramenta

O avaliador de Qualidade de Uso da Ferramenta (builtin.tool_use_quality) avalia o processo de uso de ferramentas de um agente da seleção de ferramentas por meio do uso do resultado retornado. Ele agrupa os seguintes avaliadores em uma chamada de juiz llm:

Resultados compostos

O resultado ou tool_use_quality primário output_quality passa somente quando todos os componentes aplicáveis são aprovados. Um componente que não é aplicável é ignorado e não faz com que o resultado primário falhe. Se todos os componentes forem ignorados, o resultado primário será not_applicable.

Cada avaliador composto retorna um resultado binário primário e os resultados de seus avaliadores de componente. Use o resultado primário para uma porta de qualidade estrita e use os resultados do componente 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ção, Adesão de Tarefa e Conclusão da Tarefa são aprovados, mas a aterramento falha. Identifica output_quality_reason a aterramento como o componente com falha e explica sua groundedness_reason pontuação.

Configurar avaliadores compostos

Ambos os avaliadores compostos dão suporte à avaliação em nível de turno e de conversa. A forma de entrada determina o nível de avaliação por padrão:

• Mapeie query e response para avaliação em nível de turno.
• Mapa messages para avaliação em nível de conversa.

Defina o evaluation_level parâmetro de inicialização como turn ou conversation para substituir esse comportamento.

A configuração a seguir executa os dois avaliadores compostos no nível da curva. A resposta contém mensagens de agente com chamadas de ferramenta e resultados de ferramentas, e as definições de ferramenta 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 e messages omita evaluation_level ou defina-a como 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, você pode usar Azure modelos openai ou openai reasoning e modelos sem raciocínio para o juiz llm.

Ferramentas com suporte

Os avaliadores do agente dão suporte às seguintes ferramentas:

• Pesquisa de Arquivo
• Ferramenta de Função (ferramentas definidas pelo usuário)
• MCP
• MCP baseado em conhecimento

No momento, as ferramentas a seguir têm suporte limitado. Evite usar tool_call_accuracy, tool input accuracy, tool_output_utilization, tool_call_successou groundedness avaliadores se a conversa do agente incluir chamadas para estas ferramentas:

• Pesquisa de IA do Azure 
• Fundamentos do Bing
• Pesquisa Personalizada do Bing
• Fundamentos do SharePoint
• Interpretador de códigos
• Agente de Dados do Fabric
• Pesquisa na Web

Usando avaliadores de agente

Os avaliadores do agente avaliam como os agentes de IA executam tarefas, seguem instruções e usam as ferramentas com eficiência. Cada avaliador requer mapeamentos e parâmetros de dados específicos:

A avaliação em nível de turno pontua uma resposta de agente individual; A avaliação no nível da conversa pontua a interação completa. Use evaluation_level para selecionar o nível quando o avaliador oferecer suporte a ambos. Para obter a estrutura de mensagens, consulte Mensagens com chamadas de ferramenta.

Exemplo de entrada

Seu conjunto de dados de teste deve conter os campos referenciados em seus mapeamentos de dados. Exemplos para o 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 de agente mais complexas com chamadas de ferramenta, use matrizes de mensagens para query e response. Essas matrizes usam a mesma estrutura de mensagens OpenAI que o esquema preferencial messages . Consulte o formato de consulta e resposta separados. A mensagem do sistema é opcional, mas útil para avaliadores que avaliam o comportamento do agente em relação às instruções, incluindo task_adherence, , task_completion, tool_call_accuracy, tool_selection, tool_input_accuracy, tool_output_utilizatione 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 ferramenta

O tool_definitions campo descreve as ferramentas disponíveis para o agente. Ele contém uma lista de objetos de ferramenta com um objeto de esquema parameters JSON e um namedescriptionobjeto JSON:

[
  {
    "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 essa lista como o tool_definitions campo em seu conjunto de dados de teste ao lado query e response.

Exemplo de configuração

Sintaxe de mapeamento de dados:

• {{item.field_name}} faz referência a campos do conjunto de dados de teste (por exemplo, {{item.query}}).
• {{sample.output_items}} faz referência à saída estruturada do agente, incluindo chamadas de ferramenta e resultados. Use isso para avaliadores que precisam de contexto de interação completo (task_adherence, , tool_call_accuracy, tool_selection, tool_input_accuracy, ). tool_output_utilization
• {{sample.output_text}} faz referência à resposta de texto sem formatação do agente. Use isso para avaliadores que esperam uma resposta de cadeia de caracteres (por exemplo, coherence, ). violence

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

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 Executar avaliações do SDK para obter detalhes sobre como executar avaliações e configurar fontes de dados.

Saída de exemplo

Os avaliadores do agente retornam resultados de aprovação/falha com raciocínio. Campos de saída de chave:

{
    "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 usam uma escala de 1 a 5 antes do limite (como intent_resolution e tool_call_accuracy), a saída inclui um campo numérico score junto com o resultado de passagem/falha:

{
    "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 de navegação da tarefa

A Eficiência de Navegação da Tarefa mede se o agente tomou uma sequência ideal de ações comparando-se com uma sequência esperada (verdade básica). Use este avaliador para otimização de fluxo de trabalho e teste 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 de ações:

Mapear ou actionsmessages com expected_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 uma matriz de objetos de mensagem. Cada mensagem de ação representa uma etapa que o agente tomou 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 do agente como mensagens em vez de actions, mapear messages e expected_actions:

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

Formato de ações esperadas:

Pode expected_actions ser uma lista simples de etapas esperadas:

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

Saída:

Retorna um resultado de passagem/falha binário mais precisão, recall 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 agente usam matrizes de mensagens quando precisam de instruções, chamadas de ferramenta e resultados de ferramentas. Para obter a estrutura de mensagens canônicas, definições de função e dados de exemplo, consulte Mensagens com chamadas de ferramenta e formato de consulta e resposta separados.

Conteúdo relacionado

• Mais exemplos para o avaliador de qualidade do agente
• Avaliar seus agentes de IA
• Como executar a avaliação em lote
• Como otimizar o RAG agente