Condividi tramite

Configurare il progetto dell'agente

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

Il progetto dell'agente definisce l'identità, i permessi e i requisiti infrastrutturali del tuo agente. Crea ogni istanza agente da questo progetto di agente.

Per maggiori informazioni sull'Identità dell'Agente 365, consulta Identità dell'Agente 365.

Prerequisiti

Prima di iniziare, assicurarsi di avere i prerequisiti seguenti:

  1. CLI Agent 365 - Vedi installazione CLI Agent 365.

  2. Autorizzazioni necessarie:

    • Utente del tenant valido con uno dei ruoli seguenti:
      • Amministratore globale
      • Amministratore dell'ID agente
      • Sviluppatore di ID Agente
    • Accesso a una sottoscrizione Azure con autorizzazioni per creare risorse

  3. File valido a365.config.json nella tua directory di lavoro, impostato tramite questo passaggio: Impostazione della configurazione dell'Agent 365.

Creare il progetto dell'agente

Usare il comando a365 setup per creare risorse Azure e registrare il progetto agent. Il blueprint definisce l'identità, le autorizzazioni e i requisiti dell'infrastruttura dell'agente. Questo passaggio stabilisce le basi per la distribuzione e l'esecuzione dell'agente in Azure.

Eseguire installazione

Esegui il comando setup:

a365 setup -h

Il comando ha varie opzioni. Puoi completare l'intera configurazione in un solo comando usando a365 setup all o scegliendo opzioni più dettagliate.

L'intero processo di configurazione esegue queste operazioni:

  1. Crea l'infrastruttura Azure (se non esiste già):

    • Gruppo di risorse
    • Piano di servizio app con SKU specificato
    • App Web di Azure con identità gestita attivata

  2. Registra il blueprint dell'agente:

    • Crea lo schema dell'agente nel tenant di Microsoft Entra
    • Crea registrazioni delle applicazioni Microsoft Entra
    • Configura l'identità dell'agente con le autorizzazioni necessarie

  3. Configura autorizzazioni API:

    • Configura gli ambiti di Microsoft Graph API
    • Configura le autorizzazioni dell'API del bot di messaggistica
    • Applica le autorizzazioni ereditabili per le istanze dell'agente

  4. Aggiorna i file di configurazione:

    • Salva ID e endpoint generati in un nuovo file nella tua directory di lavoro chiamato a365.generated.config.json
    • Registra informazioni sull'identità gestita e sulle risorse

Nota

L'installazione richiede in genere 3-5 minuti e salva automaticamente la configurazione in a365.generated.config.json. Se si esegue come Global Administrator, la CLI potrebbe aprire una finestra del browser per il consenso dell'amministratore. Completare il flusso di consenso per continuare. Se si esegue come amministratore dell'ID agente o sviluppatore, non viene visualizzata alcuna finestra del browser; l'interfaccia della riga di comando genera URL di consenso per il completamento da parte di un amministratore globale successivamente.

Configurazione tramite l'amministratore di ID Agente o lo sviluppatore di ID Agente

Se si esegue come amministratore id agente o agente id sviluppatore (non amministratore globale), a365 setup all completa la maggior parte dei passaggi automaticamente, ma le concessioni di autorizzazione OAuth2 richiedono un passaggio di amministratore globale separato.

Quali passaggi si completano automaticamente:

  • Infrastruttura di Azure (gruppo di risorse, piano di servizio app, app Web)
  • Registrazione dello schema dell'agente
  • Autorizzazioni ereditabili per istanze di agenti

Quali passaggi richiedono un amministratore globale:

  • Concessioni di autorizzazioni delegate OAuth2 (AllPrincipals consenso) per Microsoft Graph, Agent 365 Tools, API bot di messaggistica, API Observability e API Power Platform

Come completare la configurazione usando un account non amministratore:

# Step 1: Run setup as Agent ID Admin or Developer
a365 setup all
# Setup completes all steps it can. The CLI displays next steps
# showing how a Global Administrator can complete the OAuth2 grants.

# Step 2: Share the config folder with a Global Administrator.
# The folder contains a365.config.json and a365.generated.config.json.

# Step 3: The Global Administrator runs:
a365 setup admin --config-dir "<path-to-config-folder>"

In alternativa, l'amministratore globale può aprire l'URL di consenso combinato salvato dalla CLI a365.generated.config.json (campo: combinedAdminConsentUrl) e concedere il consenso con una sola visita del browser. Per altre informazioni, vedere a365 setup admin.

Verificare l'installazione

Dopo la fine della configurazione, vedi un riassunto che mostra tutti i passaggi completati. Verificate le risorse create:

  1. Verifica la configurazione generata:

    a365 config display -g

    L'output atteso include questi valori critici:

    {
"managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"agentBlueprintClientSecretProtected": true,
"botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"resourceConsents": [],
"completed": true,
"completedAt": "xxxx-xx-xxTxx:xx:xxZ",
"cliVersion": "x.x.xx"
}

    Campi chiave da verificare:

    Campo Scopo Cosa controllare
    managedIdentityPrincipalId Autenticazione dell'identità gestita di Azure Dovrebbe essere un GUID valido
    agentBlueprintId L'identificatore unico del tuo agente Utilizzato nel Portale Sviluppatori e nel centro amministrativo
    agentBlueprintObjectId Microsoft Entra ID del progetto
    messagingEndpoint Routing dei messaggi Dove Teams/Outlook inviano messaggi al tuo agente
    agentBlueprintClientSecret Segreto dell'autenticazione Dovrebbe esistere (il valore è mascherato)
    resourceConsents Autorizzazioni API Deve contenere risorse come Microsoft Graph, Agent 365 Tools, API bot di messaggistica, API Observability
    completed Stato di configurazione Dovrebbe essere true

    Nota

    Se l'installazione è stata eseguita come Amministratore ID agente o Sviluppatore ID agente, resourceConsents potrebbe essere vuoto e completed potrebbe essere false fino a quando un Amministratore Globale esegue a365 setup admin per completare le concessioni di autorizzazione OAuth2.

  2. Verifica le risorse di Azure nel Azure Portal:

    Oppure usa il az resource list comando PowerShell.

    # List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table

    Verifica che le seguenti risorse siano state create:

    • Gruppo di risorse:

      • Vai a Gruppi> Risorse Seleziona il tuo gruppo di risorse
      • Verifica che contenga il piano di servizio app e l'app Web

    • Piano di servizio app:

      • Vai a Servizi app>Piani di servizio app
      • Trova il piano e verifica che il piano tariffario corrisponda allo SKU di configurazione

    • App Web:

      • Vai a Servizi app>App Web
      • Trova l'app Web, quindi vai a Impostazioni>Identità>Sistema assegnato
      • Verifica che lo stato sia Attivato
      • Nota che l'ID oggetto (principale) corrisponde a managedIdentityPrincipalId

  3. Verificare le applicazioni di Microsoft Entra nel portale di Azure

    Passare a Azure Active Directory>App registrations>Tutte le applicazioni:

    • Cerca il progetto dell'agente in base a agentBlueprintId

    • Apri l'applicazione e seleziona Autorizzazioni API

    • I permessi di verifica sono concessi con segni verdi:

      • Microsoft Graph (autorizzazioni delegate e autorizzazioni dell'applicazione)
      • Autorizzazioni API del bot di messaggistica

    • Tutte le autorizzazioni mostrano "Concesso per [Il tuo inquilino]"

  4. Verifica il file di configurazione generato creato:

    È necessario avere un file denominato a365.generated.config.json che contiene tutti i dati di configurazione.

    Usare il comando PowerShell Test-Path per verificare che esista.

    # Check file exists
Test-Path a365.generated.config.json
# Should return: True

    Importante

    Salva entrambi a365.config.json e a365.generated.config.json file. Questi valori servono per il deployment e la risoluzione dei problemi.

  5. Verifica che l'app Web abbia abilitato l'identità gestita:

    Usa il az webapp identity show comando per verificare se l'identità gestita è abilitata.

    az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

    Previsto:

    {
"principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "SystemAssigned"
}

  6. Verificare il progetto Agent registrato in Microsoft Entra:

    Nell'interfaccia di amministrazione di Microsoft Entra, cerca il tuo agentBlueprintId o cerca per nome.

    Verifica che:

    ✅ Appaiono la registrazione delle app e l'applicazione aziendale
    ✅ Nel blueprint di registrazione dell'app, la scheda dei permessi API mostra tutti i permessi
    ✅ Lo stato mostra "Concesso per [Il tuo inquilino]"

Per ulteriori aiuti, vedi:

Autorizzazioni dell'agente

Prima che le app e gli agenti possano leggere o scrivere dati di Microsoft 365 (utenti, posta elettronica, file, Teams, agenti e così via), è necessario concedere in modo esplicito le autorizzazioni di Microsoft Graph. Le autorizzazioni di Microsoft Graph sono il modello di autorizzazione che controlla i dati e le azioni a cui un'app o un servizio può accedere tramite le API Microsoft Graph in Microsoft 365 e Microsoft Entra ID.

Altre informazioni: Panoramica delle autorizzazioni di Microsoft Graph

Per usare le autorizzazioni Graph per le istanze dell'agente di Agent 365, lo sviluppatore deve dichiararle nello schema dell'agente. Quando un amministratore attiva il progetto nell'interfaccia di amministrazione di Microsoft 365, il portale esamina le autorizzazioni graph del progetto e richiede all'amministratore di fornire il consenso.

Per comprendere e convalidare il modo in cui le autorizzazioni graph abilitano l'agente, è possibile:

Applicare le autorizzazioni al blueprint

Usare a365 config permissions per aggiungere le autorizzazioni necessarie per le risorse alla configurazione e quindi eseguire a365 setup permissions custom per applicarle al progetto in Microsoft Entra.

# Add resource permissions to config
a365 config permissions `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

# Apply permissions to your blueprint
a365 setup permissions custom

Per informazioni dettagliate sulla configurazione e la rimozione di autorizzazioni personalizzate, vedere setup permissions custom.

Passaggi successivi

Distribuisci il codice del tuo agente nel cloud:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Pubblica l'agente nel centro amministrativo Microsoft

Risoluzione dei problemi

Questa sezione descrive i problemi comuni durante la configurazione dei progetti degli agenti.

Suggerimento

La Guida alla risoluzione dei problemi dell'Agente 365 contiene raccomandazioni di alto livello, best practice e link a contenuti di risoluzione dei problemi per ogni fase del ciclo di sviluppo dell'Agente 365.

Questi problemi si verificano a volte durante la registrazione:

Errore di permessi insufficienti

Sintomo: Errore di permessi insufficienti durante a365 setup l'esecuzione del comando .

Nel tenant di Microsoft Entra sono necessari uno dei ruoli seguenti:

  • Amministratore globale
  • Amministratore dell'ID agente
  • Sviluppatore di ID Agente

E accesso come collaboratore o proprietario della sottoscrizione ad Azure.

Soluzione: Verificare di avere le autorizzazioni necessarie in Microsoft Entra.

Nota

Se si dispone del ruolo Amministratore ID agente o Sviluppatore ID agente (non Amministratore globale), a365 setup all ha comunque esito positivo, ma ignora le autorizzazioni OAuth2. Al termine dell'installazione, un amministratore globale deve eseguire a365 setup admin per completare le concessioni rimanenti. Questo flusso di lavoro è previsto per le organizzazioni in cui lo sviluppatore dell'agente e l'amministratore globale sono persone diverse.

Autenticazione Azure CLI mancante

Sintomo: La configurazione fallisce con errori di autenticazione.

Soluzione: Assicurarsi di essere connessi ad Azure e verificare l'account e la sottoscrizione.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

La risorsa esiste già

Sintomo: L'installazione fallisce con un errore per il gruppo di risorse, il piano di servizio app o l'app Web.

Soluzioni: Scegliere una delle soluzioni seguenti.

  • Utilizzare le risorse esistenti

    Se esistono risorse e vuoi usarle, assicurati che corrispondano alla tua configurazione. Usa il az resource list comando PowerShell.

    az resource list --resource-group <your-resource-group>

  • Elimina risorse in conflitto

    Eliminare il gruppo di risorse o rinominare le risorse in a365.config.json ed eseguire di nuovo l'installazione.

    Usare il az group delete comando di PowerShell per eliminare un gruppo di risorse.

    # WARNING: This command deletes all resources in it
az group delete --name <your-resource-group>

  • Usa il comando pulizia per ricominciare da capo

    Usare il cleanup comando per rimuovere tutte le risorse di Agent 365, quindi usare il comando per rieseguire l'installazionea365 setup all.

    Avvertimento

    L'esecuzione a365 cleanup è distruttiva.

    a365 cleanup
a365 setup all

Sintomo: Le finestre del browser sono state aperte durante l'installazione, ma sono state chiuse senza completare il consenso o il programma di installazione è stato completato, ma le concessioni di autorizzazione OAuth2 sono ancora in sospeso.

Soluzione: Scegliere in base al ruolo:

  • Amministratore globale: eseguire a365 setup all di nuovo. L'interfaccia della riga di comando richiede il consenso dell'amministratore. Completare il flusso di consenso nella finestra del browser visualizzata.

  • Amministratore ID agente o sviluppatore: non è possibile completare direttamente le autorizzazioni OAuth2. Usare il flusso di lavoro di trasferimento:

    # Option 1: Global Admin runs setup admin
a365 setup admin --config-dir "<path-to-config-folder>"

# Option 2: Global Admin opens the combined consent URL
# Find the URL in a365.generated.config.json (combinedAdminConsentUrl field)
a365 config display -g

File di configurazione mancanti o invalidi

Sintomo: L'installazione fallisce con errori di "Configurazione non trovata" o di validazione.

Soluzione:

  1. Verifica che il a365.config.json file esista.
  2. Visualizza la configurazione attuale usando il comando a365 config display.
  3. Se manca o non è valido, reinizializzare usando il comando init config a365.
# Verify a365.config.json exists
Test-Path a365.config.json

# Display current configuration
a365 config display

# If missing or invalid, re-initialize
a365 config init

L'installazione si completa ma le risorse non vengono create

Symptom: il comando Setup ha esito positivo, ma le risorse Azure non esistono.

Soluzione:

  1. Controlla le risorse create col comando a365 config display -g.
  2. Verificare che le risorse Azure esistano usando il comando az resource list.
  3. Se le risorse sono mancanti, verificare la presenza di errori nell'output di installazione ed eseguire di nuovo il programma di installazione usando il a365 setup all comando .
# Check created resources
a365 config display -g

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Progetto Agent non registrato in Microsoft Entra

Sintomo: La configurazione viene completata, ma non riesci a trovare il modello agente nell'interfaccia di amministrazione di Microsoft Entra.

Soluzione:

  1. Recupera l'ID del blueprint dalla configurazione generata usando il comando a365 config display -g.

    a365 config display -g
# Look for: agentBlueprintId

  2. Cercare nell'interfaccia di amministrazione di Microsoft Entra:

    1. Passare a: Centro di amministrazione di Microsoft Entra.
    2. Passare a Registrazioni app>Tutte le applicazioni.
    3. Cerca il tuo agentBlueprintId.

  3. Se non viene trovato, eseguire di nuovo l'installazione usando il a365 setup all comando .

    a365 setup all

Permessi API non concessi

Sintomo: Il programma di installazione viene completato, ma le autorizzazioni sono visualizzate come "Non concesse" in Microsoft Entra.

Soluzione:

  1. Aprire l'interfaccia di amministrazione di Microsoft Entra.

  2. Trovare la registrazione dell'app del progetto agente.

  3. Vai ad Autorizzazioni API.

  4. Concedere il consenso dell'amministratore:

    1. Seleziona Concede il consenso amministrativo per [Il tuo inquilino].
    2. Confermare l'azione.

  5. Verificare che tutte le autorizzazioni visualizzino i segni di spunta verdi.

Identità gestita non abilitata

Sintomo: L'app Web esiste, ma l'identità gestita non è abilitata.

Soluzione:

  1. Controllare lo stato dell'identità gestita usando il az webapp identity show comando .
  2. Se non è abilitato, abilitarlo manualmente usando il az webapp identity assign comando .
  3. Verificare che sia abilitato usando il az webapp identity show comando .
# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

Il programma di installazione richiede troppo tempo o smette di rispondere

Sintomo: Il comando di setup dura più di 10 minuti senza essere completato.

Soluzione:

  1. Se è in esecuzione come amministratore globale, verificare se una finestra del browser è in attesa del consenso dell'amministratore. Completare il flusso di consenso per sbloccare la configurazione.

  2. Se l'installazione davvero smette di rispondere, annullala (Ctrl+C) e verifica cosa è stato creato.

    # Check generated config
a365 config display -g

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Eseguire la pulizia e riprovare.

    a365 cleanup
a365 setup all

Impossibile inviare il primo messaggio in Teams

Sintomo: Dopo che un'istanza dell'agente è stata provisionata, non può inviare un messaggio di benvenuto al gestore degli agenti.

Soluzione: L'autorizzazione [Chat.Create][perm-chatcreate] è necessaria per creare un nuovo oggetto chat. Se esiste già una chat one-on-one, questa operazione restituisce la chat esistente e non ne crea una nuova.

  • Per implementare, configurare le autorizzazioni ereditabili del blueprint per includere l'ambito Chat.Create.
  • Configurare un messaggio di chat di Teams da inviare dopo il provisioning di un'istanza dell'agente.
  • Creare una nuova istanza dell'agente dal progetto e testare il messaggio di prima esecuzione.
  • Last updated on