Automatizar avaliações de agentes utilizando a API do Power Platform

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:

  • Validar a qualidade do agente após fazer alterações
  • Faça verificações de desempenho recorrentes contra agentes de produção ou de encenação
  • Integrar os testes de agentes nos pipelines CI/CD
  • Detetar regressões no comportamento dos agentes no início do ciclo de vida do 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.
    • Deve adquirir o token de acesso utilizando o ID do cliente de um registo de aplicação ao qual tenha sido concedido o âmbito apropriado pela API do Power Platform.
  • Para Iniciar uma avaliação de agente, pode opcionalmente adicionar um ID Microsoft Studio Connector à chamada para usar como perfil de utilizador na avaliação. Para encontrar o seu mcsConnectionId:
    1. Ir para Power Automate.
    2. Abre a página de Ligações .
    3. Seleciona a ligação Microsoft Copilot Studio.
    4. Copie o mcsConnectionId a partir do URL: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details

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

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: Carimbos de data/hora e IDs de utilizador para a 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 é Active.
    • totalTestCases: O número de casos de teste no conjunto de testes.

Obter detalhes do conjunto de testes do agente

  • Ponto final:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}?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 na matriz de resposta Obter conjuntos de testes de agentes.

Saiba mais na documentação de referência da API Get Test Set Details.

Inicie uma avaliação de agente

  • Ponto final:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}/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. Veja Pré-requisitos para encontrar o seu ID de Ligação MCS.
  • Resposta: Retorna a seguinte informação:
    • runId: O ID para a execução de avaliação. Use este ID para obter detalhes da avaliação.
    • lastUpdatedAt: Quando o estado da execução foi atualizado pela última vez.
    • executionState: O estado da execução, durante a execução da avaliação.
    • state: Estado atual da execução.
    • 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.

Obter detalhes da execução de testes do agente

  • Ponto final:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{yourTestRunId}?api-version=2024-10-01
  • Objetivo: Obter os detalhes de uma avaliação utilizando runId para a execução da avaliação de destino.
  • Resposta: Retorna a seguinte informação:
    • id: O ID para a execução de 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 foi concluída).
    • name: Nome da avaliação.
    • totalTestCases: Total de casos de teste no conjunto de testes.
    • mcsConnectionId: A ID de ligação para a ligação do Copilot Studio do perfil de utilizador utilizado para a execução da avaliação. null se não existir nenhum perfil de utilizador ligado.
    • testCasesResults: A lista de casos de teste na execução de 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:
        • type: O método de teste.
        • result: O resultado final deste caso de teste. Inclui:
          • 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:
            • 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 houve um erro, a causa do erro.
        • aiResultReason: A explicação da IA do resultado do caso de teste.

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: Obter uma matriz de todas as execuções anteriores.
  • Resposta: Cada item no array inclui os mesmos valores encontrados nos detalhes do teste Get agent.
  • Last updated on