Automatize avaliações de agentes com a API do Power Platform

O Copilot Studio oferece aos criadores ferramentas para realizar avaliações contínuas do desempenho dos agentes, executando testes automatizados em relação a conjuntos de testes predefinidos usando a API REST do Power Platform. Ao usar a API REST, você pode desencadear de forma programática avaliações de agentes como parte dos seus fluxos de trabalho de desenvolvimento, como durante atualizações de agentes, validação de versões ou testes de regressão.

Automatizar as avaliações ajuda você a:

  • Validar a qualidade do agente após realizar alterações.
  • Executar verificações de desempenho recorrentes em relação a agentes de produção ou de preparo.
  • Integrar testes de agente em pipelines de CI/CD.
  • Detectar regressões no comportamento do agente no início do ciclo de vida do 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 de 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 do 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. Complete os pré-requisitos.
  2. Encontre e recupere a ID do conjunto de testes que você deseja usar.
  3. Execute a avaliação.
  4. Recupere os resultados usando o ID da execução da avaliação.

Quando a solicitação tem êxito, a avaliação é executada de forma assíncrona e produz resultados que você pode revisar no Copilot Studio.

Operações de API para a automação de avaliações

O Copilot Studio oferece suporte a operações da API REST que você pode usar para desencadear avaliações de forma programática 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 testes.

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

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: recupere detalhes de um conjunto de teste específico, usando a ID do conjunto de teste.
  • Resposta: retorna as informações de um item da matriz de respostas Obter conjuntos de testes do agente.

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

Iniciar uma avaliação de 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 testes. 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 de usuário. Se você não adicionar uma mcsConnectionId à sua chamada, a avaliação será executada sem autenticação.
  • Resposta: retorna as seguintes informações:
    • runId: a ID da execução de avaliação. Use esta ID para recuperar detalhes da avaliação.
    • lastUpdatedAt: quando o status da execução foi atualizado pela última vez.
    • executionState: o status da execução enquanto a avaliação está em execução.
    • state: o 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 em Executar Conjunto de Testes de Avaliação do Criador.

Obter execuções de teste do 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 da execução de teste do agente.

Saiba mais em Listar Execuções de Teste de Avaliação do Criador.

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: recuperar 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: a ID da execução de avaliação. Use esta ID para recuperar detalhes da avaliação.
    • environmentId: a ID do ambiente de 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 do progresso da avaliação
    • startTime: quando a avaliação foi iniciada.
    • 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: a ID de conexão para a conexão do Copilot Studio do perfil de usuário usado para a execução de avaliação. null se nenhum perfil de usuário estiver conectado.
    • testCasesResults: a lista de casos de teste na execução de avaliação. Inclui:
      • testCaseId: a ID do caso de teste.
      • state: o status de conclusão do caso de teste.
      • metricsResults: os detalhes e resultados de cada método de teste usado no 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 na documentação 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 foi relevante
            • completeness: se a resposta está completa.
        • status: o status do caso de teste.
        • errorReason: em caso de erro, a causa do erro.
        • aiResultReason: a explicação da IA do resultado do caso de teste.

Saiba mais em Obter Execução de Teste de Avaliação do Maker.

Use uma ID do conector do Microsoft Studio para avaliações

Para iniciar uma avaliação de agente, você pode, opcionalmente, adicionar uma ID do conector do Microsoft Studio à chamada como um perfil de usuário para a avaliação. Para encontrar sua mcsConnectionId:

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