Automatizar avaliações de agentes com a API Power Platform

Note

As funcionalidades deste artigo são suportadas pela estrutura padrão, que utiliza as opções de faturação descritas em Licenciamento para agentes suportados pela estrutura padrão. Aprenda a aceder a funcionalidades padrão nos agentes e fluxos de agentes padrão do Access.

Copilot Studio fornece aos criadores ferramentas para avaliar continuamente o desempenho do agente, executando testes automatizados contra conjuntos de testes predefinidos usando a API REST da Power Platform. Ao usar a API REST, pode ativar programaticamente avaliações de agentes como parte dos seus fluxos de trabalho de desenvolvimento, como durante atualizações de agentes, validação de lançamentos ou testes de regressão.

Automatizar avaliações ajuda-o a:

  • Valide a qualidade do agente após efetuar alterações.
  • Faz verificações recorrentes de desempenho contra agentes de produção ou de encenação.
  • Integrar testes de agentes em pipelines de CI/CD.
  • Detetar regressões no comportamento dos agentes numa fase inicial do ciclo de desenvolvimento.

Pré-requisitos

  • Tem o ID do Bot e o ID do Ambiente para o agente de destino.
  • Um conjunto de testes criado no Copilot Studio para o seu agente alvo.
  • Um token de acesso de utilizador emitido pelo Microsoft Entra ID (OAuth 2.0). Para obter o token, consulte Autenticação.
    • Adquira o token de acesso utilizando o ID do cliente de um registo de aplicação que tenha o âmbito apropriado concedido pela API da Power Platform.

Visão geral para execução de avaliações utilizando a API REST

Para realizar uma avaliação utilizando a API do Power Platform, siga estes passos gerais:

  1. Preencha os pré-requisitos.
  2. Encontra e recupera o ID do conjunto de teste que queres usar.
  3. Faz a avaliação.
  4. Recupere os resultados usando o ID da execução de avaliação.

Quando o pedido é bem-sucedido, a avaliação decorre de forma assíncrona e produz resultados que pode analisar no Copilot Studio.

Operações de API para automatização de avaliações

O Copilot Studio suporta operações de API REST que pode usar para ativar programáticamente avaliações contra o seu agente usando um conjunto de testes existente.

Para obter mais informações sobre como e quando usar a API da Power Platform, consulte:

Obtenha conjuntos de teste de agentes

  • Ponto final:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01
  • Propósito: Recuperar um array dos IDs do conjunto de teste e outros detalhes de um agente específico.
  • Resposta: Devolve uma lista chamada value conjuntos de teste com a seguinte informação:
    • auditInfo: Timestamps e IDs de utilizador para criar e modificar cada conjunto de testes
    • displayName: O nome do conjunto de testes.
    • id: O identificador do conjunto de teste. Utilize iniciar uma avaliação de agente para escolher qual conjunto de testes utilizar.
    • description: A descrição do conjunto de testes.
    • state: O estado do conjunto de testes. Um conjunto de teste utilizável tem o estado Active.
    • totalTestCases: O número de casos de teste dentro do conjunto de teste.

Saiba mais em Conjuntos de Teste de Avaliação do Criador de Listas.

Obtenha detalhes do conjunto de testes dos agentes

  • Ponto final:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}?api-version=2024-10-01
  • Propósito: Recuperar detalhes para um conjunto de teste específico, usando o ID do conjunto de teste.
  • Resposta: Devolve a informação de um item no array de resposta dos conjuntos de teste do agente.

Saiba mais em Conjuntos de Teste de Avaliação do Criador de Listas.

Inicie uma avaliação de agente

  • Ponto final:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}/run?api-version=2024-10-01
  • Propósito: Executar uma avaliação para um conjunto de teste usando o conjunto idde teste . Também pode incluir um perfil de utilizador para autenticar ligações durante a execução de avaliação. Use mcsConnectionId para especificar o perfil do utilizador. Se não adicionares an mcsConnectionId à tua chamada, a avaliação é executada sem autenticação.
  • Resposta: Retorna a seguinte informação:
    • runId: O ID para a execução da avaliação. Use este ID para obter detalhes da avaliação.
    • lastUpdatedAt: Quando o estado da corrida foi atualizado pela última vez.
    • executionState: O estado da execução enquanto a avaliação está em curso.
    • state: Estado atual da corrida.
    • totalTestCases: Número total de casos de teste no conjunto de testes utilizado para a avaliação.
    • testCasesProcessed: Total de casos de teste avaliados até à última atualização.

Saiba mais no Conjunto de Teste de Avaliação Run Maker.

Faça testes com agentes

  • Ponto final:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • Propósito: Recuperar um array de todas as execuções anteriores.
  • Resposta: Cada item no array inclui os mesmos valores encontrados nos detalhes do teste Get agent.

Saiba mais em Testes de Avaliação do Criador de Listas.

Obtenha detalhes do teste do agente

  • Ponto final:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{TestRunId}?api-version=2024-10-01
  • Objetivo: Recolha os detalhes de uma avaliação utilizando a runId sua execução de avaliação alvo.
  • Resposta: Retorna a seguinte informação:
    • id: O ID para a execução da avaliação. Use este ID para obter detalhes da avaliação.
    • environmentId: O identificador do ambiente do seu agente.
    • cdsBotId: A identificação do agente-alvo.
    • ownerId: O ID do utilizador que iniciou a execução de avaliação.
    • testSetId: O ID do conjunto de teste utilizado para a avaliação.
    • state: O estado de progresso da avaliação.
    • startTime: Quando a avaliação começou.
    • endTime: Quando a avaliação terminou, se terminou.
    • name: Nome da avaliação.
    • totalTestCases: Total de casos de teste no conjunto de testes.
    • mcsConnectionId: O ID da conexão para a conexão do Copilot Studio do perfil de utilizador utilizado para a execução da avaliação. null se não houver perfil de utilizador ligado.
    • testCasesResults: A lista de casos de teste na execução da avaliação. Inclui:
      • testCaseId: A identificação do caso de teste.
      • state: O estado de conclusão do caso de teste.
      • metricsResults: Os detalhes e resultados de cada método de teste utilizado no cenário de teste. Inclui o seguinte:
        • type: O método de teste.
        • result: O resultado final deste caso de teste. Inclui o seguinte:
          • data: Os detalhes do resultado. Os valores exatos dependem do método de teste. Saiba mais na documentação da API do Power Platform. Para um teste geral de qualidade , a resposta inclui o seguinte:
            • abstention: Se o agente respondeu à questão.
            • relevance: Se a resposta era relevante.
            • completeness: Se a resposta está completa.
        • status: O estado do caso de teste.
        • errorReason: Se ocorreu um erro, a causa do erro.
        • aiResultReason: A explicação da IA do resultado do caso de teste.

Saiba mais em Get Maker Evaluation Test Run.

Use um ID do Microsoft Studio Connector para avaliações

Para Start an agent evaluation, podes opcionalmente adicionar um ID Microsoft Studio Connector à chamada como perfil de utilizador para a avaliação. Para encontrar o seu mcsConnectionId:

  1. Vá para Power Automate.
  2. Abre a página de Ligações .
  3. Seleciona a ligação Microsoft Copilot Studio.
  4. Copie a mcsConnectionId partir da URL: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details
  • Last updated on