Automatizar avaliações de agentes com a API 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. 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

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

Obtenha detalhes do conjunto de testes dos agentes

  • 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 no array de resposta dos conjuntos de teste do agente.

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 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 corrida, durante a avaliação.
    • 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.

Obtenha detalhes do teste do agente

  • Ponto final:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{yourTestRunId}?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 foi concluída).
    • name: Nome da avaliação.
    • totalTestCases: Total de casos de teste no conjunto de testes.
    • mcsConnectionId: O ID de ligação do Copilot Studio para o perfil de utilizador utilizado na execução de avaliação. null Se nenhum perfil de utilizador estiver 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:
        • 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: 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.
  • Last updated on