KI-geführte Konfiguration für Microsoft Entra-Agent-ID

Das Onboarding in Microsoft Entra-Agent-ID umfasst mehrere Schritte: Erstellen eines Agent-Identitäts-Blueprints, Konfigurieren von Anmeldeinformationen, Einrichten von Bezeichner-URIs und Bereichen, Erstellen von Blueprintprinzipalen und Bereitstellungs-Agent-Identitäten. Jeder Schritt hat seine eigenen Voraussetzungen, Validierungsprüfungen und Entscheidungspunkte.

Diese KI-geführte Einrichtung automatisiert diesen gesamten Workflow mithilfe eines AI-Codierungs-Agents (z. B. GitHub Copilot in VS Code), um die Schritte in Ihrem Auftrag auszuführen. Anstatt zwischen mehreren Dokumentationsseiten zu navigieren und Befehle manuell auszuführen, stellen Sie dem KI-Agenten eine einzige Anweisungsdatei zur Verfügung, die Sie interaktiv durch den Prozess führt. Diese Anweisungsdatei ist als Fähigkeit verfügbar und kann auf mehrere Weise zugegriffen werden.

Vorteile

Das KI-gesteuerte Setup bietet mehrere Vorteile gegenüber dem manuellen Arbeitsablauf:

• Einzelner Einstiegspunkt: Eine Anweisungsdatei ersetzt die Notwendigkeit, zwischen mehreren Dokumentationsseiten zu navigieren. Der KI-Agent folgt den Schritten in der Reihenfolge und übernimmt Übergänge automatisch.
• Automatierte Überprüfung der erforderlichen Komponenten: Der KI-Agent überprüft, ob Sie über die richtigen Microsoft Entra Rollen verfügen, dass die erforderlichen Tools und Graph-Module installiert sind und dass erforderliche Berechtigungen mit Administratorzustimmung konfiguriert werden, bevor API-Aufrufe ausgeführt werden.
• Intelligente Standardeinstellungen und automatische Erkennung: Der KI-Agent fragt Ihren Mandanten nach vorhandenen Benutzerinformationen und Ressourcendetails ab und verwendet diese Werte dann als Vorschläge beim Sammeln von Konfigurationseingaben.
• Abgeleitete Benennungskonventionen: Sie stellen einen einzelnen Anzeigenamen für Ihren Agent bereit, und der KI-Agent leitet alle zugehörigen Ressourcennamen ab (Blueprint, Blueprint-Prinzipal, Agentidentitäten, Bezeichner-URIs) mithilfe konsistenter Muster.
• Inlinefehlerbehandlung: Wenn ein Befehl fehlschlägt, analysiert der KI-Agent den Fehler, schlägt eine Korrektur vor und versucht es erneut, anstatt durch die Problembehandlungsdokumentation zu suchen. Diese Fehlerbehandlung ist besonders nützlich für Agent-ID-spezifische Fallstricke wie Berechtigungsverteilungsverzögerungen und OData-Headeranforderungen.
• Idempotent-Vorgänge: Der KI-Agent überprüft, ob ressourcen bereits vorhanden sind, bevor sie erstellt wurden, wodurch es sicher ist, das Setup erneut auszuführen, wenn ein vorheriger Versuch unterbrochen wurde.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über die folgenden Voraussetzungen verfügen.

Notwendige Werkzeuge

Das KI-geführte Setup erfordert einen KI-Codierungs-Agent mit Terminalzugriff:

• Visual Studio Code mit installierten Erweiterungen GitHub Copilot und GitHub Copilot Chat installiert.
• Die Erweiterung GitHub Copilot for Azure, die die Microsoft Entra-Agent-ID-Funktion direkt in VS Code bereitstellt.

Die Fähigkeit unterstützt zwei Bereitstellungspfade. Installieren Sie je nach Ihren Einstellungen eine oder beides:

• PowerShell-Pfad: PowerShell 7 oder höher mit dem Microsoft Graph PowerShell SDK. Führen Sie die Installation mithilfe von Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force aus.
• Python Pfad: Python 3,8 oder höher mit azure-identity und requests. Führen Sie die Installation mithilfe von pip install azure-identity requests aus.

Erforderliche Konten und Berechtigungen

• Zugriff auf einen Microsoft Entra-Mandanten mit einer der folgenden Rollen:
  • Agent-ID-Entwickler zur Erstellung von Agentenidentitätsentwürfen und Agentenidentitäten. Jeder Besitzer eines Agentidentitäts-Blueprints kann eine Agentidentität für diesen Blueprint ohne Agent-ID-Rolle erstellen.
  • Agent-ID-Administrator für vollständigen Administratorzugriff auf Agent-ID-Ressourcen.

• Zusätzliche Rollen für Berechtigungserteilungen:
  • Privileged Role Administrator, um Microsoft Graph Anwendungsberechtigungen zu erteilen.
  • Cloud-Anwendungsadministrator oder Application Administrator, um Microsoft Graph delegierte Berechtigungen zu erteilen.

Erforderliche Microsoft Graph Berechtigungen

Der verwendete Client (PowerShell oder eine benutzerdefinierte App-Registrierung) muss mit den folgenden delegierten Berechtigungen autorisiert werden:

Erforderlicher Agentcode (optional)

Wenn Sie bereits über ein Agent-Projekt (Python, Node.jsoder .NET) verfügen, das eine Agentidentität benötigt, ist das Projektverzeichnis verfügbar. Wenn Sie noch keins haben, können Sie das Blueprint-Setup trotzdem unabhängig abschließen.

Get started

Das KI-geführte Setup verwendet eine Fähigkeit, bei der es sich um eine einzelne Anweisungsdatei handelt, die alle Schritte und Überprüfungsprüfungen enthält. Sie können auf eine von zwei Arten auf die Fähigkeiten zugreifen:

• Über die GitHub Copilot for Azure-Erweiterung (empfohlen): Installieren Sie die GitHub Copilot for Azure VS Code-Erweiterung. Der Microsoft Entra-Agent-ID Skill wird automatisch aktiviert, wenn Sie in Copilot Chat nach der Agent-ID-Einrichtung fragen.
• Direkt aus GitHub: Verwenden Sie die eigenständige Microsoft Entra-Agent-ID skill, indem Sie sie in Ihrem Copilot Chat-Prompt einbinden.

Schritt 1: Öffnen Des Projekts in VS Code

Öffnen Sie Ihr Agent-Projektverzeichnis (oder ein beliebiges Arbeitsverzeichnis) in Visual Studio Code.

Schritt 2: Öffnen von GitHub-Copilot Chat im Agentmodus

Öffnen Sie den GitHub-Copilot Chat bereich, und wechseln Sie zum Agent-Modus. Der Agentmodus bietet GitHub Copilot die Möglichkeit, Terminalbefehle auszuführen, Dateien zu lesen und mit Ihrer Umgebung zu interagieren, die das KI-geführte Setup erfordert.

Schritt 3: Starten des geführten Setups

Wenn die GitHub Copilot für Azure Erweiterung installiert ist, bitten Sie Copilot, die Agent-ID einzurichten. Beispiel:

@azure Use the Agent ID Skill to set up an agent identity blueprint and create agent identities for my project using Microsoft Entra Agent ID.

Wenn Sie nicht über die Erweiterung verfügen, verweisen Sie direkt von GitHub auf die Fähigkeit:

Follow the steps in https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugin/skills/entra-agent-id/SKILL.md

Der KI-Agent liest die Fähigkeit und beginnt mit dem geführten Setup. Es arbeitet die Schritte nacheinander ab:

1. Voraussetzungen überprüfen: Prüft die Microsoft Entra-Rollen und überprüft, ob die erforderlichen Tools (PowerShell mit Microsoft Graph-Modul oder Python mit azure-identity) installiert sind.
2. Authentifizieren: Stellt die Verbindung mit Microsoft Graph mit den erforderlichen Berechtigungen her. Für PowerShell verwendet der Skill Connect-MgGraph mit expliziten delegierten Bereichen. Für Python wird eine dedizierte App-Registrierung mit Clientanmeldeinformationen verwendet.
3. Erstellen Sie die Agent-Identitätsvorlage: Erfasst einen Anzeigenamen, identifiziert den Sponsor (Sie), erstellt die Vorlage mithilfe des typisierten Endpunkts (/applications/microsoft.graph.agentIdentityBlueprint) und zeichnet appId auf.
4. Konfigurieren von Anmeldeinformationen: Fügt dem Blueprint eine Verbundidentität mit verwalteter Identität (für die Produktion) oder einen geheimen Clientschlüssel (für lokale Entwicklung/Tests) hinzu.
5. Konfigurieren Sie Bezeichner-URI und Berechtigungsbereich: Setzt identifierUris auf api://{appId} und erstellt einen OAuth2-Berechtigungsbereich für die Agent-zu-Agent- und Benutzer-zu-Agent-Kommunikation.
6. Erstellen Sie den Blueprint-Prinzipal: Erstellt den Dienstprinzipal für den Blueprint mithilfe des typierten Endpunkts (der Prinzipal wird nicht automatisch erstellt und muss explizit ausgeführt werden).
7. Agentenidentitäten erstellen: Erstellt einen oder mehrere Agentenidentitätsdienstprinzipale unter dem Blueprint.

Wenn der Agent die Fähigkeit liest, werden Sie möglicherweise aufgefordert, Erweiterungen oder andere Tools zu installieren. Folgen Sie den Anweisungen, um sicherzustellen, dass Ihre Umgebung bereit ist.

Schritt 4: Reagieren Sie auf Aufforderungen

Der KI-Agent hält an bestimmten Stellen inne, um Eingaben von dir zu sammeln:

• Anzeigename: Der Anzeigename für de Entwurf Ihrer Agentenidentität (z. B. „Contoso Budget Agent“).
• Sponsor: Der Benutzer oder die Gruppe, der für den Agent verantwortlich ist. Standardmäßig wird der aktuell angemeldete Benutzer verwendet.
• Besitzer: Der Benutzer oder Dienstprinzipal, der technische Änderungen am Blueprint vornehmen kann. Optional, aber empfohlen.
• Anmeldungstyp: Gibt an, ob eine verwaltete Identität (für die Produktion empfohlen) oder ein Zertifikat oder ein Clientgeheimnis (für die lokale Entwicklung) verwendet werden soll.
• Anzahl der Agentidentitäten: Wie viele Agentidentitäten unter diesem Blueprint erstellt werden sollen.
• Bestätigung des abgeleiteten Werts: Überprüfen Sie automatisch generierte Namen und URIs, bevor Ressourcen erstellt werden.

Schritt 5: Überprüfen im Microsoft Entra Admin Center

Nach Abschluss des Setups stellt der KI-Agent Anweisungen zum Überprüfen der Ressourcen bereit.

1. Melden Sie sich bei der Microsoft Entra Admin Center mindestens als Agent ID Developer an.
2. Navigieren Sie zu Entra ID>Agents>Agent-Identitäten, um Ihren neuen Agentidentitäts-Blueprint und alle darin erstellten Agentidentitäten anzuzeigen.
3. Vergewissern Sie sich, dass für den Blueprint Anmeldeinformationen, Identifikator-URI und Bereich korrekt konfiguriert sind.

Was das KI-gesteuerte Setup abdeckt

Das KI-geführte Setup automatisiert die folgenden Phasen der Agent-ID-Integration:

Häufige Probleme, die das KI-gestützte Setup bewältigt

Die Agent-ID-APIs weisen mehrere Anforderungen auf, die vom KI-geführten Setup automatisch erkannt und aufgelöst werden, aber sie sind keine offensichtlichen Anforderungen. Das Verständnis dieser Fallstricke kann hilfreich sein, wenn Sie Probleme debuggen oder das Setup erweitern müssen.

OData-Version-Header ist erforderlich.

Für alle Agent-ID-API-Aufrufe ist der OData-Version: 4.0 Header erforderlich. Wenn Sie diesen Header weglassen, erstellt die API möglicherweise im Hintergrund eine Standardanwendung anstelle eines Agentidentitäts-Blueprints. Die KI-geführte Einrichtung enthält immer diesen Header. Der Skill verwendet außerdem typisierte Endpunkte (z. B. /applications/microsoft.graph.agentIdentityBlueprint) anstelle von rohem /applications mit @odata.type-Eigenschaften, um das Risiko dieses Problems zu verringern.

Der Blueprint-Prinzipal wird nicht automatisch erstellt.

Bei der Erstellung eines Agentenidentitäts-Blueprints (POST /applications) wird nicht automatisch dessen Blueprint-Prinzipal (Dienstprinzipal) erstellt. Ohne die Blueprint-Hauptkomponente schlägt die Erstellung aller nachfolgenden Agentidentitäten fehl:

400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

Das KI-geführte Setup erstellt immer den Blueprint-Prinzipal unmittelbar nach dem Blueprint. Es behandelt auch den idempotenten Fall. Wenn eine vorherige Ausführung den Blueprint erstellt, aber vor dem Erstellen des Prinzipals abgestürzt ist, erkennt das Setup dieses Ereignis und erstellt den fehlenden Prinzipal.

Sponsoren sind erforderlich

Sponsoren sind erforderlich und können Benutzer, Gruppen mit dynamischer Mitgliedschaft oder einheitliche Gruppen sein. Sowohl die Erstellung von Blueprints als auch von Agentenidentitäten erfordert ein Feld sponsors@odata.bind. Ohne sie erhalten Sie:

400: No sponsor specified. Please provide at least one sponsor.

Das KI-geführte Setup akzeptiert nur Benutzerobjekte für die Sponsorzuweisung und verwendet das /users/{objectId} URL-Format (nicht /directoryObjects/ oder /servicePrincipals/). Das Setup löst die Objekt-ID des aktuellen Benutzers auf und verwendet sie als Standardsponsor. Wenn Sie eine supported-Gruppe als Sponsor für einen Blueprint zuweisen möchten, verwenden Sie die Microsoft-Graph-API direkt.

Die Berechtigungsverteilung dauert 30 bis über 120 Sekunden

Nachdem Sie Administratorzustimmungen für Agent-ID-Berechtigungen erteilt haben, werden neu erteilte Berechtigungen nicht sofort in Token angezeigt. Der Tokenendpunkt dient zwischengespeicherten Ansprüchen, und die Verteilung kann 30-120 Sekunden oder mehr dauern.

Das KI-geführte Setup behandelt aktuelle Berechtigungsänderungen, indem Vorgänge mit exponentiellem Backoff beim Empfang von 403 wiederholt werden. Wenn Sie dies manuell skripten, implementieren Sie die Wiederholungslogik:

# Example: Retry with backoff after admin consent
$maxRetries = 5
for ($i = 0; $i -lt $maxRetries; $i++) {
    try {
        # Attempt the operation
        $result = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 403 -and $i -lt $maxRetries - 1) {
            $wait = 20 * ($i + 1)
            Write-Host "Permission not yet propagated. Retrying in $wait seconds..."
            Start-Sleep -Seconds $wait
            # Disconnect and reconnect to force a fresh token
            Disconnect-MgGraph
            Connect-MgGraph -Scopes $scopes
        } else {
            throw
        }
    }
}

Agentidentitäten können keine Kennwortanmeldeinformationen haben

Agentidentitäten sind Dienstprinzipale ohne zugehörige Anwendungsobjekte. Der Versuch, ein passwordCredential direkt zu einer Agentidentität hinzuzufügen, führt zu:

PropertyNotCompatibleWithAgentIdentity

Anmeldeinformationen müssen für den Blueprint und nicht für einzelne Agentenidentitäten konfiguriert werden. Verwenden Sie verwaltete Identitätsverbunde (empfohlen) oder fügen Sie dem Blueprint Geheimnisse/Zertifikate hinzu, und Agentenidentitäten erben die Anmeldeinformationen durch Identitätsnachahmung.

Bezeichner-URI muss explizit festgelegt werden

Das Feld des Blueprints identifierUris ist nicht standardmäßig festgelegt. Ohne diesen Wird der OAuth2-Bereich api://{appId}/.default nicht aufgelöst, und der Tokenerwerb für den Agent schlägt fehl. Das KI-geführte Setup konfiguriert diesen Wert immer als Teil des Schritts „Bereichssetup“.

Verbundidentitätsnachweis-Pfad für Blueprints

Beim Hinzufügen von Verbundidentitätsanmeldeinformationen (FIC) für verwalteten Identitätsverbund müssen Sie den agentspezifischen API-Pfad verwenden:

POST /applications/{blueprint-obj-id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials

Die Verwendung des /applications/{id}/federatedIdentityCredentials Pfads kann möglicherweise für Agentenidentitäts-Blueprints funktionieren, wird jedoch nicht unterstützt und wird nicht empfohlen.

Tokenherausgeber variiert je nach Endpunktversion

Beachten Sie beim Überprüfen von Token im Agent-Back-End die folgenden Variationen:

• v1.0-Token verwenden Aussteller https://sts.windows.net/{tenant-id}/
• Die v2.0-Token verwenden den Aussteller https://login.microsoftonline.com/{tenant-id}/v2.0

Akzeptieren Sie beide Formate in Ihrer Tokenüberprüfungslogik.

Problembehandlung

Der KI-Agent führt keine Terminalbefehle aus

Wenn der KI-Agent Befehle beschreibt, sie aber nicht ausführt, stellen Sie sicher, dass Sie Agent-Modus in GitHub-Copilot Chat verwenden. Die Modi "fragen" und "Bearbeiten" haben keinen Terminalzugriff.

KI-Agent überspringt Validierungsschritte

Die Befehlsdatei erzwingt eine strikte Schrittreihenfolge. Wenn der KI-Agent einen Schritt überspringt, erinnern Sie ihn daran, die Anweisungen von Anfang an zu befolgen. Beispiel:

Please start from Step 1 in the setup instructions and work through each step in order.

Graph-Befehle führen zu einem 403-Verboten-Fehler

Die häufigsten Ursachen von 403 Fehlern:

• Verwenden von Azure CLI oder DefaultAzureCredential Token: Azure CLI-Token enthalten Directory.AccessAsUser.All, die Agent Identity-APIs grundsätzlich ablehnen. Verwenden Sie Connect-MgGraph mit expliziten delegierten Berechtigungsbereichen oder eine dedizierte App-Registrierung mit client_credentials. Siehe die Authentifizierungswarnung in den Voraussetzungen.
• Verzögerung der Berechtigungsverteilung: Warten Sie 1 bis 2 Minuten nach der Zustimmung des Administrators, und wiederholen Sie den Vorgang. Die KI-gestützte Einrichtung übernimmt dies automatisch mithilfe einer Wiederholungslogik.
• Fehlende Administratoreinwilligung: Überprüfen Sie, ob für die erforderlichen Berechtigungen eine Administratoreinwilligung im Microsoft Entra Admin Center unter App-Registrierungen> für Ihre Client-App >API-Berechtigungen erteilt wurde.

Der Blueprint wurde erfolgreich erstellt, gibt aber eine Standardanwendung zurück.

Dieses Ergebnis tritt auf, wenn die OData-Version: 4.0 Kopfzeile fehlt. Verwenden Sie den typisierten Endpunkt (/applications/microsoft.graph.agentIdentityBlueprint) anstelle von rohem /applications mit @odata.type, um dieses Problem zu vermeiden.

Die Erstellung der Agentidentität schlägt mit "Blueprint Principal ist nicht vorhanden" fehl.

Der Blueprint-Prinzipal muss in einem separaten Schritt nach dem Blueprint erstellt werden. Laufen:

POST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

{
  "appId": "<your-blueprint-app-id>"
}

Fehler bei Richtlinien zum Lebenszyklus von Anmeldeinformationen

Ihr Mandant verfügt möglicherweise über Richtlinien zum Lebenszyklus von Anmeldeinformationen, die die maximale Lebensdauer von Client Secrets einschränken. Wenn beim Hinzufügen eines Kennworts eine Fehlermeldung über die Lebensdauer von Anmeldeinformationen angezeigt wird, verringern Sie den endDateTime-Wert, um die Richtlinie Ihrer Organisation einzuhalten.

Konfigurationswerte müssen geändert werden

Wenn Sie konfigurationswerte nach dem Setup ändern müssen, können Sie:

• Führen Sie das KI-geführte Setup mit aktualisierten Werten erneut aus. Die idempotent-Überprüfung überspringt Ressourcen, die bereits ordnungsgemäß vorhanden sind.
• Verwenden Sie Microsoft Graph PowerShell, um bestimmte Eigenschaften mit PATCHAnforderungen zu aktualisieren.

Nächste Schritte

• Erstellen und Löschen von Agentidentitäten
• Administrative Beziehungen in der Agent-ID (Besitzer, Sponsoren und Manager)
• Agent-Identitäten, Dienstprinzipale und Anwendungen
• Konzepte des Agentidentitäts-Blueprints