Evaluadores de llamadas de herramientas para evaluaciones de Microsoft 365 Copilot CLI

Los evaluadores de llamadas a herramientas inspeccionan los diagnósticos en tiempo de ejecución (información para desarrolladores) para comprobar la selección de herramientas y los resultados de ejecución de HTTP. Son deterministas, no usan un juez de LLM y no juzgan el texto de respuesta ni requieren expected_response.

Nota

Los evaluadores de llamadas a herramientas requieren la CLI de evaluaciones de Microsoft 365 Copilot v2 (preview) y esquema v2. No están disponibles en CLI v1 (latest).

Evaluador Comprobaciones Escala Umbral Habilitado de manera predeterminada.
ToolCallSelection Si se seleccionaron las identidades de herramienta esperadas Correcto/suspenso/error 1.0, corregido No
ToolCallExecution Si cada llamada esperada tiene una ejecución HTTP correcta distinta Correcto/suspenso/error 1.0, corregido No

Para la configuración general del conjunto de datos, consulte Configuración de evaluadores.

Configuración de la CLI de versión preliminar

Siga los requisitos previos de acceso al espacio empresarial y tiempo de ejecución en la guía de inicio rápido. La configuración de puntuación de Microsoft Foundry no es necesaria si solo se ejecutan evaluadores deterministas.

Instale la versión preliminar y acepte los términos de licencia:

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

Conjunto TENANT_ID para el inquilino de Microsoft 365 en el entorno de evaluación. Para un agente declarativo implementado, pasar --m365-agent-id "<your-agent-id>" al ejecutar un conjunto de datos.

Para las evaluaciones de complementos independientes, aprovisione y habilite primero el complemento en Microsoft 365 Copilot y complete cualquier inicio de sesión de conector necesario en Copilot. Sin un identificador de agente configurado, la versión preliminar v2 evalúa el chat de Copilot. Mantenga M365_AGENT_ID un legado AGENT_ID fuera del shell y los archivos de entorno cargados para estas ejecuciones. Esto evalúa las respuestas de Copilot que usan un complemento disponible, no el punto de conexión del complemento de forma aislada.

La instalación de cualquiera de las etiquetas de liberación de npm reemplaza el comando global runevals . Para volver a la versión 1, vuelva a instalar @microsoft/m365-copilot-eval@latest.

Permitir llamadas a herramientas

Cuando una herramienta requiera confirmación, configure tanto la aprobación como las expectativas del evaluador. default_allowed_tools a nivel de documento y allowed_tools por indicación o turno, permita que la CLI apruebe las solicitudes de confirmación de la herramienta. Se debe permitir cada identificador de consentimiento solicitado; De lo contrario, el aviso se detiene con un toolCallNotAllowed error.

Importante

Permitir una llamada otorga consentimiento. Revise las operaciones que está aprobando y comience con escenarios de solo lectura. Una expectativa no otorga consentimiento; La aprobación no fuerza la selección ni prueba la ejecución. Las herramientas que no solicitan confirmación no están controladas por esta lista, por lo que no es un límite de seguridad.

Los identificadores de consentimiento son diferentes de calls[].tool las identidades. No divida los identificadores de consentimiento para rellenar los campos de identidad del evaluador.

Buscar nombres de llamada de herramientas

En el caso de los agentes declarativos, úselo runevals --list-tools para indicar los identificadores de consentimiento y las identidades de evaluador listas para copiar. El Kit de herramientas de agentes de Microsoft 365 también puede inspeccionar la información de lanzamiento del agente adquirido. No se admite el caso de complementos independientes; en su lugar, --list-tools cree identificadores de consentimiento desde el manifiesto de la aplicación.

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

Es posible que las herramientas detectadas dinámicamente no aparezcan en la lista. Después de una evaluación de llamada a la herramienta, confirme sus identidades diagnostics.tool_callsen el archivo .

El Kit de herramientas de agentes requiere acceso a la aplicación y un inicio de sesión de Microsoft 365 independiente (atk auth login m365). Su cuenta puede diferir de la cuenta utilizada para la evaluación.

Complementos independientes

Construye cada identificador de consentimiento a partir del manifiesto de la aplicación del complemento (agentConnectors[]) como se indica a continuación:

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

Conserve la carcasa. Quite espacios, guiones, guiones bajos, signos de puntuación y caracteres que no sean ASCII solo del nombre para mostrar del conector. Mantenga el nombre de la función sin cambios.

Nombre para mostrar del conector Nombre de la función allowed_tools entrada
Contoso Catalog get_product ContosoCatalog_get_product
Contoso Catalog-Tools_1! get_product ContosoCatalogTools1_get_product

Como alternativa, ejecute una evaluación una vez: si una herramienta requiere consentimiento y no está permitida, el mensaje de resultado incluye su nombre de herramienta.

Identidad de llamada de herramienta

Los tres campos de identidad son obligatorios dentro de calls[].tool:

Campo Tipo Descripción
plugin_id cadena Copiar M365_TITLE_ID desde el archivo de entorno del agente implementado o del proyecto del complemento, por ejemplo env\.env.local. Este es el ID de título del paquete (plugin.titleId en Información del desarrollador), noplugin.id. Necesario incluso cuando la CLI ya se dirige a ese agente declarativo.
toolset_id cadena Para una acción de agente declarativo, use su actions[].id en el manifiesto de agente declarativo. Para un complemento independiente, úsalo agentConnectors[].id en el manifiesto de la aplicación.
function_name cadena Nombre de función definido por el complemento, por ejemplo get_product. Conserva la carcasa; esto se indica como functionDisplayName en la Información para desarrolladores.

La tupla (plugin_id, toolset_id, function_name) identifica una herramienta de forma única. La coincidencia distingue mayúsculas de minúsculas. Utilice los identificadores de acción o de conector, no los nombres para mostrar. Por ejemplo:

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

Configuración del evaluador

Configure estas opciones en ToolCallSelection o ToolCallExecution en , o default_evaluatorsen un objeto de artículo o turno evaluators :

Opción Tipo Requerido Descripción
calls matriz Sí Lista no vacía de selecciones o ejecuciones esperadas.
calls[].id cadena No Etiqueta diagnóstica local del evaluador no vacía; no un identificador de llamada en tiempo de ejecución. Use una etiqueta única para cada expectativa.
calls[].tool objeto Sí Los tres campos de la identidad de llamada a la herramienta.
allow_additional_calls Booleano No Solo ToolCallSelection. El valor predeterminado es true. Establézcalo en false para rechazar cualquier identidad seleccionada adicional, incluidas las selecciones no identificadas.

ToolCallSelection

ToolCallSelection comprueba el conjunto de identidades de herramienta esperadas, omitiendo el orden y los duplicados. No comprueba el éxito de la ejecución ni el recuento de llamadas.

Conjunto de datos de muestra ToolCallSelection

Guarde este conjunto de datos como evals\tool-selection.json. Reemplace las identidades de ejemplo y el identificador de consentimiento por los suyos propios:

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

Ejecutar en un agente declarativo implementado:

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

En un escenario de complemento independiente, omita --m365-agent-id y asegúrese de que no se haya configurado ningún ID de agente, como se describe en Configuración de la CLI de versión preliminar.

Los siguientes resultados suponen plugin_id y toolset_id coinciden con el ejemplo.

Selecciones observadas Resultado de este ejemplo
get_product, incluidas las entradas duplicadas Aprobado
get_product y otra función Fallo: selección adicional
No hay funciones seleccionadas ([]) Fallo: falta la selección necesaria
Telemetría no disponible (null) Error

ToolCallExecution

ToolCallExecution requiere una ejecución coincidente distinta con un entero estado HTTP 200-299 para cada entrada en calls. Repita una identidad para requerir varias ejecuciones correctas.

Se permiten intentos adicionales, incluidos los reintentos erróneos. El éxito de HTTP por sí solo no establece la corrección comercial ni la calidad de la respuesta.

Conjunto de datos de ejemplo ToolCallExecution

Guarde este conjunto de datos y evals\tool-execution.json reemplace las identidades de ejemplo y el identificador de consentimiento por los suyos propios:

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

Ejecute el conjunto de datos con la misma configuración de destino que el ejemplo de selección:

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-execution.json --output results\tool-execution.json
Resultados HTTP coincidentes observados Resultado de este ejemplo
200, 200 Aprobado
500, 200, 200 Aprobado: dos éxitos a pesar de un intento fallido
200 Error: solo un éxito
200, Desconocido Error: el resultado desconocido podría satisfacer la segunda llamada

En este ejemplo se comprueban dos llamadas correctas, no los identificadores de producto que se usaron. Cada expectativa requiere una ejecución distinta; Una ejecución no puede satisfacer a ambos.

Interpretar resultados

Use estas reglas para distinguir los errores del evaluador:

Observación Resultado
Todas las selecciones esperadas están presentes y se cumplen las reglas para las selecciones adicionales Pases de selección
Una selección requerida está ausente de una lista autorizada Error en la selección
Suficientes ejecuciones HTTP 2xx distintas coinciden con todas las identidades esperadas Pasos de ejecución
Falta una identidad de ejecución esperada o los resultados confirmados hacen imposible el recuento de éxitos necesario Error en la ejecución
Una llamada observada tiene una identidad incompleta No se acredita a ninguna llamada esperada
La telemetría necesaria no está disponible, varios artefactos de información del desarrollador impiden una instantánea autoritativa o los resultados HTTP no analizables podrían cambiar el veredicto Error del evaluador: toolCallEvidenceIndeterminate

Un fracaso definitivo tiene prioridad si la evidencia desconocida no puede completar todas las expectativas. Los intentos adicionales ilegibles no invalidan suficientes éxitos confirmados.

Aprobado = 1.0; Suspenso = 0.0. Los errores omiten score y threshold; no son pases o necesariamente defectos del agente. Las claves de puntuación JSON son toolCallSelection y 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"
    }
  }
}

Evaluación de diagnósticos y respuesta guardada

Resultado Evidencia de llamada a herramientas
JSON diagnostics.tool_calls
CSV Objeto de diagnóstico serializado completo
HTML/consola Diagnóstico de llamadas a herramientas con selecciones y resultados HTTP

La visualización de la selección deduplica las identidades; Los diagnósticos de ejecución conservan cada intento. null significa evidencia no disponible; [] significa una observación autorizada de no llamadas.

Volver a puntuar las selecciones guardadas y los resultados de la ejecución sin ejecutar indicaciones. Cada artículo guardado o turno debe incluir un response:

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

Advertencia

Los diagnósticos pueden contener detalles confidenciales de la herramienta y la ejecución. EVALS_SUPPRESS_DIAGNOSTICS=true Omite diagnósticos retenidos.

No redacta indicaciones, respuestas, opciones de evaluador ni mensajes de validación nativos. Revise los artefactos antes de compartirlos. Las pruebas suprimidas no están disponibles para su reproducción.