Avaliações

Configure avaliações e avaliadores para pontuar se seu agente produz a saída esperada e, em seguida, execute-os para medir sua precisão e confiabilidade.

Sobre avaliações

Quando você está criando um agente, o objetivo é torná-lo confiável — algo em que você pode confiar para entregar resultados corretos de forma consistente.As avaliações ajudam você a entender se seu agente está fazendo um bom trabalho ou se precisa de melhorias.

Terminologia

Uma avaliação é um par entre uma entrada e uma asserção — ou avaliador — feita na saída. O avaliador é uma condição ou regra definida usada para avaliar se a saída do agente atende à saída esperada ou à trajetória esperada.

An evaluation set groups one or more evaluations and is mapped to one or more evaluators.

Resultados de avaliação são rastreamentos para execuções de avaliação concluídas que avaliam o desempenho de um agente. Durante essas execuções, a precisão, a eficiência e a capacidade de tomada de decisão do agente são medidas e pontuadas com base no desempenho do agente.

A pontuação da avaliação determina o desempenho do agente com base nas asserções em uma avaliação específica. A pontuação se dá em uma escala de 0 a 100. Se você tiver falhado nas execuções de avaliação, você deve diagnosticar a causa, fazer o debug e executá-las novamente.

Criando avaliações

Before you create evaluations at scale, you can first test your agent on one-off scenarios to see whether it performs its task and produces correct output. Based on the results, you can create evaluations in a few ways:

• If the agent generates the correct output, create evaluations from the correct runs.
• If the agent doesn't generate the correct output, fix the output and create an evaluation with the expected output.
• Alternatively, create evaluations from scratch.

Criar avaliações a partir de execuções de teste

1. Após projetar seu agente, selecione Configuração de debug.
2. Na janela Configuração de debug, confirme os recursos usados na solução e:
   • Forneça a entrada para a execução do teste:
     • Forneça entradas manualmente digitando o conteúdo ou
     • Simular entradas: use um LLM para gerar entradas para os argumentos do seu agente. Você pode permitir que o LLM gere entradas automaticamente ou fornecer prompts para orientá-lo para exemplos específicos.
   • Configurar se você deseja testar com ferramentas reais ou ter uma, mais ou todas as suas ferramentas simuladas.
     • Ferramentas de simulação: use um LLM para simular uma ou mais ferramentas de agente. Descreva como cada ferramenta deve responder e simule conjuntos de ferramentas parciais ou completas dos quais seu agente depende.
3. Selecione Salvar e Debug. Os resultados são exibidos no painel inferior Trilha de execução. Os indicadores estão disponíveis para mostrar quando seu agente está sendo executado com dados reais ou simulados.
4. Se a saída estiver correta, selecione o botão Adicionar ao conjunto de avaliação. Se a saída não estiver correta, você pode:
   • Refinar a solicitação: ajuste a solicitação e teste o agente até que a saída esteja correta.
   • Crie avaliações a partir de saídas incorretas: gere avaliações com base nas saídas incorretas e edite-as manualmente para se alinhar ao resultado esperado.
5. As execuções de Teste são listadas na janela Adicionar para conjunto de avaliação. Selecione Adicionar para conjunto padrão para qualquer execução que você queira adicionar a uma avaliação. Se você já criou um conjunto de avaliação, você pode selecioná-lo na lista suspensa disponível.
6. Em seguida, acesse o painel de Conjuntos de avaliação. Três opções estão disponível:
   1. Use o conjunto de avaliações pré-criado para organizar para suas avaliações.
   2. Gere um novo conjunto com entradas simuladas.
   3. Adicione avaliações em conjuntos existentes com dados reais e simulados.
7. Selecione Avaliar conjunto para executar as avaliações. Você também pode selecionar avaliações específicas do conjunto que você gostaria de avaliar.
8. Acesse a aba Resultados para exibir a pontuação e os detalhes da avaliação.

Criando avaliações do zero

1. Após projetar seu agente, acesse a aba Conjuntos de avaliação e selecione Criar novo. Você também pode selecionar Importar para usar dados JSON existentes dos avaliações de outros agentes.
2. Adicione um nome relevante para o conjunto de avaliação.
3. Selecione Adicionar ao conjunto para criar novas avaliações. Para cada nova avaliação no conjunto:
   1. Adicione um nome.
   2. Adicione valores para os campos de Entrada (herdados dos argumentos de entrada definidos) e a Saída esperada.
   3. Selecione Salvar.
4. Em seguida, selecione Selecionar avaliadores para atribuir avaliadores ao conjunto de avaliação. Você pode atribuir um ou vários avaliadores a um conjunto.
5. Selecione Salvar mudanças.
6. De na página principal Conjuntos de avaliação, selecione Conjunto de avaliação para cada conjunto que você deseja executar.
7. Acesse a aba Resultados para exibir a pontuação e os detalhes da avaliação.

Geração de avaliações

Gere casos de avaliação para um conjunto de avaliações novo ou existente usando o gerador de avaliação.

1. Na página Conjuntos de avaliação, selecione Gerar para conjunto.
2. Na janela Gerador de avaliação, adicione contexto opcionalmente ou descreva os casos de avaliação que você deseja gerar. Você pode colar o conteúdo ou deixar o campo em branco para permitir que o sistema gere casos automaticamente.
3. Selecione Gerar avaliações. Listamos os casos de avaliação gerados, cada um com os seguintes campos: Nome, Instruções de simulação, Instruções de geração de entrada e Notas de comportamento esperado.
4. Opcionalmente, edite qualquer um dos campos diretamente na lista.
5. Selecione um ou mais casos de avaliação e, em seguida, selecione Adicionar para conjunto.

Avaliadores

Os avaliadores definem como as saídas do agente são pontuadas em relação ao comportamento ou resultados esperados. Ao adicionar um avaliador a um conjunto de avaliações, selecione o tipo de avaliador que melhor corresponde ao tipo de validação que você deseja realizar.

Ao adicionar ou editar um avaliador, as opções de configuração que você vê dependem da Categoria e do Tipo do avaliador que você selecionar.

Categorias de avaliador

Categoria de avaliador	Tipo de avaliador	Description
Determinista	Correspondência exata	Verifica se a saída do agente corresponde exatamente à saída esperada, sem variações em palavras ou formatação.
Determinista	Similaridade JSON	Compara a similaridade estrutural de objetos ou valores JSON em vez de exigir uma correspondência exata.
LLM-como-juiz	Similaridade semântica	Usa um modelo de linguagem para avaliar o quão próximo a saída do agente corresponde à saída esperada em significado e intenção.
Trajetória	Trajetória	Usa um modelo de linguagem para julgar o comportamento geral do agente com base em seu histórico de execução e comportamento esperado.

• Os avaliadores deterministas usam correspondências predefinidas, baseadas em regras, e sempre produzem resultados consistentes para as mesmas entradas. Eles não fazem uso de um modelo de Idioma.
• LLM como um juiz os avaliadores usam um modelo de linguagem para avaliar o significado, a fundamentação ou a relevância e pode tolerar variações razoáveis na linguagem.
• Os avaliadores de Trajetória usam um modelo de linguagem para avaliar o comportamento do agente em toda a execução, incluindo etapas intermediárias e uso de ferramentas.

Os avaliadores deterministas não incluem um campo de seleção de Modelo porque não usam LLMs. Os avaliadores LLM como juiz e Trajetória permitem que você escolha o modelo usado para avaliação.

Escolhendo o tipo de avaliador

Se você não tiver certeza de qual tipo de avaliador é mais adequado ao seu caso de uso, utilize a seguinte orientação para selecionar a opção mais apropriada com base no tipo de saída que você está validando e no nível de flexibilidade de que você precisa.

• LLM como juiz (similaridade semântica):
  • Recomendado como a abordagem padrão ao direcionar a saída raiz.
  • Fornece avaliação flexível de saídas complexas.
  • Pode avaliar qualidade e correção além da correspondência exata.
  • Mais bem utilizado ao avaliar raciocínio, respostas em linguagem natural ou saídas estruturadas complexas.
• Determinístico (correspondência exata, similaridade JSON):
  • Recomendado quando são esperadas correspondências exatas.
  • Mais eficaz quando os requisitos de saída são estritamente definidos.
  • Funciona com objetos complexos, mas é mais bem utilizado com:
    • Respostas booleanas (verdadeiro/falso)
    • Valores numéricos específicos
    • Correspondências exatas de strings
    • Matrizes de tipos primitivos.
• Trajetória:
  • Recomendado quando você precisa avaliar o comportamento geral do agente, em vez de apenas sua saída final.

Definição de avaliadores

Use o painel Avaliadores para criar e gerenciar seus avaliadores. Por padrão, cada agente tem um Avaliador padrão predefinido baseado em LLM.

Para criar seus próprios avaliadores:

1. No projeto do seu agente, selecione Avaliadores.
2. Selecione Criar novo:
3. Escolha seu tipo de avaliador preferido e selecione Continuar.
4. Configurar o avaliador:
   1. Forneça um nome e descrição relevantes.
   2. (Apenas avaliadores baseados em LLM e de trajetórias) Selecionar o Modelo para avaliação.
   3. Selecionar os Campos de saída de destino:
      • Segmentação no nível raiz (todos): avalia toda a saída.
      • Segmentação específica do campo: avalia campos de saída específicos de primeiro nível. Os campos disponíveis são herdados dos argumentos de saída definidos na solicitação do sistema.
   4. Adicione uma solicitação (necessária para avaliadores baseados em LLM e de trajetória) que defina como o avaliador deve pontuar a saída.

Configuração de simulações em avaliações

Observação:

Essa funcionalidade está disponível em pré-visualização.

As simulações aprimoram as avaliações do agente permitindo testes seguros, rápidos e econômicos por meio de ferramentas simuladas e comportamentos de escalonamento em vez de endpoints reais. Oferecem controle detalhado no nível de avaliação, permitindo que as equipes definam quais componentes simular e combinem execuções reais e simuladas dentro do mesmo conjunto de avaliação.

Essa flexibilidade é compatível com entradas fixas ou geradas e saída literal e classificação baseada no comportamento, melhorando a cobertura do teste, a reprodutibilidade e a capacidade de avaliar se os agentes se comportam conforme o esperado.

Para obter informações adicionais, consulte Configuração de simulações para ferramentas de agente Information.

Como configurar simulações de avaliação

Para configurar novos conjuntos de avaliação usando simulações, siga estas etapas:

1. Na aba Conjuntos de avaliação, selecione Criar e, em seguida, Gerar novo conjunto de avaliação.
2. Insira uma descrição dos casos de avaliação que você deseja gerar. Você pode fornecer contexto de alto nível, cenários específicos ou colar conteúdo relevante para orientar a geração. Se você deixar este campo em branco, os casos de avaliação ainda são gerados automaticamente para você.
3. Selecione Gerar avaliações. O Autopilot gera várias avaliações. Para cada avaliação você pode visualizar e editar as instruções de simulação, instruções de geração de entrada e as notas de comportamento esperado.
4. Selecione quais avaliações você deseja usar e, em seguida, selecione Adicionar conjunto.

Para configurar simulações para avaliações existentes, siga estas etapas:

1. Abra qualquer conjunto de avaliações e selecione Editar em qualquer avaliação. O painel Editar avaliação é exibido.
2. Na seção Organizar, defina ou gere dados de entrada usando valores manuais ou instruções de geração em tempo de execução. Se você definir os dados de entrada manualmente, você pode definir o campo Teste como Verdadeiro para indicar que é parte de um cenário de teste.
3. Na seção Agir, escolha se cada ferramenta deve simular o comportamento (simulado) ou executar chamadas reais e adicione instruções de simulação. A execução da ferramenta é a configuração padrão.
4. Na seção Afirmar, especifique se a avaliação é baseada na correspondência de saída ou na trajetória do agente e descreva o comportamento e a saída esperados.
5. Selecione Salvar para aplicar sua configuração.

Figura 1. Configuração de simulações de ferramentas em avaliações

Teste de configurações do modelo dentro de avaliações

Você pode usar conjuntos de avaliação para comparar diferentes configurações de modelos e entender como elas afetam o comportamento de seu agente. As avaliações permitem que você teste várias combinações de modelo/temperatura lado a lado, usando os mesmos cenários e expectativas de resultados. Isso ajuda você a identificar a configuração que fornece o equilíbrio certo entre precisão, velocidade e custo.

1. A partir do painel Explorer do Agent Builder, selecione Conjuntos de avaliação.

2. Selecione um conjunto de avaliação.

3. Selecione o ícone de engrenagem para abrir as Configurações de avaliação.

   

4. No painel de Propriedades do conjunto de avaliação, adicione várias combinações de temperatura e modelo. Por exemplo:

   • Temperatura 0,2, Modelo A
   • Temperatura 0,5, Modelo A
   • Temperatura 0,7, Modelo A
   • Temperatura 0,5, Modelo B

   Cada configuração cria uma execução de avaliação separada.

   

5. Selecione Conjunto de avaliação para executar todas as configurações. Após as execuções serem concluídas, abra a guia Resultados para compará-las.

   

Para obter detalhes, consulte Escolha do melhor modelo para seu agente.

Definir avaliações com entradas de arquivos

As avaliações de agente são compatíveis com entradas baseadas em arquivos. Se seu agente espera um argumento file, a interface gráfica de avaliação renderiza um seletor de arquivos dedicado, permitindo que você carregue ou reutilize arquivos para testes.

Para usar arquivos em avaliações:

1. Abra o agente e navegue até Conjuntos de avaliações.
2. Crie uma nova avaliação ou edite uma existente.
3. No painel Configuração de entrada, localize o campo de entrada do arquivo.
4. Carregue um novo arquivo ou selecione um entre os arquivos de avaliação disponíveis.
5. Salve a avaliação e execute o conjunto de avaliações.

O arquivo selecionado é passado para o agente da mesma forma que uma entrada de arquivo de runtime, garantindo um comportamento consistente entre avaliações e execuções de produção.

Trabalhando com avaliações

Onde trabalhar com avaliações

Você pode trabalhar com avaliações em dois lugares, dependendo do seu fluxo de trabalho:

• Painel inferior na tela de projeto – fornece acesso rápido a avaliações enquanto você está criando ou testando seu agente ativamente. O painel inclui:

  • Aba Histórico para visualização de execuções anteriores com rastreamentos completos e para adicioná-las diretamente a conjuntos de avaliação.
  • Aba Avaliações para ver seus conjuntos de avaliação, revisar pontuações recentes, aprofundar-se nos detalhes ou para executar novamente testes individualmente ou como um conjunto completo. Você também pode comparar saídas reais com saídas esperadas e atualizar avaliações com a saída real quando estiver correta.
  • Aba Trilha de execução para seguir os detalhes do rastreamento para a execução atual em tempo real. Para agentes de conversação, essa aba está disponível como Chat e fornece uma janela de chat interativa para testar o agente, ao mesmo tempo em que exibe a trilha de execução para cada troca de conversação.

• Aba Avaliações sob a definição do agente – fornece o espaço de trabalho de avaliação completa. A partir daqui, você pode criar e organizar conjuntos de avaliação, atribuir avaliadores, configurar entradas e saídas esperadas e executar avaliações em escala. Este é o melhor lugar para configurar cenários de avaliação estruturados e gerenciar ativos de avaliação ao longo do tempo.

O uso do painel inferior ajuda durante a iteração e a depuração do dia a dia, enquanto a aba Avaliações dedicada é mais adequada para o gerenciamento e a configuração de conjuntos de avaliação completa.

Estruturação de sua solicitação de avaliação

For LLM-as-a-judge evaluators (such as Semantic similarity), you provide a prompt that tells the model how to score the output. A well-structured, consistent output makes these evaluations more reliable and makes comparisons easier.

Exemplo de solicitação

The following prompt evaluates the entire output for semantic similarity:

As an expert evaluator, analyze the semantic similarity of these JSON contents to determine a score from 0-100. Focus on comparing the meaning and contextual equivalence of corresponding fields, accounting for alternative valid expressions, synonyms, and reasonable variations in language while maintaining high standards for accuracy and completeness. Provide your score with justification, explaining briefly and concisely why you gave that score.

Expected Output: {{ExpectedOutput}}
ActualOutput: {{ActualOutput}}

Número de avaliações

Para agentes simples, procure aproximadamente 30 avaliações em 1 a 3 conjuntos de avaliação. Para agentes mais complexos, recomendamos que você tenha pelo menos o dobro desse valor ou mais.

O número de avaliações depende de:

• Complexidade do agente
  • Número de parâmetros de entrada
  • Complexidade da estrutura de saída
  • Padrões de uso da ferramenta
  • Ramificações de decisão
• Entrada
  • Gama de entradas possíveis: tipos de dados, intervalos de valores, campos opcionais.
  • Casos extremos
• Padrões de uso
  • Casos de uso comum
  • Perfis diferentes
  • Cenários de erro

Conjuntos de avaliação

Agrupar avaliações em conjuntos ajuda a organizá-las melhor. Por exemplo, você pode ter:

• Um conjunto para avaliação de saída completa
• Outro para casos extremos
• Outro para lidar com erros ortográficos.

Princípios de cobertura

• Cobertura lógica: mapeie combinações de entrada, casos extremos e condições de limite.
• Gerenciamento de redundância: procure realizar 3 a 5 avaliações diferentes por caso logicamente equivalente.
• Priorize qualidade em vez de quantidade: mais avaliações nem sempre significam melhores resultados. Concentre-se em testes significativos.

Quando criar avaliações

Crie avaliações quando os argumentos estiverem estáveis ou concluídos. Isso também significa que seu caso de uso é estabelecido e a solicitação, as ferramentas e os contextos são finalizados. Se você modificar os argumentos, precisará ajustar suas avaliações de acordo.

Para minimizar o trabalho adicional, é melhor começar com agentes estáveis que tenham casos de uso bem definidos. Você pode exportar e importar conjuntos de avaliação entre agentes dentro da mesma organização ou entre organizações diferentes. Desde que o design de seu agente esteja concluído, você pode mover as avaliações conforme necessário sem ter que recriá-las do zero.

Revisão de resultados

Use Comparar instantâneos para entender o que mudou na configuração de seu agente entre duas execuções, por exemplo, após editar a solicitação do sistema, alternar modelos ou ajustar a temperatura.

Na guia Resultados, marque as caixas de seleção ao lado de duas execuções concluídas e, em seguida, selecione Comparar instantâneos. A visualização de comparação destaca as alterações na configuração do esquema, nas configurações de solicitação e na solicitação do sistema, com remoções em vermelho e adições em verde. Isso é útil ao depurar alterações de saída inesperadas, validar se uma revisão de solicitação teve o efeito pretendido ou rastrear quando uma mudança de comportamento foi introduzida.