Automatizar avaliações de agente usando 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:

  • 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 preparo
  • Integrar testes 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.
    • Você deve adquirir 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.
  • Para iniciar uma avaliação do agente, você pode opcionalmente adicionar uma ID do Microsoft Studio Connector à chamada, que será usada 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

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. Atenda aos 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.

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 é Active.
    • totalTestCases: o número de casos de teste dentro do conjunto de testes.

Obter detalhes do conjunto de testes do agente

  • Ponto de extremidade:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}?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 na documentação de referência da API de Obtenção de Detalhes do Conjunto de Testes.

Iniciar uma avaliação do agente

  • Ponto de extremidade:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}/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 do usuário. Se você não adicionar um mcsConnectionId à sua chamada, a avaliação será executada sem autenticação. Consulte os pré-requisitos para saber como localizar sua ID de conexão do MCS.
  • Resposta: Retorna as seguintes informações:
    • runId: a ID 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 status da execução durante o processo de avaliação.
    • 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.

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/{yourTestRunId}?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 essa ID para recuperar os 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 de progresso da avaliação.
    • startTime: Quando a avaliação começou.
    • endTime: quando a avaliação foi concluída (se for concluída).
    • 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. Contém:
      • testCaseId: a 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. Contém:
        • type: o método de teste.
        • result: o resultado final do teste para este caso de teste. Contém:
          • 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:
            • 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 houve um erro, a causa do erro.
        • aiResultReason: a explicação de IA do resultado do caso de teste.

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 de execução de teste do agente.
  • Last updated on