Freigeben über

Automatisieren von Agent-Auswertungen mithilfe 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 der Agentqualität nach dem Vornehmen von Änderungen
  • Ausführen wiederkehrender Leistungsüberprüfungen für Produktions- oder Staging-Agents
  • Integration von Agententests 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".
    • Sie müssen das Zugriffstoken mithilfe der Client-ID einer App-Registrierung abrufen, die den entsprechenden Bereich unter der Power Platform-API gewährt hat.
  • Für Start an agent evaluation können Sie optional eine Microsoft Studio Connector-ID zum Anruf hinzufügen, um sie als Benutzerprofil für die Bewertung zu verwenden. So finden Sie Ihren 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

Ü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. Erfüllen sie die Voraussetzungen.
  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.

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 ist Active.
    • totalTestCases: Die Anzahl der Testfälle innerhalb des Testsatzes.

Abrufen von Details zum Agententestset

  • Endpunkt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}?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 in der Referenzdokumentation zur API zum Testen von Setdetails.

Agentenauswertung starten

  • Endpunkt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}/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. Informationen zum Auffinden Ihrer MCS-Verbindungs-ID finden Sie unter "Voraussetzungen ".
  • 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 des Laufs während der Auswertung.
    • 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.

Details zum Testlauf des Agenten abrufen

  • Endpunkt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{yourTestRunId}?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 Auswertevorgang. 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, die 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. Enthält:
        • type: Die Testmethode.
        • result: Das Endergebnis des Tests für diesen Testfall. Enthält:
          • 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 auftritt, wird die Ursache des Fehlers angezeigt.
        • aiResultReason: Die KI-Erklärung des Testfallergebnisses.

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.
  • Last updated on