Automatisieren von Agent-Auswertungen mit der Power Platform-API

Copilot Studio bietet Erstellern Tools, um die Agentenleistung kontinuierlich zu bewerten, indem automatisierte Tests mit vordefinierten Testsätzen unter Verwendung der Power Platform REST API ausgeführt werden. Mithilfe der REST-API können Sie Agent-Auswertungen programmgesteuert als Teil Ihrer Entwicklungsworkflows auslösen, z. B. während Agent-Updates, Freigabeüberprüfungen oder Regressionstests.

Die Automatisierung von Auswertungen hilft Ihnen:

  • Überprüfen Sie die Qualität des Agenten, nachdem Sie Änderungen vorgenommen haben.
  • Führen Sie wiederkehrende Leistungsprüfungen für Produktions- oder Staging-Agents aus.
  • Integrieren Sie Agenttests in CI/CD-Pipelines.
  • Erkennen von Regressionen im Agentverhalten frühzeitig im Entwicklungslebenszyklus.

Voraussetzungen

  • Sie verfügen über die Bot-ID und die Umgebungs-ID für den Ziel-Agent.
  • Ein testsatz erstellt in Copilot Studio für Ihren Ziel-Agent.
  • Ein von Microsoft Entra ID (OAuth 2.0) ausgestelltes Benutzerzugriffstoken. Informationen zum Abrufen des Tokens finden Sie unter Authentifizierung.
    • Rufen Sie das Zugriffstoken mithilfe der Client-ID einer App-Registrierung ab, die den entsprechenden Bereich unter der Power Platform-API gewährt hat.

Übersicht über die Ausführung von Auswertungen mithilfe der REST-API

Führen Sie die folgenden allgemeinen Schritte aus, um eine Auswertung mithilfe der Power Platform-API auszuführen:

  1. Füllen Sie die Voraussetzungen aus.
  2. Suchen und abrufen Sie die Testsatz-ID des Testsatzes, den Sie verwenden möchten.
  3. Führen Sie die Auswertung aus.
  4. Rufen Sie die Ergebnisse mithilfe der Auswertungsausführungs-ID ab.

Wenn die Anforderung erfolgreich ist, wird die Auswertung asynchron ausgeführt und erzeugt Ergebnisse, die Sie in Copilot Studio überprüfen können.

API-Vorgänge zum Automatisieren von Auswertungen

Copilot Studio unterstützt REST-API-Vorgänge, die Sie zum programmgesteuerten Auslösen von Auswertungen für Ihren Agent verwenden können, indem Sie einen vorhandenen Testsatz verwenden.

Weitere Informationen darüber, wie und wann Sie die Power Platform-API verwenden können, finden Sie unter:

Agenttestsätze abrufen

  • Endpunkt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01
  • Zweck: Abrufen eines Arrays der Testsatz-IDs und anderer Details für einen bestimmten Agent.
  • Antwort: Gibt eine Liste der Testsätze mit den folgenden Informationen zurück value :
    • auditInfo: Zeitstempel und Benutzer-IDs zum Erstellen und Ändern der einzelnen Testsätze
    • displayName: Der Name des Testsatzes.
    • id: Die ID des Testsatzes. Verwenden Sie die Option "Agent-Auswertung starten ", um auszuwählen, welcher Testsatz verwendet werden soll.
    • description: Die Beschreibung des Testsatzes.
    • state: Der Status des Testsatzes. Ein verwendbarer Testsatz hat den Status Active.
    • totalTestCases: Die Anzahl der Testfälle innerhalb des Testsatzes.

Weitere Informationen finden Sie unter List Maker Evaluation Test Sets.

Abrufen von Details zum Agententestset

  • Endpunkt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}?api-version=2024-10-01
  • Zweck: Abrufen von Details für einen bestimmten Testsatz mithilfe der Testsatz-ID.
  • Antwort: Gibt die Information eines Elements im Get-Agent-Testset-Antwort-Array zurück.

Weitere Informationen finden Sie unter List Maker Evaluation Test Sets.

Agentenauswertung starten

  • Endpunkt:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}/run?api-version=2024-10-01
  • Zweck: Führen Sie eine Auswertung für einen Testsatz mithilfe des Testsatzes id durch. Sie können auch ein Benutzerprofil für die Authentifizierung von Verbindungen während der Auswertungsausführung einschließen. Wird mcsConnectionId verwendet, um das Benutzerprofil anzugeben. Wenn Sie Ihrem Aufruf kein mcsConnectionId hinzufügen, wird die Auswertung ohne Authentifizierung ausgeführt.
  • Antwort: Gibt die folgenden Informationen zurück:
    • runId: Die ID für den Evaluierungslauf. Verwenden Sie diese ID, um Auswertungsdetails abzurufen.
    • lastUpdatedAt: Wann der Status der Ausführung zuletzt aktualisiert wurde.
    • executionState: Der Status der Ausführung, während die Auswertung ausgeführt wird.
    • state: Aktueller Zustand des Laufs.
    • totalTestCases: Die Gesamtanzahl der Testfälle im Testsatz, der für die Auswertung verwendet wird.
    • testCasesProcessed: Gesamtzahl der Testfälle, die bis zur letzten Aktualisierung ausgewertet wurden.

Weitere Informationen finden Sie unter Run Maker Evaluation Test Set.

Testausführungen von Agenten abrufen

  • Endpunkt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • Zweck: Abrufen eines Arrays aller vorherigen Ausführungen.
  • Antwort: Jedes Element im Array enthält dieselben Werte wie in get agent test run details.

Weitere Informationen finden Sie unter List Maker Evaluation Test Runs.

Details zum Testlauf des Agenten abrufen

  • Endpunkt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{TestRunId}?api-version=2024-10-01
  • Zweck: Rufen Sie die Details einer Auswertung mithilfe der runId Zielauswertungsausführung ab.
  • Antwort: Gibt die folgenden Informationen zurück:
    • id: Die ID für den Evaluierungslauf. Verwenden Sie diese ID, um Auswertungsdetails abzurufen.
    • environmentId: Die ID für die Umgebung Ihres Agents.
    • cdsBotId: Die ID für den Ziel-Agent.
    • ownerId: Die ID des Benutzers, der die Auswertung gestartet hat.
    • testSetId: Die ID des testsatzes, der für die Auswertung verwendet wird.
    • state: Der Status der Bewertung.
    • startTime: Als die Auswertung begann.
    • endTime: Nach Abschluss der Auswertung, sofern sie abgeschlossen ist.
    • name: Name der Auswertung.
    • totalTestCases: Gesamtanzahl der Testfälle im Testsatz.
    • mcsConnectionId: Die Verbindungs-ID für die Copilot Studio Verbindung des Benutzerprofils, das für die Auswertungsausführung verwendet wird. null wenn kein Benutzerprofil verbunden ist.
    • testCasesResults: Die Liste der Testfälle im Auswertungslauf. Enthält:
      • testCaseId: Die ID des Testfalls.
      • state: Der Abschlussstatus des Testfalls.
      • metricsResults: Die Details und Ergebnisse für jede Testmethode, die für den Testfall verwendet wird. Umfasst Folgendes:
        • type: Die Testmethode.
        • result: Das Endergebnis des Tests für diesen Testfall. Umfasst Folgendes:
          • data: Die Details des Ergebnisses. Genaue Werte sind von der Testmethode abhängig. Weitere Informationen finden Sie in den Power Platform-API-Dokumenten. Für einen allgemeinen Qualitätstest umfasst die Antwort Folgendes:
            • abstention: Gibt an, ob der Agent die Abfrage beantwortet hat.
            • relevance: Ob die Antwort relevant war.
            • completeness: Gibt an, ob die Antwort abgeschlossen ist.
        • status: Der Status des Testfalls.
        • errorReason: Wenn ein Fehler aufgetreten ist, die Ursache des Fehlers.
        • aiResultReason: Die KI-Erklärung des Testfallergebnisses.

Weitere Informationen finden Sie unter Get Maker Evaluation Test Run.

Verwenden einer Microsoft Studio Connector-ID für Auswertungen

Für Start an agent evaluation können Sie dem Aufruf optional eine Microsoft Studio Connector ID als Benutzerprofil für die Auswertung hinzufügen. So finden Sie Ihr mcsConnectionId:

  1. Wechseln Sie zu Power Automate.
  2. Öffnen Sie die Seite "Verbindungen ".
  3. Wählen Sie die Verbindung Microsoft Copilot Studio aus.
  4. Kopieren Sie das mcsConnectionId aus der URL: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details
  • Last updated on