Creare un progetto di identità dell'agente

Un progetto di identità agente viene usato per creare identità dell'agente e richiedere token usando tali identità dell'agente. Durante il processo di creazione di un progetto di identità agente, impostare il proprietario e lo sponsor di tale progetto per stabilire relazioni amministrative e di responsabilità. È anche possibile configurare un URI di identificatore e definire un ambito per gli agenti creati da questo progetto se l'agente è progettato per ricevere richieste in ingresso da altri agenti e utenti.

È possibile creare un progetto di identità agente in due modi:

Interfaccia di amministrazione di Microsoft Entra: usare la procedura guidata per una configurazione rapida che crea il progetto e la relativa entità.
Microsoft API Graph o PowerShell: creare e configurare completamente il progetto a livello di codice, incluse le credenziali, gli URI dell'identificatore, gli ambiti e l'entità progetto in un singolo flusso di lavoro.

Prerequisiti

Per creare un progetto di identità dell'agente, è necessario:

Amministratore dei ruoli privilegiati è il ruolo con i privilegi minimi necessario per concedere autorizzazioni dell'applicazione di Microsoft Graph.
Amministratore delle applicazioni cloud o Amministratore delle applicazioni deve concedere le autorizzazioni delegate per Microsoft Graph.
Entrambi i ruoli di Sviluppatore ID Agente e di Amministratore ID Agente possono creare modelli di identità agente e principali di modelli di identità agente.
- Lo sviluppatore id agente può configurare le credenziali di identità federate in un progetto di identità agente.
- L'Amministratore ID Agente può configurare le credenziali di identità federate in un modello di identità agente ed è tenuto ad aggiungere una credenziale segreta o un certificato.
Se si usa PowerShell, è necessaria la versione 7.

Annotazioni

I proprietari di un blueprint di identità agente o un principale del blueprint di identità agente possono creare identità dell'agente per tale blueprint senza che venga richiesto un ruolo Microsoft Entra Agent ID. I creatori di modelli di identità dell'agente sono impostati automaticamente come proprietari sia del modello che del principale di modello di identità dell'agente associato.

Prepara il tuo ambiente

Per semplificare il processo, dedicare alcuni istanti per configurare l'ambiente per le autorizzazioni appropriate.

Autorizzare un client a creare modelli di identità dell'agente

In questo articolo si usa Microsoft Graph PowerShell o un altro client per creare il progetto di identità dell'agente. È necessario autorizzare questo client a creare e configurare un blueprint di identità agente e creare un principale del blueprint di identità agente. Il client richiede le autorizzazioni di Microsoft Graph seguenti:

I passaggi descritti in questa guida usano tutte le autorizzazioni delegate, ma è possibile usare le autorizzazioni dell'applicazione per gli scenari che li richiedono.

Per connettersi a tutti gli ambiti necessari per Microsoft Graph PowerShell, eseguire il comando seguente:

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

Creare un progetto di identità dell'agente

I progetti di identità dell'agente devono avere uno sponsor, ovvero l'utente o il gruppo supportato che è responsabile dell'agente. È consigliabile avere un proprietario, che sia l'utente o il principale del servizio in grado di apportare modifiche allo schema identità dell'agente. Per informazioni, vedere Relazioni amministrative in Microsoft Entra Agent ID.

Usare il Interfaccia di amministrazione di Microsoft Entra

È possibile creare un progetto di identità agente direttamente nel Interfaccia di amministrazione di Microsoft Entra. La procedura guidata del centro di amministrazione crea automaticamente sia il modello di identità dell'agente che il principale del modello.

Annotazioni

La procedura guidata dell'interfaccia di amministrazione imposta il nome del progetto e assegna proprietari e sponsor. Per configurare credenziali, URI identificatori, ambiti o autorizzazioni, usare Microsoft API Graph o PowerShell oppure configurarli dopo la creazione tramite le pagine di dettagli del progetto nell'interfaccia di amministrazione.

Accedi all'interfaccia di amministrazione di Microsoft Entra.
Passare a Entra ID>Agenti>Blueprint degli agenti.
Selezionare Nuovo progetto agente (anteprima).
Nella scheda Informazioni di base immettere un nome nel campo Nome progetto Agente e selezionare Avanti.
Nella scheda Proprietari e sponsor , facoltativamente, modificare o aggiungere proprietari e sponsor per il progetto:
- Selezionare l'icona a forma di matita accanto al campo Proprietari per modificare o aggiungere utenti che possono gestire il progetto.
- Selezionare l'icona a forma di matita accanto al campo Sponsors per modificare o aggiungere utenti che possono sponsorizzare il progetto.
Annotazioni

Gli sponsor possono essere utenti, gruppi di appartenenze dinamici o gruppi di Microsoft 365. I gruppi di sicurezza e i gruppi assegnabili a ruoli non sono supportati in qualità di sponsor.
Selezionare Avanti.
Esaminare le impostazioni e quindi selezionare Crea.
Selezionare Fine per uscire dalla procedura guidata o Passare al progetto agente per visualizzare la pagina dei dettagli del progetto o configurare altre impostazioni.

Per altre informazioni sulla gestione dei progetti di identità dell'agente, vedere Gestire i progetti di identità dell'agente.

Creare programmaticamente

Per creare un progetto di identità agente usando il codice, usare Microsoft API Graph o PowerShell.

Microsoft API Graph
Microsoft Graph PowerShell

Questo passaggio crea il progetto di identità dell'agente, assegna un proprietario e uno sponsor e richiede i dettagli seguenti:

Autorizzazione AgentIdentityBlueprint.Create .
L'intestazione OData-Version deve essere impostata su 4.0.
ID utente per i campi proprietario e sponsor nel corpo della richiesta di esempio. Uno sponsor è obbligatorio, ma un proprietario è facoltativo.

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

Dopo aver creato il progetto di identità dell'agente, annotare il valore di appId per il passaggio successivo.

Questo passaggio crea l'applicazione del progetto di identità dell'agente usando l'utente corrente come proprietario e sponsor e include le attività distinte seguenti:

Connettiti al tenant con gli ambiti AgentIdentityBlueprint.Create e User.Read.
Aggiunge l'utente corrente come sponsor e proprietario del modello d'identità dell'agente.
Creare l'applicazione dello schema di identità dell'agente.

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

Dopo aver creato il progetto di identità dell'agente, registrare il valore di appId dall'output.

Configurare le credenziali per il progetto di identità dell'agente

Per richiedere token access usando il progetto di identità dell'agente, è necessario aggiungere una credenziale client. Si consiglia di utilizzare una managed identity come credenziale di identità federata (FIC) per le distribuzioni in produzione. Le identità gestite consentono di ottenere Microsoft Entra token senza dover gestire le credenziali. Per altre informazioni, vedere Identità gestite per le risorse Azure.

Altri tipi di credenziali dell'app, inclusi keyCredentials e passwordCredentials , sono supportati, ma non consigliati per la produzione. Possono essere utili per lo sviluppo e il test locali o dove le identità gestite non sono funzionali, ma queste opzioni non sono allineate alle migliori pratiche di sicurezza. Per ulteriori informazioni, vedere le migliori pratiche di sicurezza per le proprietà dell'applicazione.

Tenere presente che per usare un'identità gestita è necessario eseguire il codice in un servizio Azure, ad esempio una macchina virtuale o Servizio app di Azure. Per lo sviluppo e il test locali, usare un segreto client o un certificato.

Microsoft API Graph
Microsoft Graph PowerShell

Per inviare questa richiesta:

È necessaria l'autorizzazione AgentIdentityBlueprint.AddRemoveCreds.All.
Sostituire il segnaposto <agent-blueprint-id> con il blueprint di identità dell'agente appId.
Sostituire il <managed-identity-principal-id> segnaposto con l'ID dell'identità gestita.

Aggiungere un'identità gestita come credenziale usando la richiesta seguente:

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

Questo passaggio include le attività distinte seguenti:

Collegati al tuo tenant con l'ambito AgentIdentityBlueprint.AddRemoveCreds.All.
Aggiungere un'identità gestita come credenziale per il blueprint di identità dell'agente utilizzando il principale del blueprint di identità dell'agente creato in precedenza.

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

Altre credenziali dell'app

Per gli scenari in cui le identità gestite non funzioneranno o se si sta creando un progetto in locale per il test, seguire questa procedura per aggiungere le credenziali.

Microsoft API Graph
Microsoft Graph PowerShell

Per inviare questa richiesta, è prima necessario ottenere un token di accesso con l'autorizzazione delegata AgentIdentityBlueprint.AddRemoveCreds.All

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

Annotazioni

Il tenant potrebbe avere criteri relativi al ciclo di vita delle credenziali che limitano la durata massima per i segreti client. Se viene visualizzato un errore relativo alla durata delle credenziali, ridurre il valore endDateTime per allinearsi alla policy aziendale.

Assicurarsi di archiviare in modo sicuro i passwordCredential valori generati. Non può essere visualizzato dopo la creazione iniziale. È anche possibile usare i certificati client come credenziali; vedere Aggiungere una credenziale del certificato.

Se gli agenti creati con il progetto supporteranno agenti interattivi, in cui l'agente agisce per conto di un utente, il progetto deve esporre un ambito in modo che il front-end dell'agente possa passare un token di accesso al back-end dell'agente. Questo token può quindi essere utilizzato dal back-end dell'agente per ottenere un token di accesso che agisca per conto dell'utente.

Configurare l'URI e l'ambito dell'identificatore

Per ricevere richieste in ingresso da utenti e altri agenti, ad esempio per qualsiasi API Web, è necessario definire un URI di identificatore e un ambito OAuth per il progetto di identità dell'agente:

Microsoft API Graph
Microsoft Graph PowerShell

Per inviare questa richiesta:

È necessaria l'autorizzazione AgentIdentityBlueprint.UpdateAuthProperties.All.
Sostituire il segnaposto <agent-blueprint-id> con il blueprint di identità dell'agente appId.
È necessario un identificatore univoco globale (GUID). In PowerShell eseguire [guid]::NewGuid() o usare un generatore GUID online. Copiare il GUID generato e usarlo per sostituire il <generate-a-guid> segnaposto.

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

Una chiamata con esito positivo genera una risposta 204.

Questo passaggio include le attività distinte seguenti:

Installare il modulo obbligatorio se non è già stato fatto.
Collegati al tuo tenant con l'ambito AgentIdentityBlueprint.UpdateAuthProperties.All.
Configurare l'URI e l'ambito per il nuovo modello di identità dell'agente.

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

Creare un modello principale per l'agente

In questo passaggio si crea un'entità per il progetto di identità dell'agente. Per altre informazioni, vedere Identità dell'agente, entità servizio e applicazioni.

Microsoft API Graph
Microsoft Graph PowerShell

Sostituire il <agent-blueprint-app-id> segnaposto con l'oggetto appId copiato dai risultati del passaggio precedente.

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

Dopo aver creato il progetto blueprint dell'identità dell'agente, crea un'entità principale del blueprint dell'identità dell'agente utilizzando il blueprint dell'identità dell'agente appena creato appId.

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId <your-tenant-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)

Il progetto agente è ora pronto e visibile nel Interfaccia di amministrazione di Microsoft Entra. Nel passaggio successivo si userà questo progetto per creare identità dell'agente.

Registrare gli agenti nel Registro di sistema di Agent 365

Dopo aver creato un progetto di identità agente, registrarlo nel registro Agent 365 in modo che gli amministratori possano individuare, gestire e gestire l'agente dal interfaccia di amministrazione di Microsoft 365. Questa sezione fornisce anche istruzioni per aggiungere schemi d'identità degli agenti esistenti che potrebbero non essere attualmente visualizzati nel registro di Agent 365.

Usare il Managed Disks (scelta consigliata)

Il Managed Disks è ora disponibile a livello generale ed è il modo consigliato per compilare ed effettuare il provisioning degli agenti. L'SDK L'SDK gestisce automaticamente la creazione e la registrazione dell'identità dell'agente nel Registro di sistema di Agent 365, quindi le identità dell'agente verranno visualizzate automaticamente senza codice aggiuntivo. Se si avvia un nuovo progetto di agente o si ha la flessibilità necessaria per eseguire la migrazione del codice esistente, usare l'SDK. È il percorso più semplice e durevole ed evita la necessità di coordinare manualmente più chiamate API.

Usare la CLI di Agent 365

Agent 365 CLI è un'altra opzione che gestisce la configurazione per te, inclusa la registrazione dell'agente. Seguire le istruzioni di installazione usando l'ordine di esecuzione consigliato. Utilizza il seguente comando:

a365 setup all

Se la registrazione non riesce, è possibile rieseguire solo il passaggio di registrazione senza dover eseguire l'intero processo. Utilizza il seguente comando:

a365 setup all --agent-registration-only

Chiamare l'API Registro Agente direttamente

Se è necessario creare progetti di identità agente a livello di codice con il API Graph Microsoft, ad esempio perché sono presenti flussi di lavoro esistenti di rilascio delle identità che non è possibile modificare immediatamente, è necessario aggiungere una chiamata esplicita all'API del Registro di sistema degli agenti after la creazione del progetto di identità dell'agente per pubblicare la scheda agente corrispondente. Questo passaggio registra la scheda agente nel Registro di sistema di Agent 365 in modo che venga visualizzata per gli amministratori.

Creare il progetto di identità dell'agente usando microsoft API Graph (come illustrato nelle sezioni precedenti).
Seguite immediatamente con una chiamata all'API del Registro Agent per pubblicare la relativa scheda agente, inclusi i metadati di cui gli amministratori hanno bisogno per gestirla.
Gestire il pattern a due chiamate in modo sicuro ai tentativi di ripetizione, in modo che un errore temporaneo in una delle chiamate mantenga l'ambiente in uno stato recuperabile.

Per gli schemi di richiesta e risposta, le autorizzazioni necessarie e gli esempi di codice, vedere le informazioni di riferimento sull'API del Registro di sistema dell'agente.

Tip

Se sono presenti progetti di identità degli agenti esistenti che non vengono visualizzati nel registro di Agent 365, registrarli usando l'API Registro agenti. Per i modelli di identità dell'agente in blocco, usare l'endpoint batch. Per ulteriori informazioni, consultare la convergenza del registro di Agent con Microsoft Agent 365.

Progetti di identità dell'agente esistenti che non si trovano nel registro di Agent 365

Per i progetti di identità dell'agente creati in precedenza usando il Microsoft Entra Agent ID API Graph ma che non sono attualmente visibili nel registro Agent 365, è possibile registrarli usando l'Agent Registry API. Questo passaggio garantisce che vengano visualizzati nel Registro di sistema di Agent 365.

Eliminare un modello di identità dell'agente

Quando un agente viene rimosso, eliminare il progetto di identità dell'agente associato. L'eliminazione dello schema attiva la pulizia automatica di tutte le identità dei sotto-agenti e degli account utente degli agenti. Per istruzioni dettagliate sull'eliminazione e sul ripristino, vedere Eliminare e ripristinare gli oggetti identity dell'agente.

Passo successivo

Creare ed eliminare le identità dell'agente

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-05-09

Creare un progetto di identità dell'agente

Prerequisiti

Prepara il tuo ambiente

Autorizzare un client a creare modelli di identità dell'agente

Creare un progetto di identità dell'agente

Usare il Interfaccia di amministrazione di Microsoft Entra

Creare programmaticamente

Configurare le credenziali per il progetto di identità dell'agente

Altre credenziali dell'app

Configurare l'URI e l'ambito dell'identificatore

Creare un modello principale per l'agente

Registrare gli agenti nel Registro di sistema di Agent 365

Usare il Managed Disks (scelta consigliata)

Usare la CLI di Agent 365

Chiamare l'API Registro Agente direttamente

Progetti di identità dell'agente esistenti che non si trovano nel registro di Agent 365

Eliminare un modello di identità dell'agente

Passo successivo

Commenti e suggerimenti

Risorse aggiuntive