Avaliadores de chamada de ferramenta para a CLI de avaliações do Microsoft 365 Copilot

Os avaliadores de chamada de ferramenta inspecionam o diagnóstico de tempo de execução (Informações do Desenvolvedor) para verificar a seleção de ferramentas e os resultados da execução HTTP. Eles são determinísticos, não usam um juiz LLM e não julgam o texto de resposta ou exigem expected_response.

Observação

Os avaliadores de chamada de ferramenta exigem o CLI v2 e o esquema v2 das Avaliações do Microsoft 365 Copilot v2preview. Elas não estão disponíveis na CLI v1 (latest).

Avaliador Verificações Scale Limite Habilitado por padrão
ToolCallSelection Se as identidades de ferramenta esperadas foram selecionadas Aprovado/reprovado/erro 1.0, corrigido Não
ToolCallExecution Se cada chamada esperada tem uma execução HTTP bem-sucedida distinta Aprovado/reprovado/erro 1.0, corrigido Não

Para obter a configuração geral do conjunto de dados, consulte Configurar avaliadores.

Configurar a CLI de visualização

Siga os pré-requisitos de acesso e de tempo de execução do locatário no início rápido. A configuração de pontuação do Microsoft Foundry não é necessária se você executar apenas avaliadores determinísticos.

Instale a versão prévia e aceite os termos de licença:

npm install -g @microsoft/m365-copilot-eval@preview
runevals accept-eula

Defina TENANT_ID para o seu locatário do Microsoft 365 em seu ambiente de avaliação. Para um agente declarativo implantado, passe --m365-agent-id "<your-agent-id>" ao executar um conjunto de dados.

Para avaliações de plug-in independentes, provisione e habilite o plug-in no Microsoft 365 Copilot primeiro e conclua todas as entradas necessárias do conector no Copilot. Sem nenhuma ID de agente configurada, a versão prévia v2 avalia o Copilot Chat. Mantenha M365_AGENT_ID um legado AGENT_ID fora do shell e arquivos de ambiente carregados para essas execuções. Isso avalia as respostas do Copilot que usam um plug-in disponível, não o ponto de extremidade do plug-in isoladamente.

A instalação da marca de versão npm substitui o comando global runevals . Para retornar à v1, reinstale @microsoft/m365-copilot-eval@latesto .

Permitir chamadas de ferramenta

Quando uma ferramenta exigir confirmação, configure as expectativas de aprovação e do avaliador. default_allowed_tools no nível do documento e allowed_tools por prompt ou turno, permita que a CLI aprove os prompts de confirmação da ferramenta. Todos os identificadores de consentimento solicitados devem ser permitidos; Caso contrário, o prompt será interrompido com um toolCallNotAllowed erro.

Importante

Permitir uma chamada concede consentimento. Examine as operações que você está aprovando e comece com cenários somente leitura. Uma expectativa não concede consentimento; A aprovação não força a seleção nem prova a execução. As ferramentas que não solicitam confirmação não são controladas por esta lista, portanto, ela não é um limite de segurança.

Identificadores de consentimento são diferentes de calls[].tool identidades. Não divida identificadores de consentimento para preencher os campos de identidade do avaliador.

Localizar nomes de chamadas de ferramenta

Para agentes declarativos, use runevals --list-tools para listar identificadores de consentimento e identidades de avaliador prontas para cópia. O Microsoft 365 Agents Toolkit também pode inspecionar as informações de inicialização do agente adquirido. Para plug-ins autônomos, não há suporte; em vez disso, --list-tools construa identificadores de consentimento a partir do manifesto do aplicativo.

Agentes declarativos

# List consent identifiers and evaluator identities for declarative agent actions.
npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"

# Alternatively, inspect launch information with Agents Toolkit.
# Use the package Title ID without the .declarativeAgent suffix.
atk launchinfo --title-id "<your-title-id>"

As ferramentas descobertas dinamicamente podem não estar listadas. Após uma avaliação de chamada de ferramenta, confirme suas identidades diagnostics.tool_callsno arquivo .

O Kit de Ferramentas de Agentes requer acesso ao aplicativo e uma entrada separada do Microsoft 365 (atk auth login m365). Seu relato pode ser diferente do relato usado para avaliação.

Plug-ins autônomos

Construa cada identificador de consentimento a partir do manifesto do aplicativo do plug-in (agentConnectors[]) da seguinte maneira:

<connector display name with only A-Z, a-z, and 0-9 retained>_<function name>

Preserve o invólucro. Remova espaços, hifens, sublinhados, pontuação e caracteres não ASCII somente do nome de exibição do conector. Mantenha o nome da função inalterado.

Nome de exibição do conector Nome da função allowed_tools entrada
Contoso Catalog get_product ContosoCatalog_get_product
Contoso Catalog-Tools_1! get_product ContosoCatalogTools1_get_product

Como alternativa, execute uma avaliação uma vez: Se uma ferramenta exigir consentimento e não for permitida, a mensagem de resultado incluirá o nome da ferramenta.

Identidade de chamada de ferramenta

Todos os três campos de identidade são obrigatórios dentro calls[].toolde:

Campo Tipo Descrição
plugin_id cadeia de caracteres Copie M365_TITLE_ID do arquivo de ambiente do seu agente implantado ou do projeto de plug-in, por exemplo env\.env.local. Esta é a ID do título do pacote (plugin.titleId em informações do desenvolvedor), nãoplugin.id. Necessário mesmo quando a CLI já tem como alvo esse agente declarativo.
toolset_id cadeia de caracteres Para uma ação de agente declarativo, use its actions[].id no manifesto do agente declarativo. Para um plug-in independente, use-o agentConnectors[].id no manifesto do aplicativo.
function_name cadeia de caracteres Nome da função definido pelo seu plug-in, por exemplo get_product. Preservar invólucro; isso é relatado como functionDisplayName em Informações do desenvolvedor.

A tupla (plugin_id, toolset_id, function_name) identifica exclusivamente uma ferramenta. A correspondência diferencia maiúsculas de minúsculas. Usam IDs de ação ou de conector, não nomes de exibição. Por exemplo:

{
  "plugin_id": "T_1234",
  "toolset_id": "catalog",
  "function_name": "get_product"
}

Configuração do avaliador

Configure estas opções em ToolCallSelection ou ToolCallExecution em default_evaluators, ou no objeto de um item ou turno evaluators :

Opção Tipo Obrigatório Descrição
calls matriz Sim Lista não vazia de seleções ou execuções esperadas.
calls[].id cadeia de caracteres Não Rótulo de diagnóstico local do avaliador não vazio; não é uma ID de chamada de runtime. Use um rótulo exclusivo para cada expectativa.
calls[].tool objeto Sim Todos os três campos da identidade de chamada de ferramenta.
allow_additional_calls booleano Não Somente ToolCallSelection. O padrão é true. Defina como false para rejeitar qualquer identidade selecionada extra, incluindo seleções não identificadas.

ToolCallSelection

ToolCallSelection verifica o conjunto de identidades de ferramenta esperadas, ignorando a ordem e as duplicatas. Ele não verifica o sucesso da execução ou as contagens de chamadas.

Conjunto de dados de exemplo ToolCallSelection

Salve este conjunto de dados como evals\tool-selection.json. Substitua as identidades de exemplo e o identificador de consentimento pelos seus:

{
  "schemaVersion": "2.0.0",
  "default_allowed_tools": ["ContosoCatalog_get_product"],
  "default_evaluators": {
    "ToolCallSelection": {
      "calls": [
        {
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        }
      ],
      "allow_additional_calls": false
    }
  },
  "items": [
    {
      "prompt": "Find product SKU-123 in the Contoso Catalog."
    }
  ]
}

Executar em relação a um agente declarativo implantado:

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-selection.json --output results\tool-selection.json

Para um cenário de plug-in autônomo, omita --m365-agent-id e certifique-se de que nenhuma ID de agente esteja configurada, conforme descrito em Configurar a CLI de visualização.

Os resultados a seguir pressupõem plugin_id e toolset_id correspondem ao exemplo.

Seleções observadas Resultado neste exemplo
get_product, incluindo entradas duplicadas Aprovado
get_product e outra função Falha: seleção adicional
Nenhuma função selecionada ([]) Falha: seleção necessária ausente
Telemetria indisponível (null%) Erro

ToolCallExecution

ToolCallExecution requer uma execução de correspondência distinta com um status HTTP inteiro 200-299 para cada entrada no calls. Repetir uma identidade para exigir várias execuções bem-sucedidas.

Tentativas adicionais, incluindo tentativas com falha, são permitidas. O sucesso do HTTP por si só não estabelece a correção dos negócios ou a qualidade da resposta.

Conjunto de dados de exemplo ToolCallExecution

Salve este conjunto de dados e evals\tool-execution.json substitua as identidades de exemplo e o identificador de consentimento pelo seu:

{
  "schemaVersion": "2.0.0",
  "default_evaluators": {
    "ToolCallExecution": {
      "calls": [
        {
          "id": "first-lookup",
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        },
        {
          "id": "second-lookup",
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        }
      ]
    }
  },
  "items": [
    {
      "prompt": "Look up products SKU-123 and SKU-456 individually in the Contoso Catalog.",
      "allowed_tools": ["ContosoCatalog_get_product"]
    }
  ]
}

Execute o conjunto de dados com a mesma configuração de destino que o exemplo de seleção:

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-execution.json --output results\tool-execution.json
Resultados HTTP correspondentes observados Resultado neste exemplo
200, 200 Aprovado
500, 200, 200 Passe: dois sucessos apesar de uma tentativa fracassada
200 Falha: apenas um sucesso
200, desconhecido Erro: o resultado desconhecido pode satisfazer a segunda chamada

Este exemplo verifica duas chamadas bem-sucedidas, não quais IDs de produto foram usadas. Cada expectativa requer uma execução distinta; Uma execução não pode satisfazer ambos.

Interpretar os resultados

Use estas regras para distinguir falhas de erros do avaliador:

Observação Resultado
Todas as seleções esperadas estão presentes e as regras para seleções adicionais são atendidas A seleção é aprovada
Uma seleção obrigatória está ausente de uma lista autoritativa Falha na seleção
Execuções HTTP 2xx distintas suficientes correspondem a todas as identidades esperadas Passes de execução
Uma identidade de execução esperada está ausente ou os resultados confirmados impossibilitam a contagem de sucesso necessária Falha na execução
Uma chamada observada tem uma identidade incompleta Não creditado a nenhuma chamada esperada
A telemetria necessária não está disponível, vários artefatos de Informações do Desenvolvedor impedem um snapshot autoritativo ou resultados HTTP não analisáveis podem mudar o veredicto Erro do avaliador: toolCallEvidenceIndeterminate

Uma falha definitiva tem precedência se evidências desconhecidas não puderem completar todas as expectativas. Tentativas extras ilegíveis não invalidam sucessos confirmados suficientes.

Aprovado = 1.0; reprovado = 0.0. Os erros omitem score e threshold; eles não são passes ou necessariamente defeitos de agente. As chaves de pontuação JSON são toolCallSelection e toolCallExecution:

{
  "scores": {
    "toolCallSelection": {
      "score": 1.0,
      "result": "pass",
      "threshold": 1.0,
      "reason": "All expected tool functions were selected."
    },
    "toolCallExecution": {
      "result": "error",
      "error": "Developer Info execution telemetry is unavailable.",
      "code": "toolCallEvidenceIndeterminate"
    }
  }
}

Diagnóstico e avaliação de resposta salva

Saída Evidência de chamada de ferramenta
.JSON diagnostics.tool_calls
CSV Objeto de diagnóstico serializado completo
HTML / console Diagnóstico de chamada de ferramenta com seleções e resultados HTTP

A exibição de seleção desduplica identidades; Os diagnósticos de execução preservam todas as tentativas. null significa provas indisponíveis; [] significa uma observação autorizada de nenhuma chamada.

Reavalie as seleções salvas e os resultados da execução sem executar prompts. Cada item ou turno salvo deve incluir um response:

npx -y --package @microsoft/m365-copilot-eval@preview runevals --evaluate-only results\captured-tool-calls.json --output results\rescored.html

Aviso

Os diagnósticos podem conter detalhes confidenciais de ferramenta e execução. EVALS_SUPPRESS_DIAGNOSTICS=trueomite os diagnósticos retidos.

Ele não redigirá prompts, respostas, opções do avaliador ou mensagens de validação nativas. Examinar artefatos antes de compartilhar. As evidências suprimidas não estão disponíveis para repetição.