Avaliações

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.

Conjuntos de avaliações são agrupamentos lógicos de avaliações e avaliadores.

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

Antes de criar avaliações em escala, você pode primeiro testar seu agente em cenários únicos para ver se o agente é capaz de realizar sua tarefa e se a saída está correta ou não. Se seu agente estiver gerando a saída correta, você pode criar avaliações a partir das execuções corretas. Se seu agente não estiver gerando a saída correta, você pode corrigir a saída e criar uma avaliação com a saída esperada, você pode criar avaliações a partir do zero.

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:

   1. 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.
   2. 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 e ferramentas 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 Definir 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.

Criar avaliações a partir de rastreamentos de runtime.

Você pode criar avaliações de agentes diretamente de rastreamentos de runtime, permitindo que você transforme o feedback de produção em casos de teste acionáveis para melhorias no tempo de projeto.

1. Primeiro, execute seu agente.
2. No Orchestrator, acesse Automações > Trabalhos e abra os rastreamentos de trabalhos para a execução do agente. Ou acesse a página Gerenciamento de instâncias de agentes para visualizar traços para execuções de agentes.
3. Forneça feedback para as execuções do agente:
   • Para cada rastreamento, selecione o ícone de polegar para cima ou polegar para baixo.
   • Adicione um comentário para tornar a avaliação acionável.
4. Busque rastreamentos de runtime na definição do agente:
   • Volte para o seu agente no Studio Web e navegue até Avaliações > Conjuntos de avaliação.
   • No botão Criar, selecione Buscar rastreamentos de runtime para obter rastreamentos que receberam feedback.
5. Adicione rastreamentos para um conjunto de avaliação:
   • Dos rastreamentos obtidos, selecione Adicionar ao conjunto de avaliações.
   • Edite a entrada e a saída esperada, se necessário.
   • Salve o rastreamento para o conjunto de avaliação escolhido.
6. Salve o rastreamento para o conjunto de avaliação escolhido.

Depois de adicionados, os rastreamentos de runtime são claramente rotulados como execuções de runtime dentro do conjunto de avaliação, facilitando sua distinção das execuções de teste offline. Esses rastreamentos também atualizam automaticamente a pontuação geral da avaliação do agente, dando a você Visibilidade imediata sobre como o feedback do mundo real está melhorando o desempenho do agente.

Geração de avaliações

Você também pode criar conjuntos de avaliação com simulações. Gere novos conjuntos de avaliação (ou adicione aos existentes) usando entradas e ferramentas simuladas.

1. Selecione Criar.
2. Selecione Gerar novo conjunto de avaliação.

   Você pode deixar o LLM gerar automaticamente o conjunto de avaliação com base em seu agente existente, suas execuções de design, argumentos ou fornecer prompts para direcioná-lo para exemplos específicos.

Para obter detalhes, consulte Configuração de simulações nas avaliações.

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. Selecione Criar novo:
2. Selecione o tipo de avaliador:
   1. LLM como um juiz: Similaridade Semântica – Crie seu próprio avaliador baseado em LLM.
   2. Correspondência exata – Verifica se a saída do agente corresponde à saída esperada.
   3. Similaridade do JSON – Verifica se duas estruturas ou valores do JSON são semelhantes.
   4. Avaliador de trajetória – Usa IA para julgar o agente baseado no histórico de execução e o comportamento esperado.
3. Selecione Continuar.
4. Configurar o avaliador:

   1. Adicione um nome e uma descrição relevantes.

   2. Selecionar os Campos de saída de destino:
      • Segmentação de nível raiz (* Todos): avalia toda a saída.
      • Segmentação específica para campo: avalia campos específicos de primeiro nível.Use o menu suspenso para selecionar um campo. Os campos de saída listados são herdados dos argumentos de saída que você definiu para o prompt do sistema.
   3. Adicione uma solicitação (apenas para o avaliador baseado em LLM).

Escolhendo o tipo de avaliador

Se você não souber qual tipo de avaliador se adequa às suas necessidades, consulte as seguintes recomendações:

• LLM como juiz:
  • 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 ou similaridade do 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.

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

Observação: essa funcionalidade está disponível como 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.

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 visualização 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

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

Uma saída bem estruturada torna as avaliações mais confiáveis. É por isso que é bom ter saídas estruturadas — garante consistência e facilita as comparações.

Aqui está um exemplo de uma solicitação predefinida que avalia toda a saída:

Exemplo de solicitação

Como avaliador especializado, analise a similaridade semântica desses conteúdos JSON para determinar uma pontuação de 0 a 100. Concentre-se na comparação do significado e da equivalência contextual dos campos correspondentes, levando em consideração expressões alternativas válidas, sinônimos e variações razoáveis no idioma, mantendo altos padrões de precisão e integridade. Forneça sua pontuação com a justificativa, explicando de forma breve e concisa por que você deu essa pontuação.

Saída esperada: {{ExpectedOutput}}

ActualOutput: {{ActualOutput}}

Número de avaliações

A Pontuação do agente considera mais de 30 avaliações como um bom parâmetro de referência.

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.