Migriere Copilot Studio-Agenten auf Microsoft Entra-Agent-ID

Dieser Artikel beschreibt, wie bestehende Copilot Studio-Agenten optional von der alten App-Registrierungsidentität auf eine Microsoft Entra-Agent-ID migriert werden können, bevor die automatische Migration durchgeführt wird.

Nutzen Sie die Empfehlung im Power Platform Admin Center, um berechtigte Agenten zu identifizieren, Migrationschargen zu planen und einen oder mehrere Agenten zu migrieren. Diese beraterbasierte Erfahrung ist die empfohlene manuelle Migrationsmethode. Sie können auch Power Platform API-Endpunkte nutzen, um Ihren eigenen Migrationsprozess zu erstellen.

Wenn Sie einen Agenten auf die Microsoft Entra-Agent-ID migrieren, erhalten Sie:

• Eine erstklassige Agenten-Identität, die Administratoren in Microsoft Entra einsehen und steuern können.
• Bedingter Zugriff und andere Zugriffsrichtlinien, die für agentenbasierte Workloads entwickelt und auf Agenten beschränkt sind, anstatt von App-Registrierungen übernommen zu werden.
• Ein konsistentes Identitätsmodell über die Dienste hinweg, die mit Ihren Agenten zusammenarbeiten.

Erfahren Sie mehr zu Agentenidentitäten und Authentifizierung für Copilot Studio.

Über die Migration der Agentenidentität

Die Migration wandelt die bestehende App-Registrierungsidentität eines Agenten um. Der Agent behält seine Anwendungs-(Client-)ID, sodass nachgelagerte Konfigurationen, die diese ID verwenden, wie Kanalregistrierungen und -anschlüsse, weiterhin auf denselben Identifikator aufgelöst werden. Der Agent erhält außerdem eine Microsoft Entra-Agent-ID, die Administratoren verwalten können.

Die Migration ist ein kontrollierter, opt-in-Prozess. Sie haben folgende Möglichkeiten:

• Einen Agenten migrieren.
• Wähle mehrere Agenten aus und migriere sie als Batch.
• Migrate weitere Chargen nach deinem eigenen Zeitplan.
• Setzen Sie einen Agenten auf seine bisherige Identität zurück, wenn er die Validierung nicht besteht.

Prerequisites

• Sie müssen Power Platform Administrator, Dynamics 365 Administrator oder Global Administrator sein.
• Das Power Platform-Inventar muss für Ihren Mieter aktiviert sein, damit Advisor berechtigte Agenten identifizieren kann.
• Koordinieren Sie ein Validierungsfenster mit den Herstellern, die die Agenten besitzen, die Sie migrieren möchten.

Plane deine Migrationschargen

Das Migrieren von Agentenidentitäten betrifft Live-Agenten und kann Authentifizierung, Connectors und Integrationen stören, wenn man die Migration nicht sorgfältig plant. Verwenden Sie den folgenden gestuften Ansatz:

1. Beginnen Sie mit einem Pilotprojekt: Wählen Sie eine kleine Gruppe nicht-kritischer Agenten aus, die die Kanäle, Authentifizierungsmodi, Connectors, Flows und Integrationen repräsentieren, die Sie validieren müssen.
2. Koordinieren Sie sich mit Herstellern: Benachrichtigen Sie die betroffenen Hersteller und einigen Sie sich auf ein Validierungsfenster. Hersteller sollten verfügbar sein, um ihre Agenten zu testen, wenn ein Migrationsbatch abgeschlossen ist.
3. Inkrementell migrieren: Agenten einzeln oder in kleinen Chargen migrieren. Übertragen Sie nicht den gesamten Nachlass auf einmal.
4. Überprüfen Sie End-to-End: Bestätigen Sie, dass jeder migrierte Agent über seine konfigurierten Kanäle, Aktionen, Connectors, Authentifizierungsflüsse und Integrationen hinweg arbeitet.
5. Überwachen und erweitern: Überprüfen Sie die Anmeldeprotokolle von Microsoft Entra, einschließlich der Ergebnisse des bedingten Zugriffs, bevor Sie eine größere Charge migrieren.

Agenten im Power Platform Admin Center migrieren

Nutzen Sie die Advisor-Empfehlung im Power Platform Admin Center, um berechtigte Agenten zu überprüfen und einen oder mehrere Agenten zu migrieren.

1. Melden Sie sich im Power Platform Admin Center an.

2. Im linken Navigationsbereich wählen Sie Aktionen aus.

3. Wählen Sie unter Aktionen Empfehlungen aus.

4. Im Reiter Empfehlungen wählen Sie Aktiv.

5. Suchen Sie nach Copilot Studio-Agenten zu Microsoft Entra-Agent-ID für eine verbesserte Agentenverwaltung migrieren, und wählen Sie dies aus.

   

6. Im Empfehlungsfenster erweitern Sie Warum ist das wichtig?, und sehen Sie sich die Migrationsleitlinien an.

7. Überprüfen Sie die berechtigten Agenten. Verwenden Sie die vorgeschlagene Migrationsreihenfolge und die Migrationsnotizen, um einen ersten Piloten oder den nächsten Migrationsbatch auszuwählen. Die Tabelle liefert außerdem Informationen wie Umgebung, Umgebungstyp, Besitzer, aktuelle Aktivitäten und Authentifizierungsmethode.

8. Wähle das Kontrollkästchen neben jedem Agenten, den du migrieren möchtest. Sie können einen Agenten oder mehrere berechtigte Agenten auswählen.

   Die Schaltfläche "Migrieren " wird verfügbar und die Aktionsleiste zeigt die Anzahl der ausgewählten Agenten an.

   

9. Wählen Sie Migrate aus, überprüfen Sie die Bestätigung und bestätigen Sie die Migration.

10. Überprüfen Sie die Spalten Aktion,Aktionszustand und Aktionsdatum für jeden ausgewählten Agenten. Um Aktionen in verschiedenen Empfehlungen zu überprüfen, wählen Sie den Reiter Aktionshistorie .

Wiederholen Sie diese Schritte für jede geplante Charge nur, nachdem die vorherige Charge die Validierung bestanden hat.

Validieren von migrierten Agenten

Bevor Sie eine weitere Gruppe migrieren, stimmen Sie sich mit den Erstellern der Agenten ab und bestätigen Sie, dass jeder migrierte Agent:

• Antwortet korrekt in jedem Kanal, in dem es veröffentlicht wird.
• Führt Aktionen, Verbindungen, Abläufe und Integrationen erfolgreich aus.
• Authentifiziert sich wie erwartet, einschließlich benutzerdefinierter Authentifizierung.
• Funktioniert wie erwartet mit den entsprechenden Agenten-Zugriffsrichtlinien und Conditional Access-Richtlinien.

Überprüfen Sie die Anmeldeprotokolle der migrierten Agenten im Microsoft Entra Admin Center. Bestätigen Sie eine erfolgreiche Authentifizierung und untersuchen Sie Fehler oder unerwartete Ergebnisse des Conditional Access.

Wenn ein Agent die Validierung nicht besteht, stoppe den Batch-Rollout und setze diesen Agenten zurück, bevor du weitermachst.

Optional: API-Operationen zur Agenten-ID-Migration

Wenn Sie Ihre eigene Automatisierung entwickeln möchten, können Sie Power Platform API-Endpunkte aufrufen, um Agenten zu migrieren oder zurückzusetzen (zurückzurollen). Beide Operationen sind HTTP-POST-Anfragen, die mit einem Trägertoken für den Power Platform-Dienst autorisiert sind.

Weitere Informationen finden Sie unter:

• Power Platform-API und SDKs: Von UX-first bis API-first (Blog) (Power Platform Developer Blog)
• Übersicht über die Programmierbarkeit und Erweiterbarkeit (Dokumentation zur Power Platform)
• Erste Schritte mit der Power Platform-API (Dokumentation zu Power Platform)
• Referenzdokumentation der Copilot Studio Betriebs-API

Holen Sie sich ein OAuth2-Trägertoken für die Power Platform API

Alle hier aufgeführten Operationen erfordern ein OAuth2-Trägertoken für https://api.powerplatform.com. Fügen Sie dieses Token in Ihre Anfrage unter einer Überschrift Authorization hinzu. Das Token muss von der Microsoft Entra ID OAuth2 stammen und mit einem Benutzerkonto verknüpft sein, das eine der in den Voraussetzungen aufgeführten Admin-Rollen hat.

Verwenden Sie zum Beispiel das Az PowerShell-Modul, um das Token abzurufen und es als $token zur Verwendung in API-Anfragen zu speichern:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

Migriere die Agentenidentität auf Microsoft Entra-Agent-ID

Migrieren Sie einen Agenten von der App-Registrierungs-ID zur Entra-Agent-ID, indem Sie eine POST-Anfrage mit den Angaben des Agenten an den Migrierungs-Endpunkt senden:

• Endpunkt:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Authentifizierung: Fügen Sie ein gültiges OAuth-Trägertoken für die Power Platform API im Authorization Header ein. Die Power Platform API benötigt ein Inhabertoken von Microsoft Entra ID.
• Body: Nicht erforderlich
• Zweck: Migration eines Agenten von der App-Registrierungs-ID zur Entra-Agent-ID
• Antwort: Gibt ein AgentIdentityMigrationResult JSON-Objekt mit einem status Wert für die ID-Migration des Agenten zurück:
  • Migrated
  • AlreadyMigrated

Zum Beispiel erhält das folgende Skript ein Autorisierungstoken und ruft dann den Migr-Endpunkt für einen bestimmten Agenten (<BotId>) in einer bestimmten Umgebung (<EnvironmentId>) mit dieser Autorisierung auf:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

$environmentId = "<EnvironmentId>"
$botId = "<BotId>"

$uri = "https://api.powerplatform.com/copilotstudio/environments/$environmentId/bots/$botId/api/agentidentitymigration/migrate?api-version=2024-10-01"
Invoke-RestMethod `
    -Method Post `
    -Uri $uri `
    -Headers @{
        Authorization = "Bearer $token"
    }

Die folgende Beispielantwort zeigt eine erfolgreiche Migration:

{
  "status": "Migrated",
  "cdsBotId": "<bot-id>",
  "environmentId": "<environment-id>",
  "tenantId": "<tenant-id>",
  "agentIdentityId": "<agent-identity-id>",
  "applicationId": "<application-client-id>",
  "servicePrincipalObjectId": "<service-principal-object-id>",
  "managedIdentityId": "<managed-identity-id>",
  "completedAtUtc": "2026-08-21T12:00:00Z"
}

Agentenidentität auf App-Registrierungs-ID zurücksetzen oder zurückrollen

Um einen Agenten zurückzusetzen, senden Sie eine POST-Anfrage an den Rücksetzungsendpunkt mit den Angaben des Agenten:

• Endpunkt:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Authentifizierung: Fügen Sie ein gültiges OAuth-Trägertoken für die Power Platform API im Authorization Header ein. Die Power Platform API benötigt ein Inhabertoken von Microsoft Entra ID.
• Body: Nicht erforderlich
• Zweck: Rollback (Zurücksetzen) der ID eines Agenten von einer Entra ID zu einer App-Registrierungs-ID
• Antwort: Gibt ein AgentIdentityRollbackResult JSON-Objekt mit einem Terminalstatuswert für die ID-Migration des Agenten zurück:
  • NotMigrated
  • RolledBack

Zum Beispiel erhält das folgende Skript ein Token und ruft dann den Revert-Endpunkt für einen bestimmten Agenten (<BotId>) in einer bestimmten Umgebung (<EnvironmentId>) mit dieser Autorisierung auf:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

$environmentId = "<EnvironmentId>"
$botId = "<BotId>"

$uri = "https://api.powerplatform.com/copilotstudio/environments/$environmentId/bots/$botId/api/agentidentitymigration/rollback?api-version=2024-10-01"
Invoke-RestMethod `
    -Method Post `
    -Uri $uri `
    -Headers @{
        Authorization = "Bearer $token"
    }

Die folgende Beispielantwort zeigt ein erfolgreiches Rollback:

{
  "status": "RolledBack",
  "cdsBotId": "<bot-id>",
  "environmentId": "<environment-id>",
  "tenantId": "<tenant-id>",
  "completedAtUtc": "2026-08-21T12:05:00Z"
}

Troubleshooting

Die folgende Tabelle listet häufige Probleme und deren Lösung auf:

Verwandte Inhalte

• Beispielabfragen für Power Platform-Inventar
• Copilot Studio-Agenteninventar