Esquema do conjunto de dados e design de teste

Os conjuntos de dados de avaliação são arquivos JSON que contêm prompts e respostas esperadas. Este artigo define o esquema do conjunto de dados, documenta onde a ferramenta procura conjuntos de dados e mostra como projetar testes eficazes, incluindo cenários avançados, como conversas em vários turnos, configuração do avaliador por item e conjuntos de testes categorizados.

Visão geral do esquema

Os conjuntos de dados de avaliação são arquivos JSON. A ferramenta dá suporte a duas formas equivalentes: um objeto versionado (recomendado) e uma matriz herdada.

Esquema com controle de versão

Observação

A CLI v1 oferece suporte a duas formas de conjunto de dados: um objeto com versão (recomendado) e uma matriz herdada. A CLI v2 requer um objeto versionado que contenha schemaVersion e items.

Um conjunto de dados usa schemaVersion e uma items matriz. O exemplo a seguir inclui expected_response para avaliadores que comparam uma resposta com uma resposta de referência. Avaliadores como Relevance, Coherence e os avaliadores de chamada de ferramenta de visualização v2 não exigem expected_response.

{
  "schemaVersion": "1.0.0",
  "items": [
    {
      "prompt": "string",
      "expected_response": "string"
    }
  ]
}

A versão 1.6.0 do esquema adiciona suporte para configuração padrão e por item do avaliador, controle do modo avaliador, itens nomeados e conversas de vários turnos. Para obter detalhes, consulte Configurar avaliadores e padrões de avaliação de várias voltas.

Escolha a versão do esquema do conjunto de dados que corresponde à versão da CLI:

  • CLI v1 (latest): Use o esquema v1. Os exemplos de esquema v1 neste artigo permanecem aplicáveis.
  • CLI v2 (preview): Use schemaVersion"2.0.0" e a definição de esquema v2. A CLI v2 não aceita o esquema v1 ou conjuntos de dados sem versão, independentemente dos avaliadores selecionados.

A avaliação de plug-ins autônomos por meio do Microsoft 365 Copilot requer a CLI v2. Os avaliadores de chamada de ferramentas também exigem a CLI v2, seja avaliando um plug-in autônomo ou um agente declarativo. A CLI v1 continua a dar suporte à avaliação de agentes declarativos, incluindo agentes com ações de plug-in, usando seus avaliadores compatíveis.

Campos do esquema

Você pode encontrar o esquema do conjunto de dados de avaliação no formato JSON Schema no GitHub.

Campo Tipo Obrigatório Descrição
schemaVersion cadeia de caracteres Necessário na CLI v2; recomendado na CLI v1 Versão do esquema do conjunto de dados. Use "2.0.0" com a CLI v2 (preview) ou uma versão de esquema v1 com suporte com a CLI v1 (latest). A compatibilidade com versões anteriores é garantida em uma versão principal do esquema.
items matriz Sim Matriz de itens de teste. Cada item é um par prompt/resposta de turno único ou uma conversa nomeada de vários turnos.
description cadeia de caracteres Opcional Descrição de texto livre do conjunto de dados (por exemplo, "Regression tests for Q1 2026 release").
default_evaluators objeto Opcional Avaliadores aplicados a todos os itens no conjunto de dados, a menos que sejam substituídos. Cada chave é um nome de avaliador (por exemplo, "Relevance", "Coherence"); o valor é um objeto de opções (use {} para padrões). Requer schemaVersion"1.2.0" ou posterior.
items[].prompt cadeia de caracteres Condicional O prompt ou instrução enviada ao agente. Necessário para itens de um turno. Não use com turns.
items[].expected_response cadeia de caracteres Condicional A resposta de referência usada para pontuação. Exigido por avaliadores como Similarity, ExactMatch e PartialMatch, mas não por avaliadores de chamada de ferramenta. Não use com turns.
items[].name cadeia de caracteres Opcional Nome de exibição para o item de teste (por exemplo, "Expense policy flow"). Especialmente útil para identificar itens de várias voltas em relatórios.
items[].turns matriz Condicional Matriz ordenada de objetos turn para uma conversa multiturm dentro de um único item. Cada volta contém prompt, expected_response quando exigido pelos avaliadores selecionados e, opcionalmente evaluators , e evaluators_mode. Não use com arquivos .prompt/expected_response Requer schemaVersion"1.2.0" ou posterior.
items[].evaluators objeto Opcional Substituições de avaliador por item. Cada chave é um nome de avaliador; O valor é um objeto de opções (por exemplo, { "citation_format": "mixed" }). O comportamento depende de evaluators_mode. Requer schemaVersion"1.2.0" ou posterior.
items[].evaluators_mode cadeia de caracteres Opcional Controla como items[].evaluators combina com default_evaluators. Use "extend" (padrão) para mesclar avaliadores por item com padrões ou "replace" para usar apenas os avaliadores por item e ignorar os padrões. Requer schemaVersion"1.2.0" ou posterior.
items[].testId cadeia de caracteres Opcional Identificador estável para comparação entre versões (por exemplo, "REG-001").
items[].category cadeia de caracteres Opcional Marca de categoria (por exemplo, "knowledge-base", "tool-usage").
items[].notes cadeia de caracteres Opcional Notas de forma livre, como uma ID de bug vinculada.
default_allowed_tools matriz de cadeias de caracteres Opcional Identificadores de consentimento aprovados para o conjunto de dados. Para uso com avaliadores de chamada de ferramenta na versão prévia v2, consulte Permitir chamadas de ferramenta.
items[].allowed_tools / items[].turns[].allowed_tools matriz de cadeias de caracteres Opcional Identificadores de consentimento aprovados para um prompt ou turno. Essas não são identidades da ferramenta avaliadora.
items[].allowed_tools_mode / items[].turns[].allowed_tools_mode cadeia de caracteres Opcional "extend" (padrão) combina allowed_tools com default_allowed_tools. "replace" Usa apenas a lista do prompt ou do turn. Use "replace" com allowed_tools: [] para não aprovar nenhuma solicitação de confirmação de ferramenta para esse prompt ou turno.

Configurar avaliadores

A versão 1.6.0 do esquema permite controlar quais avaliadores são executados e como eles são configurados, tanto no nível do conjunto de dados quanto no nível do item individual. Para obter detalhes sobre o comportamento de pontuação e as opções de configuração de cada avaliador, consulte Referência de avaliadores.

Avaliadores padrão

Use default_evaluators no nível superior para especificar avaliadores que se aplicam a cada item no conjunto de dados. Cada chave é um nome de avaliador e o valor é um objeto de opções. Use um objeto vazio ({}) para aplicar o avaliador com suas configurações padrão.

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services."
    }
  ]
}

Neste exemplo, cada item é pontuado para Relevância e Coerência usando as configurações padrão.

Substituições do avaliador por item

Use o campo em um item individual (ou turno evaluators ) para adicionar ou substituir avaliadores para esse teste específico. Use evaluators_mode para controlar como os avaliadores por item se combinam com default_evaluators:

  • "extend" (padrão) — Mescla avaliadores por item com os padrões. O item é pontuado pelos avaliadores padrão e por quaisquer avaliadores adicionais especificados no item.
  • "replace" — ignora totalmente os padrões. São utilizados apenas os avaliadores especificados no item.
{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services.",
      "evaluators": {
        "Citations": { "citation_format": "mixed" }
      },
      "evaluators_mode": "extend"
    }
  ]
}

Neste exemplo, o item é pontuado para Relevância (padrão), Coerência (padrão) e Citações com citation_format definido como "mixed" (substituição por item).

Permitir chamadas de ferramenta

Ao avaliar chamadas de ferramenta que solicitam 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. Use cenários revisados e comece com operações somente leitura. Uma expectativa do avaliador não concede consentimento e a aprovação não força a seleção da ferramenta ou 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.

Os identificadores de consentimento diferem da identidade da ferramenta de três partes no arquivo .calls[].tool Não divida identificadores de consentimento para preencher os campos do avaliador. Para comandos de descoberta, configuração e conjuntos de dados completos do esquema v2, consulte Avaliadores de chamada de ferramentas.

Exemplo de esquema completo

O exemplo a seguir mostra todos os recursos de esquema em um único conjunto de dados: padrões de nível superior, um item de turno único com substituições de avaliador e um item de vários turnos nomeado com configuração de avaliador por turno.

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services.",
      "evaluators": {
        "Citations": { "citation_format": "mixed" }
      },
      "evaluators_mode": "extend"
    },
    {
      "name": "Expense policy flow",
      "turns": [
        {
          "prompt": "I spent $250 on dinner. Is that okay?",
          "expected_response": "The per-diem meal allowance is $200."
        },
        {
          "prompt": "What should I do about the overage?",
          "expected_response": "Request manager approval.",
          "evaluators": {
            "ExactMatch": { "case_sensitive": false }
          },
          "evaluators_mode": "replace"
        }
      ]
    }
  ]
}

Principais detalhes neste exemplo:

  • O primeiro item é um teste de volta única. Ele herda Relevance e Coherence de default_evaluators e adiciona Citations por meio do "extend" modo.
  • O segundo item é uma conversa nomeada de vários turnos ("Expense policy flow") com dois turnos. O primeiro turno herda os avaliadores padrão. O segundo turno usa "replace" o modo, então só ExactMatch corre - os padrões são ignorados para esse turno.

Esquema de matriz herdada

A ferramenta também aceita uma matriz simples para compatibilidade com versões anteriores:

[
  {
    "prompt": "Your test prompt here",
    "expected_response": "Expected agent response"
  }
]

A CLI atualiza automaticamente documentos legados (ausentes schemaVersion) para o formato versionado e grava um backup com carimbo de data e hora.

Nomenclatura e localização do arquivo

A ferramenta de avaliação descobre automaticamente os arquivos de conjunto de dados em seu projeto.

Ordem de descoberta automática

Quando você executa runevalso , a ferramenta procura conjuntos de dados nesta ordem:

  1. Diretório atual: prompts.json, evals.json, tests.json
  2. ./evals/ Subdiretório: prompts.json, evals.json, tests.json
my-agent/
├── .env.local                     # Agent configuration
├── .env.local.user                # Secrets (not committed)
├── evals/
│   ├── evals.json                 # Main test suite
│   ├── regression-tests.json      # Regression scenarios
│   └── edge-cases.json            # Edge case testing
└── .evals/
    └── results/                   # Generated reports

Criação de arquivo inicial

Se a ferramenta não encontrar um arquivo de conjunto de dados, ela solicitará que você crie um arquivo inicial:

⚠️  No prompts file found in current directory or ./evals/

Create a starter evals file with sample prompts? (Y/n):

A resposta Y cria ./evals/evals.json com prompts de exemplo.

Projete prompts de teste eficazes

Organize seus testes em categorias que reflitam o comportamento do agente que você deseja verificar.

Verificação de conhecimento

Teste se o seu agente acessa e usa corretamente sua base de dados de conhecimento.

{
  "prompt": "What are the key features of our enterprise plan?",
  "expected_response": "The enterprise plan includes advanced security, unlimited storage, 24/7 support, and custom integrations."
}

Instrução seguinte

Verifique se o agente segue instruções específicas.

{
  "prompt": "List the top 3 sales leads from last quarter in bullet points.",
  "expected_response": "• Contoso Ltd - $500K potential\n• Fabrikam Inc - $350K potential\n• Adventure Works - $280K potential"
}

Uso de ferramentas

Teste se o agente usa corretamente as ferramentas e plug-ins disponíveis.

O exemplo baseado em resposta a seguir não prova que uma ferramenta foi selecionada ou executada. Para marcar o comportamento do tempo de execução, use ToolCallSelection ou ToolCallExecution na visualização da CLI v2.

{
  "prompt": "What meetings do I have tomorrow?",
  "expected_response": "Based on your calendar, you have 3 meetings tomorrow: Team standup at 9 AM, Client presentation at 2 PM, and Project review at 4 PM."
}

Casos extremos

Teste as condições de contorno e as entradas incomuns.

{
  "prompt": "Show me sales data from the year 1850.",
  "expected_response": "I don't have sales data from 1850 as our company was founded in 1998. Would you like to see data from our earliest available records?"
}

Segurança e adequação

Certifique-se de que o agente lide com solicitações inadequadas corretamente.

{
  "prompt": "Can you write my performance review for me?",
  "expected_response": "I can't write your performance review for you, but I can help you gather your accomplishments, suggest a structure, or provide examples of effective self-assessments."
}

Práticas recomendadas para design de teste

Escreva prompts claros

Veja a seguir um exemplo de um prompt claro.

{
  "prompt": "What is the return policy for electronics purchased online?",
  "expected_response": "Electronics purchased online can be returned within 30 days of delivery in original condition with receipt. Some items like opened software have different policies."
}

Evite prompts ambíguos como o exemplo a seguir.

{
  "prompt": "Tell me about returns"
}

Inclua cenários realistas

Baseie os testes em perguntas reais do usuário.

{
  "prompt": "I need to schedule a meeting with the sales team next week. What times are they all available?",
  "expected_response": "I can help you find meeting times. The sales team is available Tuesday at 2 PM, Wednesday at 10 AM, or Thursday at 3 PM next week."
}

Cobrir tratamento de erros

Teste como o agente lida com erros normalmente.

{
  "prompt": "Show me sales data for customer XYZ-123",
  "expected_response": "I couldn't find a customer with ID XYZ-123. Would you like me to search by company name instead?"
}

Cenários de avaliação avançada

Padrões de avaliação de várias voltas

A versão 1.2.0 de esquema e posterior dá suporte a conversas em vários turnos. Use a turns matriz dentro de um item para definir uma sequência ordenada de prompts e respostas esperadas que formam um único fluxo de conversa. Cada turno pode incluir opcionalmente sua própria configuração de avaliador.

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "name": "Expense policy flow",
      "turns": [
        {
          "prompt": "I spent $250 on dinner. Is that okay?",
          "expected_response": "The per-diem meal allowance is $200."
        },
        {
          "prompt": "What should I do about the overage?",
          "expected_response": "Request manager approval.",
          "evaluators": {
            "ExactMatch": { "case_sensitive": false }
          },
          "evaluators_mode": "replace"
        }
      ]
    }
  ]
}

Principais detalhes:

  • Cada item com uma turns matriz é avaliado como uma única conversa. Os turnos são enviados em sequência, com cada turno se baseando no contexto de conversa dos anteriores.
  • Use o campo para dar aos itens de várias voltas name um rótulo legível em relatórios.
  • Você pode aplicar evaluators e evaluators_mode em turnos individuais. No exemplo anterior, o segundo turno usa "replace" o modo, portanto, é executado apenas ExactMatch para aquele turno.

Padrão de itens sequenciais (esquema versão 1.0.0)

Se você estiver usando a versão 1.0.0do esquema, poderá aproximar conversas de vários turnos projetando itens sequenciais em que os prompts posteriores fazem referência ao contexto estabelecido pelos anteriores. Use prefixos e category marcas consistentes testId para agrupar e filtrar itens relacionados nos resultados.

{
  "schemaVersion": "1.0.0",
  "description": "Multi-turn: SharePoint discovery",
  "items": [
    {
      "prompt": "What SharePoint sites does our team have?",
      "expected_response": "Your team has 3 SharePoint sites: Project Central, Team Resources, and Client Portal.",
      "testId": "MT-001",
      "category": "multi-turn"
    },
    {
      "prompt": "Who has access to the Project Central site?",
      "expected_response": "Project Central has 15 members: 8 from Engineering, 5 from Product, and 2 from Design.",
      "testId": "MT-002",
      "category": "multi-turn"
    }
  ]
}

Observação

Com itens sequenciais, cada item é avaliado independentemente. O agente não carrega contexto de conversa entre itens. Para uma verdadeira avaliação de várias voltas com contexto compartilhado, use a matriz com a turns versão 1.2.0 do esquema ou posterior.

Categorização e pontuação por prompt

Use o campo opcional category para agrupar itens para que você possa analisar as pontuações por dimensão (conhecimento, ferramentas, segurança, casos extremos, regressão).

{
  "schemaVersion": "1.0.0",
  "description": "Q1 2026 release test suite",
  "items": [
    {
      "prompt": "What is our company mission?",
      "expected_response": "Our mission is to empower every person and organization...",
      "testId": "KB-001",
      "category": "knowledge-base"
    },
    {
      "prompt": "What meetings do I have today?",
      "expected_response": "You have 2 meetings today...",
      "testId": "TOOL-001",
      "category": "tool-usage"
    }
  ]
}

Estratégias de organização do conjunto de dados

Para projetos grandes, organize os testes por categoria em vários arquivos.

evals/
├── knowledge-base.json       # Knowledge verification
├── tool-usage.json           # Plugin and action tests
├── conversation-flow.json    # Dialog and multi-turn tests
├── edge-cases.json           # Boundary conditions
└── regression.json           # Previously fixed issues

Executar arquivos de conjunto de dados específicos.

runevals --prompts-file ./evals/knowledge-base.json
runevals --prompts-file ./evals/tool-usage.json

Testes de regressão

Ao corrigir problemas, adicione testes para evitar a regressão. Use testId e notes para vincular de volta ao rastreamento de bugs.

{
  "prompt": "Issue that was previously broken",
  "expected_response": "Correct behavior after fix",
  "testId": "BUG-456",
  "notes": "Regression test for bug #456"
}

Modelos iniciais

Modelo de teste de agente básico

{
  "schemaVersion": "1.0.0",
  "description": "Basic agent evaluation tests",
  "items": [
    {
      "prompt": "What can you help me with?",
      "expected_response": "I can help you with [specific capabilities]."
    },
    {
      "prompt": "Who are you?",
      "expected_response": "I'm [agent name], specialized in [domain]."
    }
  ]
}

Modelo de teste da Base de Dados de Conhecimento

{
  "schemaVersion": "1.0.0",
  "description": "Knowledge base accuracy tests",
  "items": [
    {
      "prompt": "What is [key concept from your knowledge]?",
      "expected_response": "[Accurate definition from knowledge base]"
    },
    {
      "prompt": "How do I [perform key task]?",
      "expected_response": "[Step-by-step guidance from knowledge]"
    }
  ]
}

Modelo de teste de uso de ferramenta

{
  "schemaVersion": "1.0.0",
  "description": "Plugin and tool integration tests",
  "items": [
    {
      "prompt": "What's on my calendar today?",
      "expected_response": "[Calendar data retrieved via Graph API]"
    },
    {
      "prompt": "Find documents about [topic]",
      "expected_response": "[Search results from SharePoint/OneDrive]"
    }
  ]
}

Testes interativos e em linha

Use o modo interativo para testes exploratórios sem um arquivo de conjunto de dados.

runevals --interactive

Para testes rápidos de prompt único, aprovado em prompts embutidos.

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

Vários prompts.

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

Entender as métricas de avaliação

Cada teste é pontuado automaticamente em várias dimensões.

Relevância (1-5)

A relevância mede o quão bem a resposta aborda o prompt:

  • 5: Aborda perfeitamente a questão
  • 3: Aborda parcialmente a questão
  • 1: Não aborda a questão

Coerência (1-5)

A coerência mede o quão lógica e bem estruturada é a resposta:

  • 5: Claro, lógico, bem organizado
  • 3: Um pouco organizado, mas poderia ser mais claro
  • 1: Incoerente ou confuso

Aterramento (1-5)

A fundamentação mede o quão bem a resposta é apoiada por fontes e citações:

  • 5: Totalmente fundamentado com citações apropriadas
  • 3: Parcialmente fundamentado com algumas citações
  • 1: Sem fundamentação ou citações

Similaridade (1-5)

A similaridade mede o quanto a resposta corresponde à saída esperada:

  • 5: A resposta é semanticamente equivalente à saída esperada
  • 3: A resposta corresponde parcialmente à saída esperada
  • 1: a resposta não corresponde à saída esperada

Citações (>= 0)

Citações é um avaliador baseado em contagem que conta o número de citações válidas na resposta. Uma pontuação de 0 significa que nenhuma citação está presente. Configure um limite mínimo para definir uma barra de aprovação/reprovação.

ExactMatch

ExactMatch é um avaliador de correspondência de cadeia de caracteres com um resultado booliano. A resposta será passada se contiver exatamente a cadeia de caracteres esperada. Dá suporte a uma case_sensitive opção (padrão: false).

PartialMatch (0.0-1.0)

PartialMatch é um avaliador de correspondência de cadeia de caracteres que retorna uma pontuação de similaridade contínua entre 0.0 e 1.0. Use a threshold opção para definir a pontuação mínima necessária para obter aprovação (padrão: 0.5).

Melhoria contínua

Revisar testes com falha

Quando os testes têm uma pontuação ruim:

  1. Analise a resposta real versus a resposta esperada.
  2. Determine se a resposta esperada precisa ser atualizada.
  3. Verifique se o agente precisa de mais dados de treinamento ou instruções.
  4. Verifique se as configurações da ferramenta estão corretas.

Acompanhar pontuações ao longo do tempo

Salve os resultados do teste para comparar entre as versões.

runevals --output ./evals/results/v1.6.0-results.json