Een blauwdruk voor een agentidentiteit maken

Een blauwdruk voor de agentidentiteit wordt gebruikt om agentidentiteiten te maken en tokens met deze agentidentiteiten aan te vragen. Tijdens het proces voor het maken van een agentidentiteitsblauwdruk stelt u de eigenaar en sponsor van die blauwdruk in om verantwoordelijkheidsrelaties en administratieve relaties tot stand te brengen. U configureert ook een id-URI en definieert een bereik voor agents die op basis van deze blauwdruk zijn gemaakt als de agent is ontworpen voor het ontvangen van binnenkomende aanvragen van andere agents en gebruikers.

U kunt een blauwdruk voor de agentidentiteit op twee manieren maken:

• Microsoft Entra-beheercentrum: gebruik de wizard voor een snelle installatie waarmee de blauwdruk en de principal worden gemaakt.
• Microsoft Graph API of PowerShell — creëer en programmeer de blauwdruk programmatisch en beheer deze volledig, inclusief verificatiegegevens, id-URI's, toepassingsbereiken en de principaal van de blauwdruk in één werkstroom.

Vereiste voorwaarden

Als u een blauwdruk voor een agentidentiteit wilt maken, hebt u het volgende nodig:

• Privileged Role Administrator rol is de minst bevoorrechte rol die is vereist om Microsoft Graph toepassingsmachtigingen te verlenen.
• Cloud-toepassingsbeheerder of Toestemmingsbeheerder is vereist om Microsoft Graph gedelegeerde machtigingen te verlenen.
• De rollen Agent-id Developer en Agent ID Administrator kunnen blauwdrukken voor agentidentiteit en blauwdruk-principals voor agentidentiteiten maken.
  • Agent ID Developer kan geconfigureerde federatieve identiteitsreferenties toevoegen aan een blauwdruk van de agentidentiteit.
  • Agent-id-beheerder kan federatieve identiteitsreferenties configureren op een blauwdruk voor de agentidentiteit en is vereist om een geheime of certificaatreferentie toe te voegen.
• Als u PowerShell gebruikt, is versie 7 vereist.

Uw omgeving voorbereiden

Neem even de tijd om uw omgeving in te stellen voor de juiste machtigingen en zo het proces te stroomlijnen.

Een cliënt autoriseren om blauwdrukken voor een agentidentiteit te maken

In dit artikel gebruikt u Microsoft Graph PowerShell of een andere client om uw blauwdruk voor de agentidentiteit te maken. U moet deze client autoriseren voor het maken en configureren van een blauwdruk voor de agentidentiteit en het maken van een blauwdrukprincipaal voor de agentidentiteit. Voor de client zijn de volgende Microsoft Graph machtigingen vereist:

• Gedelegeerde machtiging AgentIdentityBlueprint.Create
• AgentIdentityBlueprint.AddRemoveCreds.All gedelegeerde machtiging
• AgentIdentityBlueprint.UpdateAuthProperties.All gedelegeerde machtiging
• AgentIdentityBlueprintPrincipal.Gedelegeerde machtiging maken

In de stappen in deze handleiding worden alle gedelegeerde machtigingen gebruikt, maar u kunt toepassingsmachtigingen gebruiken voor deze scenario's waarvoor ze zijn vereist.

Voer de volgende opdracht uit om verbinding te maken met alle vereiste machtigingen voor Microsoft Graph PowerShell.

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.AddRemoveCreds.All", "AgentIdentityBlueprint.UpdateAuthProperties.All", "AgentIdentityBlueprintPrincipal.Create", "User.Read" -TenantId <your-tenant-id>

Een blauwdruk voor een agentidentiteit maken

Blauwdrukken voor agentidentiteiten moeten een sponsor hebben, namelijk de gebruiker of de ondersteunde groep die verantwoordelijk is voor de agent. Een eigenaar wordt aanbevolen. Dit is de gebruiker of service-principal die wijzigingen kan aanbrengen in de blauwdruk voor de agentidentiteit. Zie Administratieve relaties in Microsoft Entra Agent-ID voor meer informatie.

De Microsoft Entra-beheercentrum gebruiken

U kunt een blauwdruk voor de agentidentiteit rechtstreeks in de Microsoft Entra-beheercentrum maken. De beheerderscentrumwizard maakt automatisch zowel de blauwdruk voor de agentidentiteit als de hoofdblauwdruk.

1. Meld u aan bij het Microsoft Entra-beheercentrum.

2. Navigeer naar Entra ID>Agents>Agent blauwdrukken.

3. Selecteer Nieuwe agent blauwdruk (Preview).

4. Voer op het tabblad Basisinformatie een naam in het veld Blauwdruknaam van agent in en selecteer Volgende.

   

5. Op het tabblad Eigenaren en sponsors kunt u desgewenst eigenaren en sponsors wijzigen of toevoegen aan de blauwdruk:

   • Selecteer het potloodpictogram naast het veld Eigenaren om gebruikers te wijzigen of toe te voegen die de blauwdruk kunnen beheren.
   • Selecteer het potloodpictogram naast het veld Sponsors om gebruikers te wijzigen of toe te voegen die de blauwdruk kunnen sponsoren.

   Opmerking

   Sponsors kunnen gebruikers, dynamische lidmaatschapsgroepen of Microsoft 365 groepen zijn. Beveiligingsgroepen en roltoewijzingsgroepen worden niet ondersteund als sponsors.

6. Selecteer Volgende.

7. Controleer uw instellingen en selecteer Aanmaken.

8. Selecteer Gereed om de wizard af te sluiten of ga naar de blauwdruk van de agent om de detailpagina van de blauwdruk weer te geven of configureer meer instellingen.

Zie Beheer van blauwdrukken voor agentidentiteiten voor meer informatie over het beheren van blauwdrukken voor agentidentiteiten.

Programmatisch maken

Als u een blauwdruk voor een agentidentiteit wilt maken met behulp van code, gebruikt u de Microsoft Graph API of PowerShell.

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>"
  ],
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create","User.Read" -TenantId <your-tenant-id>

$currentUser = Get-MgContext | Select-Object -ExpandProperty Account
$user = Get-MgUser -UserId $currentUser

Write-Host "Current user: $($user.DisplayName) ($($user.Id))"
Write-Host "Sponsor user: $($user.DisplayName) ($($user.Id))"


$body = @{
    "@odata.type" = "Microsoft.Graph.AgentIdentityBlueprint"
    "displayName" = "My Agent Identity Blueprint"
    "sponsors@odata.bind" = @("https://microsoft.graph.microsoft.com/v1.0/users/$($user.Id)")
    "owners@odata.bind" = @("https://microsoft.graph.microsoft.com/v1.0/users/$($user.Id)")
} | ConvertTo-Json -Depth 5

$response = Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprint" `
    -Body $body `
    -ContentType "application/json"

$response

Referenties configureren voor de blauwdruk voor de identiteit van de agent

Als u toegangstokens wilt aanvragen met behulp van de blauwdruk voor de agentidentiteit, moet u een clientreferentie toevoegen. U wordt aangeraden een beheerde identiteit te gebruiken als federatieve identiteitsreferentie (FIC) voor productie-implementaties. Met beheerde identiteiten kunt u Microsoft Entra tokens verkrijgen zonder referenties te hoeven beheren. Zie Beheerde identiteiten voor Azure resources voor meer informatie.

Andere soorten app-referenties, waaronder keyCredentials en passwordCredentials worden ondersteund, maar niet aanbevolen voor productie. Ze kunnen handig zijn voor lokale ontwikkeling en testen of waar beheerde identiteiten niet werken, maar deze opties zijn niet afgestemd op aanbevolen beveiligingsprocedures. Zie de aanbevolen beveiligingsprocedures voor toepassingseigenschappen voor meer informatie.

Als u een beheerde identiteit wilt gebruiken, moet u uw code uitvoeren op een Azure-service, zoals een virtuele machine of Azure App Service. Gebruik een clientgeheim of certificaat voor lokale ontwikkeling en testen.

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"
    ]
}

Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId <your-tenant-id>

$applicationId = "<agent-blueprint-id>"

$federatedCredential = @{
  Name             = "my-managed-identity"
  Issuer           = "https://login.microsoftonline.com/<your-tenant-id>/v2.0"
  Subject          = "<managed-identity-principal-id>"
  Audiences         = @("api://AzureADTokenExchange")
}

New-MgApplicationFederatedIdentityCredential `
  -ApplicationId $applicationId `
  -BodyParameter $federatedCredential

Andere app-referenties

Voor scenario's waarin beheerde identiteiten niet werken of als u een blauwdruk lokaal maakt voor testen, gebruikt u de volgende stappen om de referenties toe te voegen.

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"
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId <your-tenant-id>

$applicationId = "<agent-blueprint-application-id>"

# Define the secret properties
$displayName = "My Secret"
$endDate = (Get-Date).AddYears(1).ToString("o")  # 1 year from now, in ISO 8601 format

# Construct the password credential
$passwordCredential = @{
    displayName = $displayName
    endDateTime = $endDate
}

# Add the password (client secret)
$response = Add-MgApplicationPassword -ApplicationId $applicationId -PasswordCredential $passwordCredential

# Output the generated secret (only returned once!)
Write-Host "Secret Text: $($response.secretText)"

Zorg ervoor dat u de passwordCredential gegenereerde waarden veilig opslaat. Het kan niet worden weergegeven na de oorspronkelijke creatie. U kunt ook clientcertificaten als referenties gebruiken; zie Een certificaatreferentie toevoegen.

Als de agents die zijn gemaakt met de blauwdruk interactieve agents ondersteunen, waarbij de agent namens een gebruiker handelt, moet uw blauwdruk een bereik beschikbaar maken, zodat de front-end van de agent een access token kan doorgeven aan de back-end van de agent. Dit token kan vervolgens worden gebruikt door de back-end van de agent om een toegangstoken op te halen om namens de gebruiker te handelen.

Id-URI en bereik configureren

Als u binnenkomende aanvragen van gebruikers en andere agents wilt ontvangen, zoals voor elke web-API, moet u een id-URI en OAuth-bereik definiëren voor de blauwdruk voor uw agentidentiteit:

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"
        }
      ]
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.UpdateAuthProperties.All" -TenantId <your-tenant-id>

$AppId = "<agent-blueprint-id>"
$IdentifierUri = "api://<agent-blueprint-id>"
$ScopeId = [guid]::NewGuid()

# Construct the OAuth2 permission scope
$scope = @{
    adminConsentDescription = "Allow the application to access the agent on behalf of the signed-in user."
    adminConsentDisplayName = "Access agent"
    id = $ScopeId
    isEnabled = $true
    type = "User"
    value = "access_agent"
}

Update-MgApplication -ApplicationId $AppId `
    -IdentifierUris @($IdentifierUri) `
    -Api @{ oauth2PermissionScopes = @($scope) }

Een hoofdelement van de blauwdruk voor een agent maken

In deze stap maakt u een hoofdaccount aan voor de blauwdruk van de agentidentiteit. Zie Agent-identiteiten, service-principals en toepassingen voor meer informatie.

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>"
}

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId
$body = @{
    appId   = "<agent-blueprint-client-id>"
}
Invoke-MgGraphRequest -Method POST `
        -Uri "https://graph.microsoft.com/v1.0/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

Uw agentblauwdruk is nu gereed en zichtbaar in de Microsoft Entra-beheercentrum. In de volgende stap gebruikt u deze blauwdruk om agentidentiteiten te maken.

Agents registreren in het register agent 365

Nadat u een blauwdruk voor de agentidentiteit hebt gemaakt, registreert u deze in het register Agent 365 zodat beheerders de agent kunnen detecteren, beheren en beheren vanuit de Microsoft 365-beheercentrum. In deze sectie vindt u ook instructies voor het toevoegen van bestaande blauwdrukken voor agentidentiteiten die momenteel niet worden weergegeven in het register agent 365.

De SDK voor Microsoft 365-agenten gebruiken (aanbevolen)

De SDK voor Microsoft 365-agenten is nu algemeen beschikbaar en is de aanbevolen manier om agents te bouwen en in te richten. De SDK De SDK verwerkt het maken en registreren van agentidentiteiten in het register agent 365 voor u, zodat uw agentidentiteiten automatisch worden weergegeven zonder extra code. Als u een nieuw agentproject start of flexibiliteit hebt om bestaande code te migreren, gebruikt u de SDK. Het is het eenvoudigste, meest duurzame pad en voorkomt dat u zelf meerdere API-aanroepen hoeft te coördineren.

De Agent 365 CLI gebruiken

De Agent 365 CLI is een andere optie die de installatie voor u afhandelt, inclusief agentregistratie. Volg de installatie-instructies met behulp van de aanbevolen uitvoeringsvolgorde. Gebruik de volgende opdracht:

a365 setup all

Als de registratie mislukt, kunt u alleen de registratiestap opnieuw uitvoeren zonder dat u het hele proces hoeft te doorlopen. Gebruik de volgende opdracht:

a365 setup all --agent-registration-only

De agentregister-API rechtstreeks aanroepen

Als u agentidentiteitsblauwdrukken programmatisch moet maken met microsoft Graph API, bijvoorbeeld omdat u bestaande werkstromen voor identiteitsuitgifte hebt die u niet onmiddellijk kunt wijzigen, moet u een expliciete aanroep toevoegen aan de Register-API van agent na het maken van de blauwdruk voor de agentidentiteit om de bijbehorende agentkaart te posten. Met deze stap wordt de agentkaart geregistreerd in het register agent 365, zodat deze voor beheerders wordt weergegeven.

1. Maak de blauwdruk voor de agentidentiteit met behulp van de Microsoft Graph API (zoals weergegeven in de vorige secties).
2. Doe onmiddellijk een aanroep naar de Agent Registry API om de bijbehorende agentkaart te posten, inclusief de metagegevens die uw beheerders nodig hebben voor het beheer ervan.
3. Verwerk het patroon voor twee aanroepen op een herhaalveilige manier, zodat een tijdelijke fout bij een van beide aanroepen uw omgeving in een herstelbare status achterlaat.

Zie de naslaginformatie over de agentregister-API voor aanvragen en antwoordschema's, vereiste machtigingen en codevoorbeelden.

Bestaande agentidentiteitsblauwdrukken die zich niet in het Agent 365-register bevinden

Voor agentidentiteitsblauwdrukken die eerder zijn gemaakt met behulp van de Microsoft Entra Agent-ID Graph API, maar die momenteel niet zichtbaar zijn in het register agent 365, kunt u deze registreren met behulp van de agentregister-API. Deze stap zorgt ervoor dat ze worden weergegeven in het register agent 365.

Een blauwdruk voor de agentidentiteit verwijderen

Wanneer een agent buiten gebruik wordt gesteld, verwijdert u de bijbehorende blauwdruk voor de agentidentiteit. Door de blauwdruk te verwijderen, worden alle bijbehorende agentidentiteiten en agentgebruikersaccounts automatisch opgeschoond. Zie Identiteitsobjecten voor agent verwijderen en herstellen voor stapsgewijze instructies.

Volgende stap