Configurazione guidata dall'intelligenza artificiale per Microsoft Entra Agent ID

L'onboarding in Microsoft Entra Agent ID prevede più passaggi: creazione di un progetto di identità agente, configurazione delle credenziali, configurazione di URI e ambiti dell'identificatore, creazione di entità di progetto e identità dell'agente di provisioning. Ogni fase ha i propri prerequisiti, controlli di validazione e punti decisionali.

Questa configurazione guidata dall'intelligenza artificiale automatizza l'intero flusso di lavoro usando un agente di codifica di intelligenza artificiale (ad esempio GitHub Copilot in VS Code) per eseguire i passaggi per conto dell'utente. Invece di navigare tra più pagine di documentazione ed eseguire comandi manualmente, fornisci all'agente AI un unico file di istruzioni che ti guida nel processo in modo interattivo. Questo file di istruzioni è disponibile come competenza ed è accessibile in più modi.

Vantaggi

La configurazione guidata dall'IA offre diversi vantaggi rispetto al flusso di lavoro manuale:

• Punto di ingresso singolo: un file di istruzioni sostituisce la necessità di spostarsi tra più pagine della documentazione. L'agente AI segue i passaggi in ordine e gestisce automaticamente le transizioni.
• Convalida dei prerequisiti automatica: l'agente di intelligenza artificiale verifica di disporre dei ruoli di Microsoft Entra corretti, che siano installati gli strumenti necessari e i moduli Graph e che le autorizzazioni necessarie siano configurate con il consenso amministratore prima di effettuare chiamate API.
• Impostazioni predefinite intelligenti e rilevamento automatico: l'agente di intelligenza artificiale esegue una query sul tenant per ottenere informazioni sull'utente e i dettagli delle risorse esistenti, quindi usa tali valori come suggerimenti durante la raccolta degli input di configurazione.
• Convenzioni di denominazione derivate: si specifica un singolo nome visualizzato per l'agente e l'agente di intelligenza artificiale deriva tutti i nomi di risorse correlati (progetto, entità progetto, identità agente, URI identificatori) usando modelli coerenti.
• Gestione degli errori inline: quando un comando ha esito negativo, l'agente di intelligenza artificiale analizza l'errore, suggerisce una correzione e riprova anziché richiedere la ricerca tramite la documentazione sulla risoluzione dei problemi. Questa gestione degli errori è particolarmente utile per i problemi specifici dell'Agent ID, come ad esempio i ritardi nella propagazione delle autorizzazioni e i requisiti di intestazione OData.
• Operazioni Idempotenti: l'agente di intelligenza artificiale verifica se le risorse esistono già prima di crearle, assicurando la sicurezza di rieseguire l'installazione se un tentativo precedente è stato interrotto.

Prerequisiti

Prima di iniziare, assicurarsi di disporre dei prerequisiti seguenti.

Strumenti necessari

La configurazione guidata dall'intelligenza artificiale richiede un agente di codifica di intelligenza artificiale con accesso al terminale:

• Visual Studio Code con estensioni GitHub Copilot e GitHub Copilot Chat installate.
• L'estensione GitHub Copilot per Azure, che offre direttamente in VS Code la funzionalità Microsoft Entra Agent ID.

La funzionalità supporta due modalità di provisioning. Installare uno o entrambi a seconda delle preferenze:

• Percorso di PowerShell: PowerShell 7 o versione successiva con SDK PowerShell di Microsoft Graph. Installare utilizzando Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force.
• Percorso Python: Python 3.8 o versione successiva con azure-identity e requests. Installare utilizzando pip install azure-identity requests.

Account e autorizzazioni obbligatori

• Accesso a un tenant Microsoft Entra con uno dei ruoli seguenti:
  • Sviluppatore ID agente per creare modelli di identità dell'agente e identità dell'agente. Qualsiasi proprietario di un blueprint di identità agente può creare un'identità agente per tale blueprint senza un ruolo ID agente.
  • Amministratore Agent ID per l'accesso completo alle risorse di Agent ID.

• Ruoli aggiuntivi per le concessioni di autorizzazioni:
  • Amministratore del ruolo con privilegi per concedere le autorizzazioni dell'applicazione Microsoft Graph.
  • Amministratore di applicazioni Cloud o Amministratore di applicazioni per concedere autorizzazioni delegate Microsoft Graph.

Autorizzazioni di Microsoft Graph necessarie

Il client usato (PowerShell o una registrazione dell'app personalizzata) deve essere autorizzato con le autorizzazioni delegate seguenti:

Codice agente obbligatorio (facoltativo)

Se si dispone già di un progetto di agente funzionante (Python, Node.js o .NET) che necessita di un'identità dell'agente, tenere a disposizione la directory del progetto. Se non ne possiedi ancora uno, puoi comunque completare la configurazione del blueprint in modo indipendente.

Get started

La configurazione guidata dall'intelligenza artificiale usa una competenza, ovvero un singolo file di istruzioni che contiene tutti i passaggi e i controlli di convalida. È possibile accedere alla competenza in uno dei due modi seguenti:

• Tramite l'estensione GitHub Copilot for Azure (consigliata): Installa l'estensione GitHub Copilot for Azure per VS Code. La competenza Microsoft Entra Agent ID viene attivata automaticamente quando si richiede la configurazione dell'ID agente in Copilot Chat.
• Direttamente da GitHub: usa la competenza autonoma Microsoft Entra Agent ID facendo riferimento a essa nel prompt di Copilot Chat.

Passaggio 1: Aprire il progetto in VS Code

Apri la directory del progetto agente (o qualsiasi altra directory di lavoro) in Visual Studio Code.

Passaggio 2: Aprire gitHub Copilot Chat in modalità agente

Aprire il pannello Copilot Chat GitHub e passare alla modalità Agent. La modalità agente offre GitHub Copilot la possibilità di eseguire comandi del terminale, leggere i file e interagire con l'ambiente, richiesta dall'installazione guidata dall'intelligenza artificiale.

Passaggio 3: Avviare la configurazione guidata

Se è installata l'estensione GitHub Copilot per Azure, chiedere Copilot di configurare l'ID agente. Per esempio:

@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.

Se non disponi dell'estensione, fai riferimento direttamente alla competenza da GitHub:

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

L'agente IA legge la skill e inizia la configurazione guidata. Esegue i passaggi in sequenza:

1. Convalidare i prerequisiti: verifica i ruoli di Microsoft Entra e convalida che gli strumenti necessari (PowerShell con il modulo Microsoft Graph oppure Python con azure-identity) siano installati.
2. Autentica: si connette a Microsoft Graph con le autorizzazioni necessarie. In PowerShell, la skill usa Connect-MgGraph con ambiti delegati espliciti. Per Python, usa una registrazione app dedicata con credenziali client.
3. Crea il modello di identità dell'agente: raccoglie un nome visualizzato, identifica lo sponsor (tu), crea il modello usando l'endpoint immesso (/applications/microsoft.graph.agentIdentityBlueprint) e registra il appId.
4. Configurare le credenziali: aggiunge al progetto una credenziale di identità federata con identità gestita (per la produzione) o un segreto client (per lo sviluppo/test locale).
5. Configurare l'URI e l'ambito dell'identificatore: imposta identifierUris su api://{appId} e crea un ambito di autorizzazione OAuth2 per la comunicazione da agente a agente e da utente a agente.
6. Creare l'entità progetto: crea l'entità servizio per il progetto usando l'endpoint tipizzato (l'entità non viene creata automaticamente e deve essere eseguita in modo esplicito).
7. Creare identità agente: crea una o più entità servizio di identità agente nel progetto.

Mentre l'agente esamina la competenza, potrebbe esserti richiesto di installare estensioni o altri strumenti. Segui le istruzioni per assicurarti che il tuo ambiente sia pronto.

Passo 4: Rispondi ai prompt

L'agente IA si ferma in punti specifici per raccogliere input da te:

• Nome visualizzato: Il nome visualizzato per lo schema di identità del tuo agente (ad esempio, "Agente Budget Contoso").
• Sponsor: utente o gruppo responsabile dell'agente. Di default, è selezionato l'utente attualmente connesso.
• Proprietario: utente o entità servizio che può apportare modifiche tecniche al progetto. Facoltativo ma consigliato.
• Tipo di credenziale: indica se usare un'identità gestita (consigliata per la produzione) o un certificato o un segreto client (per lo sviluppo locale).
• Numero di identità dell'agente: numero di identità dell'agente da creare in questo progetto.
• Conferma del valore derivato: esaminare i nomi generati automaticamente e gli URI prima della creazione delle risorse.

Passaggio 5: Verificare nel Interfaccia di amministrazione di Microsoft Entra

Al termine dell'installazione, l'agente di intelligenza artificiale fornisce istruzioni su come verificare le risorse:

1. Accedi al Interfaccia di amministrazione di Microsoft Entra con almeno il ruolo di Agent ID Developer.
2. Vai a Entra ID>Agents>Agent identities per visualizzare il nuovo progetto di identità dell'agente ed eventuali identità dell'agente create sotto di esso.
3. Verificare che il blueprint abbia configurate le credenziali corrette, l'URI identificatore e l'ambito.

Cosa copre la configurazione guidata dall'IA

La configurazione guidata dall'intelligenza artificiale automatizza le fasi seguenti dell'integrazione dell'ID agente:

Problemi comuni che la configurazione guidata dall'intelligenza artificiale gestisce

Le API ID agente hanno diversi requisiti che la configurazione guidata dall'intelligenza artificiale rileva e risolve automaticamente, ma non sono requisiti ovvi. Comprendere questi problemi può essere utile se è necessario eseguire il debug dei problemi o estendere la configurazione.

L'intestazione OData-Version è obbligatoria

Tutte le chiamate all'API Agent ID richiedono l'intestazione OData-Version: 4.0. Se si omette questa intestazione, l'API potrebbe creare senza alcuna segnalazione un'applicazione standard invece di un modello di identità dell'agente. La configurazione guidata dall'intelligenza artificiale include sempre questa intestazione. La skill usa anche endpoint tipizzati (ad esempio /applications/microsoft.graph.agentIdentityBlueprint) anziché /applications non elaborati con proprietà @odata.type per ridurre il rischio di questo problema.

Il modello principale non è creato automaticamente

La creazione di un progetto di identità agente (POST /applications) non crea automaticamente l'entità progetto (entità servizio). Senza lo schema principale, la creazione delle identità successive degli agenti fallisce con:

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

La configurazione guidata dall'intelligenza artificiale crea sempre lo schema principale immediatamente dopo lo schema. Gestisce anche il caso idempotente. Se un'esecuzione precedente ha creato il modello ma è andata in crash prima di creare l'entità principale, l'installazione rileva questo evento e crea l'entità mancante.

Gli sponsor sono obbligatori

Gli sponsor sono obbligatori e possono essere utenti, gruppi con appartenenza dinamica o gruppi unificati. Sia la creazione del progetto, sia quella dell'identità dell'agente richiedono un campo sponsors@odata.bind. Senza di esso, si riceve:

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

La configurazione guidata dall'intelligenza artificiale accetta solo gli oggetti Utente per l'assegnazione dello sponsor e usa il /users/{objectId} formato URL (non /directoryObjects/ o /servicePrincipals/). L'installazione risolve l'ID oggetto dell'utente corrente e lo usa come sponsor di default. Per assegnare un gruppo supportato come sponsor per un progetto, usare direttamente microsoft API Graph.

La propagazione delle autorizzazioni richiede 30–120+ secondi

Dopo aver concesso il consenso amministratore per le autorizzazioni id agente, le autorizzazioni appena concesse non vengono visualizzate immediatamente nei token. L'endpoint del token serve attestazioni memorizzate nella cache e la propagazione può richiedere almeno 30-120 secondi.

La configurazione guidata dall'intelligenza artificiale gestisce le modifiche recenti delle autorizzazioni ritentando le operazioni con backoff esponenziale quando viene ricevuto un errore 403. Se si esegue manualmente lo script, implementare la logica di ripetizione dei tentativi:

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

Le identità dell'agente non possono avere credenziali di password

Le identità dell'agente sono entità servizio senza eseguire il backup degli oggetti applicazione. Provare ad aggiungere un passwordCredential direttamente all'identità di un agente risulta nel seguente:

PropertyNotCompatibleWithAgentIdentity

Le credenziali devono essere configurate nel blueprint, non nelle singole identità dell'agente. Usare la federazione delle identità gestite (scelta consigliata) o aggiungere segreti/certificati al modello, e le identità degli agenti ereditano le credenziali tramite impersonificazione.

L'URI dell'identificatore deve essere impostato in modo esplicito

Il campo del identifierUris progetto non è impostato per impostazione predefinita. Senza di esso, l'ambito api://{appId}/.default OAuth2 non verrà risolto e l'acquisizione del token per l'agente avrà esito negativo. La configurazione guidata dall'intelligenza artificiale configura sempre questo valore come parte del passaggio di configurazione dell'ambito.

Percorso delle credenziali delle identità federate per i progetti

Quando si aggiungono le credenziali di identità federate (FIC) per la federazione delle identità gestite, è necessario usare il percorso API specifico dell'agente:

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

L'uso del percorso /applications/{id}/federatedIdentityCredentials potrebbe funzionare per i modelli di identità dell'agente, ma non è supportato e non è consigliato.

L'autorità emittente del token varia in base alla versione dell'endpoint

Quando si convalidano i token nel back-end dell'agente, tenere presente le varianti seguenti:

• I token v1.0 usano l'autorità di certificazione https://sts.windows.net/{tenant-id}/
• I token v2.0 usano l'autorità di certificazione https://login.microsoftonline.com/{tenant-id}/v2.0

Accettare entrambi i formati nella logica di convalida del token.

Risoluzione dei problemi

L'agente IA non esegue i comandi del terminale

Se l'agente di intelligenza artificiale descrive i comandi ma non li esegue, assicurarsi di usare la modalità Agent in GitHub Copilot Chat. Le modalità Ask e Edit non hanno accesso al terminale.

L'agente IA salta i passaggi di validazione

Il file di istruzioni impone un ordine rigoroso dei passaggi. Se l'agente IA sembra saltare un passaggio, ricordagli di seguire le istruzioni dall'inizio. Per esempio:

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

I comandi di Graph hanno esito negativo con 403-Accesso negato

Le cause più comuni degli errori 403:

• Uso di interfaccia della riga di comando di Azure o token DefaultAzureCredential: i token di interfaccia della riga di comando di Azure includono Directory.AccessAsUser.All, che le API Agent Identity rifiutano categoricamente. Usare Connect-MgGraph con ambiti delegati espliciti o una registrazione di app dedicata con client_credentials. Vedere l'avviso di autenticazione nei prerequisiti.
• Ritardo di propagazione delle autorizzazioni: attendere 1-2 minuti dopo il consenso dell'amministratore e riprovare. La configurazione guidata dall'intelligenza artificiale gestisce automaticamente questa operazione con la logica di ripetizione dei tentativi.
• Consenso amministratore mancante: verificare che le autorizzazioni necessarie abbiano il consenso amministratore concesso nel Interfaccia di amministrazione di Microsoft Entra in Registrazioni app> la tua app client >Autorizzazioni API.

La creazione dello schema ha esito positivo ma restituisce un'applicazione standard

Questo risultato si verifica quando manca l'intestazione OData-Version: 4.0 . Usare l'endpoint tipizzato (/applications/microsoft.graph.agentIdentityBlueprint) anziché l'endpoint grezzo /applications con @odata.type per evitare questo problema.

La creazione dell'identità dell'agente non riesce con "Blueprint Principal does not exist" (L'entità progetto non esiste)

Il modello principale deve essere creato in un passaggio separato dopo il modello. Corri!

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

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

Errori dei criteri di durata delle credenziali

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 durante l'aggiunta di una password, ridurre il endDateTime valore per allinearlo alle politiche dell'organizzazione.

I valori di configurazione devono essere cambiati

Se è necessario modificare i valori di configurazione dopo l'installazione, è possibile:

• Eseguire di nuovo la configurazione guidata dall'intelligenza artificiale con i valori aggiornati. I controlli idempotenti saltano le risorse già esistenti correttamente.
• Usare Microsoft Graph PowerShell per aggiornare proprietà specifiche con PATCH requests.

Passaggi successivi

• Creare ed eliminare le identità dell'agente
• Relazioni amministrative nell'ID dell'agente (proprietari, sponsor e manager)
• Identità dell'agente, entità servizio e applicazioni
• Concetti relativi al progetto di identità dell'agente