Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Ein Agentidentitäts-Blueprint wird verwendet, um Agentidentitäten zu erstellen und Token mithilfe dieser Agentidentitäten anzufordern. Während des Prozesses zum Erstellen eines Agentidentitäts-Blueprints legen Sie den Besitzer und Sponsor dieses Blueprints fest, um Verantwortlichkeit und administrative Beziehungen einzurichten. Sie konfigurieren außerdem eine Bezeichner-URI und legen einen Geltungsbereich für Agents fest, die aus diesem Blueprint erstellt werden sollen, wenn der Agent dafür ausgelegt ist, eingehende Anforderungen von anderen Agents und Benutzern zu empfangen.
Sie können einen Agent-Identitäts-Blueprint auf zwei Arten erstellen:
- Microsoft Entra Admin Center – Verwenden Sie den Assistenten für eine schnelle Einrichtung, die den Blueprint und den Prinzipal erstellt.
- Microsoft Graph-API oder PowerShell – Erstellen und konfigurieren Sie den Blueprint programmgesteuert vollständig, einschließlich von Anmeldeinformationen, Bezeichner-URIs, Bereichen und der Blueprint-Hauptrolle in einem einzigen Workflow.
Voraussetzungen
Zum Erstellen eines Agentidentitäts-Blueprints benötigen Sie Folgendes:
- Privileged Role Administrator ist die am wenigsten privilegierte Rolle, die erforderlich ist, um Microsoft Graph Anwendungsberechtigungen zu erteilen.
- Cloud-Anwendungsadministrator oder Application Administrator ist erforderlich, um Microsoft Graph delegierte Berechtigungen zu erteilen.
- Sowohl die Rollen Agent-ID-Entwickler als auch Agent-ID-Administrator können Agentenidentitäts-Blueprints und Agentenidentitäts-Blueprint-Prinzipale erstellen.
- Agent ID Developer kann die Anmeldeinformationen für die Verbundidentität auf einem Agent Identity Blueprint konfigurieren.
- Der Agent-ID-Administrator kann federierte Identitätsnachweise in einem Agentenidentitäts-Blueprint konfigurieren und muss einen geheimen Schlüssel oder einen Zertifikatsnachweis hinzufügen.
- Bei Verwendung von PowerShell ist Version 7 erforderlich.
Hinweis
Besitzer eines Blueprints für Agent-Identitäten oder eines Prinzipals für Agent-Identitäten können Agent-Identitäten für diesen Blueprint ohne eine Microsoft Entra ID-Rolle erstellen. Ersteller von Agentenidentitäts-Blueprints werden automatisch als Besitzer des Blueprints und des entsprechenden Agentenidentitäts-Blueprint-Prinzipals festgelegt.
Vorbereiten der Umgebung
Um den Prozess zu optimieren, nehmen Sie sich einige Minuten Zeit, um Ihre Umgebung für die richtigen Berechtigungen einzurichten.
Autorisierung eines Clients zur Erstellung von Agentenidentitätsvorlagen
In diesem Artikel verwenden Sie Microsoft Graph PowerShell oder einen anderen Client, um Ihren Agent-Identitäts-Blueprint zu erstellen. Sie müssen diesen Client autorisieren, um einen Agent-Identity Blueprint zu erstellen und zu konfigurieren und einen Agent-Identity Blueprint Prinzipal zu erstellen. Der Client benötigt die folgenden Microsoft Graph Berechtigungen:
- AgentIdentityBlueprint.Create delegierte Berechtigung
- AgentIdentityBlueprint.AddRemoveCreds.All delegierte Berechtigung
- AgentIdentityBlueprint.UpdateAuthProperties.All delegierte Berechtigung
- AgentIdentityBlueprintPrincipal.Create delegierte Berechtigung
In den Schritten in diesem Leitfaden werden alle delegierten Berechtigungen verwendet, Sie können jedoch Anwendungsberechtigungen für diese Szenarien verwenden, für die sie erforderlich sind.
Führen Sie den folgenden Befehl aus, um eine Verbindung mit allen erforderlichen Bereichen für Microsoft Graph PowerShell herzustellen:
Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.AddRemoveCreds.All", "AgentIdentityBlueprint.UpdateAuthProperties.All", "AgentIdentityBlueprintPrincipal.Create", "User.Read" -TenantId <your-tenant-id>
Erstellen eines Agentidentitäts-Blueprints
Agentenidentitäts-Blueprints müssen einen Sponsor haben, der der Benutzer oder die unterstützte Gruppe ist, die für den Agenten verantwortlich ist. Es wird ein Besitzer empfohlen, d. h. ein Benutzer oder ein Dienstprinzipal, der Änderungen am Blueprint der Agent-Identität vornehmen kann. Weitere Informationen finden Sie unter Administrative Beziehungen in Microsoft Entra-Agent-ID.
Verwenden Sie das Microsoft Entra Admin Center
Sie können einen Agent-Identitäts-Blueprint direkt im Microsoft Entra Admin Center erstellen. Der Assistent des Administrationscenters erstellt sowohl den Blueprint für die Agent-Identität als auch den Blueprint-Principal automatisch.
Hinweis
Der Assistent des Administrationscenters legt den Namen des Blueprints fest und weist Besitzer und Sponsoren zu. Um Anmeldeinformationen, Bezeichner-URIs, Bereiche oder Berechtigungen zu konfigurieren, verwenden Sie microsoft Graph-API oder PowerShell, oder konfigurieren Sie sie nach der Erstellung über die Detailseiten des Blueprints im Admin Center.
Melden Sie sich beim Microsoft Entra Admin Center an.
Durchsuchen Sie die Entra-ID>Agents>Agent-Blueprints.
Wählen Sie "Neue Vorlage für Agenten (Vorschau)" aus.
Geben Sie auf der Registerkarte Grundlagen einen Namen in das Feld Name des Blueprints des Agents ein und wählen Sie Weiter.
Auf der Registerkarte Besitzer &Sponsoren können Sie optional Besitzer und Sponsoren für den Blueprint ändern oder hinzufügen:
- Wählen Sie das Bleistiftsymbol neben dem Feld "Besitzer " aus, um Benutzer zu ändern oder hinzuzufügen, die den Blueprint verwalten können.
- Wählen Sie das Bleistiftsymbol neben dem Feld "Sponsoren " aus, um Benutzer zu ändern oder hinzuzufügen, die den Blueprint unterstützen können.
Hinweis
Sponsoren können Benutzer, dynamische Mitgliedschaftsgruppen oder Microsoft 365 Gruppen sein. Sicherheitsgruppen und rollenzuweisungsfähige Gruppen werden nicht als Sponsoren unterstützt.
Wählen Sie Weiter aus.
Überprüfen Sie Ihre Einstellungen, und wählen Sie dann "Erstellen" aus.
Wählen Sie "Fertig " aus, um den Assistenten zu beenden oder zum Agent-Blueprint zu wechseln , um die Detailseite des Blueprints anzuzeigen oder weitere Einstellungen zu konfigurieren.
Weitere Informationen zum Verwalten von Agentidentitäts-Blueprints finden Sie unter Verwalten von Agentidentitäts-Blueprints.
Programmatisch erstellen
Verwenden Sie microsoft Graph-API oder PowerShell, um einen Agentidentitäts-Blueprint mithilfe von Code zu erstellen.
Dieser Schritt erstellt den Agentidentitäts-Blueprint, weist einen Besitzer und Sponsor zu und erfordert die folgenden Details:
- Die
AgentIdentityBlueprint.CreateBerechtigung. - Der OData-Version-Header muss auf 4.0 festgelegt werden.
- Eine Benutzer-ID für die Felder "Besitzer" und "Sponsor" im Beispielanforderungstext. Ein Sponsor ist erforderlich, aber ein Besitzer ist optional.
POST https://graph.microsoft.com/v1.0/applications/
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
{
"@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
"displayName": "My Agent Identity Blueprint",
"sponsors@odata.bind": [
"https://graph.microsoft.com/v1.0/users/<id>"
],
"owners@odata.bind": [
"https://graph.microsoft.com/v1.0/users/<id>"
]
}
Notieren Sie sich nach dem Erstellen des Blueprints der Agentenidentität den Wert des appId für den nächsten Schritt.
Konfigurieren von Anmeldeinformationen für das Blueprint der Agent-Identität
Um Access-Token mithilfe des Agentidentitäts-Blueprints anzufordern, müssen Sie eine Client-Anmeldeinformation hinzufügen. Es wird empfohlen, eine verwaltete Identität als federierte Identitätsanmeldeinformationen (FIC) für Produktionsumgebungen zu verwenden. Mit verwalteten Identitäten können Sie Microsoft Entra Token abrufen, ohne Anmeldeinformationen verwalten zu müssen. Weitere Informationen finden Sie unter Managed identities for Azure resources.
Andere Arten von App-Anmeldeinformationen, einschließlich keyCredentials und passwordCredentials werden unterstützt, aber nicht für die Produktion empfohlen. Sie können für lokale Entwicklung und Tests geeignet sein oder verwaltete Identitäten funktionieren nicht, aber diese Optionen entsprechen nicht den bewährten Methoden der Sicherheit. Weitere Informationen finden Sie unter "Bewährte Methoden für Sicherheit" für Anwendungseigenschaften.
Beachten Sie, dass Sie zum Verwenden einer verwalteten Identität Ihren Code auf einem Azure Dienst ausführen müssen, z. B. auf einem virtuellen Computer oder Azure App Service. Verwenden Sie für lokale Entwicklung und Tests einen geheimen Clientschlüssel oder ein Zertifikat.
So senden Sie diese Anforderung:
- Sie benötigen die Berechtigung
AgentIdentityBlueprint.AddRemoveCreds.All. - Ersetzen Sie den
<agent-blueprint-id>-Platzhalter durch denappIddes Blueprints für die Agent-Identität. - Ersetzen Sie den
<managed-identity-principal-id>Platzhalter durch die ID Ihrer verwalteten Identität.
Fügen Sie eine verwaltete Identität als Berechtigungsnachweis mithilfe der folgenden Anforderung hinzu:
POST https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>/federatedIdentityCredentials
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
{
"name": "my-managed-identity",
"issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
"subject": "<managed-identity-principal-id>",
"audiences": [
"api://AzureADTokenExchange"
]
}
Andere App-Anmeldeinformationen
Für Szenarien, in denen verwaltete Identitäten nicht funktionieren oder wenn Sie einen Blueprint lokal zum Testen erstellen, führen Sie die folgenden Schritte aus, um die Anmeldeinformationen hinzuzufügen.
Um diese Anforderung zu senden, müssen Sie zuerst ein Zugriffstoken mit der delegierten Berechtigung AgentIdentityBlueprint.AddRemoveCreds.All erhalten.
POST https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>/addPassword
Content-Type: application/json
Authorization: Bearer <token>
{
"passwordCredential": {
"displayName": "My Secret",
"endDateTime": "2026-08-05T23:59:59Z"
}
}
Hinweis
Ihr Mandant verfügt möglicherweise über Richtlinien zum Lebenszyklus von Anmeldeinformationen, die die maximale Lebensdauer von Client Secrets einschränken. Wenn Sie eine Fehlermeldung über die Lebensdauer von Anmeldeinformationen erhalten, verringern Sie den endDateTime-Wert, um ihn an die Richtlinie Ihrer Organisation anzupassen.
Achten Sie darauf, die passwordCredential generierten Werte sicher zu speichern. Sie kann nach der ersten Erstellung nicht angezeigt werden. Sie können Clientzertifikate auch als Anmeldeinformationen verwenden; siehe Hinzufügen von Zertifikatanmeldeinformationen.
Wenn die mit dem Blueprint erstellten Agents interaktive Agents unterstützen, bei denen der Agent im Namen eines Benutzers agiert, muss Ihr Blueprint einen Bereich verfügbar machen, damit das Agent-Front-End ein Zugriffstoken an das Agent-Back-End übergeben kann. Dieses Token kann dann vom Agent-Back-End verwendet werden, um ein Zugriffstoken abzurufen und im Auftrag des Benutzers zu handeln.
Konfigurieren des Bezeichner-URI und -Bereichs
Um eingehende Anfragen von Benutzern und anderen Agents zu empfangen, müssen Sie wie bei jeder Web-API einen Identifier-URI und einen OAuth-Bereich für Ihr Blueprint für Agent-Identitäten definieren:
So senden Sie diese Anforderung:
- Sie benötigen die Berechtigung
AgentIdentityBlueprint.UpdateAuthProperties.All. - Ersetzen Sie den
<agent-blueprint-id>-Platzhalter durch denappIddes Blueprints für die Agent-Identität. - Sie benötigen eine GUID (Globally Unique Identifier). Führen Sie in PowerShell
[guid]::NewGuid()aus oder verwenden Sie einen Online-GUID-Generator. Kopieren Sie die generierte GUID, und verwenden Sie sie, um den<generate-a-guid>Platzhalter zu ersetzen.
PATCH https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
{
"identifierUris": ["api://<agent-blueprint-id>"],
"api": {
"oauth2PermissionScopes": [
{
"adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
"adminConsentDisplayName": "Access agent",
"id": "<generate-a-guid>",
"isEnabled": true,
"type": "User",
"value": "access_agent"
}
]
}
}
Ein erfolgreicher Anruf generiert eine 204-Antwort.
Erstellen eines Agenten-Hauptentwurfs
In diesem Schritt erstellen Sie einen Prinzipal für den Blueprint der Agent-Identität. Weitere Informationen finden Sie unter Agentidentitäten, Dienstprinzipale und Anwendungen.
Ersetzen Sie den <agent-blueprint-app-id> Platzhalter durch das appId, das Sie aus den Ergebnissen des vorherigen Schritts kopiert haben.
POST https://graph.microsoft.com/v1.0/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
{
"appId": "<agent-blueprint-app-id>"
}
Ihr Agent-Blueprint ist jetzt im Microsoft Entra Admin Center bereit und sichtbar. Im nächsten Schritt verwenden Sie diesen Blueprint zum Erstellen von Agentidentitäten.
Registrieren von Agents in der Agent 365-Registrierung
Nachdem Sie einen Agentidentitäts-Blueprint erstellt haben, registrieren Sie ihn im Agent 365-Registrierung damit Administratoren den Agent aus dem Microsoft 365 Admin Center ermitteln, steuern und verwalten können. Dieser Abschnitt enthält auch Anweisungen zum Hinzufügen vorhandener Agent-Identitätsvorlagen, die möglicherweise nicht in der Agent-365-Registrierung angezeigt werden.
Verwenden des Microsoft 365 Agents SDK (empfohlen)
Die Microsoft 365 Agents SDK ist jetzt allgemein verfügbar und ist die empfohlene Methode zum Erstellen und Bereitstellen von Agents. Das SDK Behandelt die Agentidentitätserstellung und -registrierung in der Agent 365-Registrierung für Sie, sodass Ihre Agentidentitäten automatisch ohne zusätzlichen Code angezeigt werden. Wenn Sie ein neues Agentprojekt starten oder flexibilität zum Migrieren vorhandener Code haben, verwenden Sie das SDK. Es ist der einfachste, langlebigste Pfad und vermeidet die Notwendigkeit, mehrere API-Aufrufe selbst zu koordinieren.
Verwenden Sie die Agent 365 CLI
Die Agent 365 CLI ist eine weitere Option, die die Einrichtung für Sie übernimmt, einschließlich der Agentenregistrierung. Folgen Sie den Setupanweisungen mithilfe der empfohlenen Ausführungsreihenfolge. Verwenden Sie den folgenden Befehl:
a365 setup all
Wenn die Registrierung fehlschlägt, können Sie nur den Registrierungsschritt erneut ausführen, ohne den gesamten Prozess durchlaufen zu müssen. Verwenden Sie den folgenden Befehl:
a365 setup all --agent-registration-only
Direktes Aufrufen der Agent-Registrierungs-API
Wenn Sie Agentidentitäts-Blueprints programmgesteuert mit dem Microsoft Graph-API erstellen müssen, z. B. weil Sie über vorhandene Identitätsausstellungsworkflows verfügen, die Sie nicht sofort ändern können, müssen Sie einen expliziten Aufruf der Agent-Registrierungs-API after erstellen, um den Agentidentitäts-Blueprint zu erstellen, um die entsprechende Agentkarte zu veröffentlichen. In diesem Schritt wird die Agentkarte in der Agent 365-Registrierung registriert, sodass sie für Administratoren angezeigt wird.
- Erstellen Sie den Agent-Identitäts-Blueprint mithilfe der Microsoft Graph-API (wie in den vorherigen Abschnitten dargestellt).
- Führen Sie sofort einen Aufruf der Agenten-Registrierungs-API durch, um die entsprechende Agentenkarte zu veröffentlichen, einschließlich der Metadaten, die Ihre Administratoren zur Verwaltung benötigen.
- Behandeln Sie das Muster von zwei Aufrufen wiederholungssicher, sodass Ihre Umgebung bei einem vorübergehender Fehler bei einem der Aufrufe in einem wiederherstellbaren Zustand bleibt.
Informationen zu Anforderungs- und Antwortschemas, erforderlichen Berechtigungen und Codebeispielen finden Sie in der Referenz zur Agentregistrierungs-API.
Tip
Wenn Sie über vorhandene Agenten-Identitätsentwürfe verfügen, die nicht im Agent 365-Register angezeigt werden, registrieren Sie diese mithilfe der API zur Agentenregistrierung. Verwenden Sie für Agentidentitäts-Blueprints in großen Mengen den Batch-Endpunkt. Weitere Informationen finden Sie unter Agent Registry convergence with Microsoft Agent 365.
Vorhandene Agentidentitäts-Blueprints, die nicht in der Agent 365-Registrierung enthalten sind
Für Agentidentitäts-Blueprints, die zuvor mithilfe der Microsoft Entra-Agent-ID Graph-API erstellt wurden, aber derzeit nicht in der Agent 365-Registrierung sichtbar sind, können Sie sie mithilfe der Agent-Registrierungs-API registrieren. Dieser Schritt stellt sicher, dass sie in der Agent 365-Registrierung angezeigt werden.
Löschen eines Agentidentitäts-Blueprints
Wenn ein Agent außer Betrieb genommen wird, löschen Sie den zugehörigen Agent-Identitäts-Blueprint. Das Löschen des Blueprints löst eine automatische Bereinigung aller untergeordneten Agent-Identitäten und Benutzerkonten der Agents aus. Schrittweise Lösch- und Wiederherstellungsanweisungen finden Sie unter Löschen und Wiederherstellen von Agent-Identitätsobjekten.