Automatizar avaliações de agente com a API do Power Platform

Copilot Studio fornece aos fabricantes ferramentas para avaliar continuamente o desempenho do agente executando testes automatizados em conjuntos de teste predefinidos usando a API REST Power Platform. Usando a API REST, você pode disparar avaliações de agente programaticamente como parte de seus fluxos de trabalho de desenvolvimento, como durante atualizações de agente, validação de versão ou teste de regressão.

A automatização de avaliações ajuda você a:

  • Valide a qualidade do agente depois de fazer alterações.
  • Execute verificações de desempenho recorrentes em agentes de produção ou de homologação.
  • Integre o teste de agente em pipelines de CI/CD.
  • Detectar regressões no comportamento do agente no início do ciclo de vida de desenvolvimento.

Pré-requisitos

  • Você tem a ID do bot e a ID do ambiente para o agente de destino.
  • Um conjunto de teste criado no Copilot Studio para o agente de destino.
  • Um token de acesso do usuário emitido pelo Microsoft Entra ID (OAuth 2.0). Para obter o token, consulte Autenticação.
    • Adquira o token de acesso usando a ID do cliente de um registro de aplicativo que tenha o escopo apropriado concedido na API do Power Platform.

Visão geral da execução de avaliações usando a API REST

Para executar uma avaliação usando a API do Power Platform, siga estas etapas gerais:

  1. Conclua os pré-requisitos.
  2. Localize e recupere a ID do conjunto de testes do conjunto de testes que você deseja usar.
  3. Execute a avaliação.
  4. Recupere os resultados usando a ID da execução de avaliação.

Quando a solicitação for bem-sucedida, a avaliação será executada de forma assíncrona e produzirá resultados que você pode examinar em Copilot Studio.

Operações de API para automatizar avaliações

Copilot Studio dá suporte a operações de API REST que você pode usar para disparar avaliações programaticamente em seu agente usando um conjunto de testes existente.

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

Obter conjuntos de testes do agente

  • Ponto de extremidade:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01
  • Finalidade: recuperar uma matriz das IDs do conjunto de testes e outros detalhes para um agente específico.
  • Resposta: Retorna uma lista chamada value de conjuntos de teste com as seguintes informações:
    • auditInfo: carimbos de data/hora e IDs de usuário para criar e modificar cada conjunto de testes
    • displayName: o nome do conjunto de testes.
    • id: a ID do conjunto de testes. Use em Iniciar uma avaliação de agente para escolher qual conjunto de testes usar.
    • description: a descrição do conjunto de testes.
    • state: o status do conjunto de testes. Um conjunto de testes utilizável tem o status Active.
    • totalTestCases: o número de casos de teste dentro do conjunto de testagem.

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

Obter detalhes do conjunto de testes do agente

  • Ponto de extremidade:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}?api-version=2024-10-01
  • Finalidade: recuperar detalhes de um conjunto de testes específico, usando a ID do conjunto de testes.
  • Resposta: retorna as informações de um item na matriz de resposta Get agent test sets .

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

Iniciar uma avaliação do agente

  • Ponto de extremidade:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}/run?api-version=2024-10-01
  • Finalidade: executar uma avaliação para um conjunto de teste usando o id do conjunto de teste. Você também pode incluir um perfil de usuário para autenticar conexões durante a execução da avaliação. Use mcsConnectionId para especificar o perfil do usuário. Se você não adicionar um mcsConnectionId à sua chamada, a avaliação será executada sem autenticação.
  • Resposta: Retorna as seguintes informações:
    • runId: o identificador da execução de avaliação. Use essa ID para recuperar os detalhes da avaliação.
    • lastUpdatedAt: quando o status da execução foi atualizado pela última vez.
    • executionState: O estado da execução enquanto a avaliação está em andamento.
    • state: estado atual da execução.
    • totalTestCases: número total de casos de teste no conjunto de testes usado para a avaliação.
    • testCasesProcessed: total de casos de teste avaliados a partir da última atualização.

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

Obter execuções de teste do sistema agente

  • Ponto de extremidade:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • Finalidade: recuperar uma matriz de todas as execuções anteriores.
  • Resposta: cada item na matriz inclui os mesmos valores encontrados em Obter detalhes de execução de teste do agente.

Saiba mais em Execuções de teste de avaliação do Gerador de Listas.

Obter detalhes da execução de teste do agente

  • Ponto de extremidade:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{TestRunId}?api-version=2024-10-01
  • Finalidade: recupere os detalhes de uma avaliação usando o runId para sua execução de avaliação de destino.
  • Resposta: Retorna as seguintes informações:
    • id: o identificador da execução de avaliação. Use essa ID para recuperar os detalhes da avaliação.
    • environmentId: O ID do ambiente do seu agente.
    • cdsBotId: a ID do agente de destino.
    • ownerId: a ID do usuário que iniciou a execução da avaliação.
    • testSetId: a ID do conjunto de testes usado para a avaliação.
    • state: o status de progresso da avaliação.
    • startTime: Quando a avaliação começou.
    • endTime: quando a avaliação terminou, se ela terminou.
    • name: nome da avaliação.
    • totalTestCases: total de casos de teste no conjunto de testes.
    • mcsConnectionId: O ID da conexão do Copilot Studio do perfil de usuário usado na execução da avaliação. null se nenhum perfil de usuário estiver conectado.
    • testCasesResults: A lista de casos de teste no ciclo de avaliação. Contém:
      • testCaseId: o ID do caso de teste.
      • state: o estado de conclusão do caso de teste.
      • metricsResults: os detalhes e os resultados de cada método de teste usado para o caso de teste. Inclui o seguinte:
        • type: o método de teste.
        • result: o resultado final do teste para este caso de teste. Inclui o seguinte:
          • data: os detalhes do resultado. Os valores exatos dependem do método de teste. Saiba mais nos documentos da API do Power Platform. Para um teste de qualidade geral , a resposta inclui o seguinte:
            • abstention: se o agente respondeu à consulta.
            • relevance: se a resposta era relevante.
            • completeness: se a resposta está concluída.
        • status: o status do caso de teste.
        • errorReason: se ocorreu um erro, a causa do erro.
        • aiResultReason: a explicação de IA do resultado do caso de teste.

Saiba mais em Obter execução de teste de avaliação do Maker.

Usar um identificador do Microsoft Studio Connector para avaliações

Para Iniciar uma avaliação do agente, você pode, opcionalmente, adicionar uma ID do Microsoft Studio Connector à chamada como um perfil de usuário para a avaliação. Para localizar seu mcsConnectionId:

  1. Vá para Power Automate.
  2. Abra a página Conexões .
  3. Selecione a conexão Microsoft Copilot Studio.
  4. Copie a mcsConnectionId da URL: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details
  • Last updated on