Configurare il progetto dell'agente

Il progetto dell'agente definisce l'identità, le autorizzazioni e i requisiti dell'infrastruttura dell'agente. Crea ogni istanza agente da questo progetto di agente.

Per maggiori informazioni sull'identità di Agent 365, vedi Identità di Agent 365.

Prerequisiti

Prima di iniziare, accertati di avere i seguenti prerequisiti:

1. CLI di Agent 365: vedi Installazione CLI di Agent 365.

2. Autorizzazioni necessarie:

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

   Suggerimento

   Gli agenti (non i compagni IA) non hanno bisogno di un file di configurazione. Usa a365 setup all --agent-name <name> e la CLI risolve automaticamente il tenant e l'app client. La configurazione di un assistente IA richiede la creazione manuale di un a365.config.json.

Creare il progetto dell'agente

Usa il comando a365 setup per creare le risorse di Azure e registra il blueprint dell'agente. 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 Setup

Esegui il comando di configurazione:

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.

Configurazione dell'agente (predefinita):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

Configurazione dell'agente M365 (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

Configurazione degli assistenti IA:

a365 setup all --aiteammate

Il processo completo di installazione esegue queste operazioni:

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

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

2. Registra il blueprint dell'agente:

   • Creare il progetto dell'agente nel tenant Microsoft Entra
   • Crea le registrazioni dell'applicazione Microsoft Entra
   • Configura l'identità dell'agente con le autorizzazioni necessarie
   • Imposta managerApplications nel blueprint, che è necessario per la gestibilità della piattaforma

   Importante

   I blueprint devono avere managerApplications impostato per essere accettati dalla piattaforma. La CLI lo imposta automaticamente. Se hai un blueprint esistente creato prima che questo requisito venisse introdotto, eliminalo ed esegui di nuovo a365 setup all, oppure modificalo manualmente tramite l'API Graph.

3. Configura autorizzazioni API:

   • Configura gli ambiti dell'API Microsoft Graph
   • 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 gli ID e gli endpoint generati in un nuovo file nella directory di lavoro, denominato a365.generated.config.json
   • Registra informazioni sull'identità gestita e sulle risorse

Configurazione tramite Sviluppatore ID agente

Se si esegue come Sviluppatore ID agente (non amministratore globale), a365 setup all completa la maggior parte dei passaggi automaticamente tranne le concessioni di autorizzazioni OAuth2 che richiedono un passaggio di Amministratore globale.

Quali passaggi vengono completati automaticamente:

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

Quali passaggi richiedono un amministratore globale:

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

Come completare la configurazione utilizzando un account non amministratore:

Esecuzione dei comandi:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

Condividi i prossimi passaggi visualizzati dalla CLI con il tuo Amministratore globale. Possono aprire il collegamento fornito o l'URL di consenso per completare le autorizzazioni OAuth2.

Verificare l'installazione

Al termine della configurazione, viene visualizzato un riepilogo che mostra tutti i passaggi completati. Verificare le risorse create:

1. Verifica la configurazione generata:

   Apri a365.generated.config.json nella directory di lavoro. Oppure usa PowerShell:

   Get-Content a365.generated.config.json | ConvertFrom-Json
   

   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 e gestione delle identità di Azure	Deve essere un GUID valido
   agentBlueprintId	L'identificatore unico del tuo agente	Utilizzato nel portale degli sviluppatori e nell'interfaccia di amministrazione
   agentBlueprintObjectId	Microsoft Entra ID del progetto
   messagingEndpoint	Trasferimento dei messaggi	Dove Teams/Outlook inviano messaggi al tuo agente
   agentBlueprintClientSecret	Segreto autenticazione	Dovrebbe esistere (il valore è mascherato)
   resourceConsents	Autorizzazioni API	Deve contenere risorse come Microsoft Graph, Strumenti di Agent 365, API bot di messaggistica, API di osservabilità
   completed	Stato configurazione	Deve 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 completa l'autorizzazione OAuth2 usando le fasi successive stampate dal CLI.

2. Verifica le risorse di Azure nel portale di Azure:

   Oppure usa il comando az resource list di PowerShell.

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

   Verifica che siano state create le seguenti risorse:

   • Gruppo di risorse:

     • Vai a Gruppi di risorse> Seleziona il gruppo delle 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 (entità) corrisponde a managedIdentityPrincipalId

3. Verifica le applicazioni Microsoft Entra nel portale di Azure:

   Vai ad Azure Active Directory>Registrazioni app>Tutte le applicazioni:

   • Cerca il progetto dell'agente in base a agentBlueprintId

   • Apri l'applicazione e seleziona Autorizzazioni API

   • Verifica che le autorizzazioni siano concesse con segni di spunta verdi:

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

   • Tutte le autorizzazioni visualizzano "Concesso per [il tuo tenant]"

4. Verifica il file di configurazione generato:

   Dovresti avere un file chiamato a365.generated.config.json che contiene tutti i dati di configurazione.

   Usa il comando Test-Path di PowerShell per verificare che esista.

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

   Importante

   Salva entrambi i file a365.config.json e a365.generated.config.json. Questi valori sono necessari per lo sviluppo e la risoluzione dei problemi.

5. Verificare che l'app Web abbia l'identità gestita abilitata:

   Usa il comando az webapp identity show 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. Verifica il progetto dell'agente registrato in Microsoft Entra:

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

   l'elenco di controllo seguente.

   ✅ Registrazione app e Applicazione aziendale vengono visualizzate
   ✅ Nel blueprint di registrazione dell'app, la scheda Autorizzazioni API mostra tutte le autorizzazioni
   ✅ Lo stato mostra "Concesso per [Il tuo tenant]"

Per ulteriore assistenza, vedi:

• Problemi con app client personalizzate

Autorizzazioni dell'agente

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

Per saperne di più: Panoramica delle autorizzazioni di Microsoft Graph

Per utilizzare le autorizzazioni Graph per le istanze dell'agente Agent 365, lo sviluppatore deve dichiararle nel blueprint dell'agente. Quando un amministratore attiva il blueprint nell'interfaccia di amministrazione di Microsoft 365, il portale esamina i permessi Graph del blueprint e invita l'amministratore ad acconsentire.

Per comprendere e verificare come le autorizzazioni Graph consentano al tuo agente di operare, puoi:

• Visualizzare tutte le autorizzazioni Graph disponibili.
• Visita Graph Explorer per provare le query, ispezionare le risposte e comprendere le autorizzazioni.
• Usa Playground per gli agenti Microsoft 365 per testare il tuo agente in locale prima dello sviluppo.

Applicare le autorizzazioni al tuo blueprint

Usa a365 setup permissions custom per applicare autorizzazioni API personalizzate direttamente al tuo blueprint in Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

Per dettagli completi sulla configurazione e rimozione delle autorizzazioni personalizzate, consulta setup permissions custom.

Passaggi successivi

Distribuisci il codice del tuo agente nel cloud:

Risoluzione dei problemi

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

Questi problemi a volte si verificano durante la registrazione:

• Errore autorizzazioni insufficienti
• Autenticazione dell'interfaccia della riga di comando di Azure mancante
• La risorsa esiste già
• Consenso amministratore non completato
• File di configurazione mancante o non valido
• La configurazione viene completata ma le risorse non vengono create
• Progetto dell'agente non registrato in Microsoft Entra
• Autorizzazioni API non concesse
• Identità gestita non abilitata
• L'installazione richiede troppo tempo o smette di rispondere
• Pulisci un agente senza configurazione
• Impossibile inviare il primo messaggio in Teams

Errore autorizzazioni insufficienti

Sintomo: errore di autorizzazioni insufficienti durante a365 setup l'esecuzione del comando.

È necessario disporre di uno dei seguenti ruoli nel tenant Microsoft Entra:

• Amministratore globale
• Sviluppatore ID agente

E accesso come collaboratore o proprietario della sottoscrizione ad Azure.

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

• Vai a: Interfaccia di amministrazione di Microsoft Entra> Profilo personale > Ruoli assegnati
• Verifica l'accesso all'abbonamento Azure usando il comando az account show di PowerShell

Autenticazione dell'interfaccia della riga di comando di Azure mancante

Sintomo: la configurazione fallisce con errori di autenticazione.

Soluzione: assicurati di essere connesso ad Azure e verifica il tuo 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 errore Resource already exists per il gruppo risorse, il piano servizio app o l'app Web.

Soluzioni: scegli tra le seguenti soluzioni.

• Usa risorsa esistente

  Se le risorse esistono e vuoi utilizzarle, assicurati che siano conformi alla tua configurazione. Usa il comando az resource list di PowerShell.

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

• Elimina risorse in conflitto

  Elimina il gruppo di risorse oppure rinomina le tue risorse in a365.config.json e riesegui la configurazione.

  Usa il comando az group delete 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 cleanup per ricominciare da capo

  Usa il comando cleanup per rimuovere tutte le risorse di Agent 365, quindi usa il comando a365 setup all per riavviare la configurazione.

  Avviso

  L'esecuzione di a365 cleanup è distruttiva.

  a365 cleanup
  a365 setup all
  

Consenso amministratore non completato

Sintomo: hai aperto delle finestre del browser durante la configurazione ma le hai chiuse senza completare il consenso oppure la configurazione è stata completata ma le concessioni di autorizzazione OAuth2 sono ancora in sospeso.

Soluzione: scegli a seconda del tuo ruolo:

• Amministratore globale: esegui di nuovo a365 setup all. La CLI richiede il consenso amministrativo. Completa il flusso di consenso nella finestra del browser che appare.

• Amministratore ID agente o sviluppatore: non puoi completare direttamente le concessioni OAuth2. Esegui a365 setup all: il riepilogo dell'installazione elenca i passaggi successivi per un Amministratore globale, incluso un collegamento diretto o un URL di consenso per completare le autorizzazioni. Condividi questi dettagli con il tuo Amministratore globale.

File di configurazione mancante o non valido

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

Soluzione:

1. Verifica che il file a365.config.json esista.
2. Se manca o non è valido, crealo manualmente oppure usa a365 setup all --agent-name <name> (solo per agenti).

# Verify a365.config.json exists
Test-Path a365.config.json

La configurazione viene completata ma le risorse non vengono create

Sintomo: il comando di configurazione ha successo ma le risorse Azure non sono presenti.

Soluzione:

1. Controlla le risorse create aprendo a365.generated.config.json nella tua directory di lavoro.
2. Verifica che le risorse Azure esistano usando il comando az resource list.
3. Se mancano risorse, controlla eventuali errori nell'output di configurazione e riavviala usando il comando a365 setup all.

# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# 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 dell'agente non registrato in Microsoft Entra

Sintomo: l'installazione è completata ma non riesci a trovare il progetto dell'agente nell'interfaccia di amministrazione di Microsoft Entra.

Soluzione:

1. Ottieni ID blueprint da a365.generated.config.json.

   Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId
   

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

   1. Vai a: Interfaccia di amministrazione di Microsoft Entra.
   2. Vai a Registrazioni app>Tutte le applicazioni.
   3. Cerca il agentBlueprintId.

3. Se non trovato, ripeti la configurazione utilizzando il comando a365 setup all.

   a365 setup all
   

Autorizzazioni API non concesse

Sintomo: la configurazione è stata completata, ma le autorizzazioni risultano "Non concesse" in Microsoft Entra.

Soluzione:

1. Apri l'interfaccia di amministrazione di Microsoft 365.

2. Trova la registrazione del progetto dell'app per il tuo agente.

3. Vai ad Autorizzazioni API.

4. Concedere il consenso amministratore:

   1. Seleziona Concedi consenso amministratore per [il tuo tenant].
   2. Conferma l'azione.

5. Verifica che tutti i permessi abbiano una spunta verde.

Identità gestita non abilitata

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

Soluzione:

1. Controlla lo stato dell'identità gestita tramite il comando az webapp identity show.
2. Se non è attivato, abilitalo manualmente usando il comando az webapp identity assign.
3. Verifica che sia abilitato tramite il comando az webapp identity show.

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

L'installazione richiede troppo tempo o smette di rispondere

Sintomo: il comando di configurazione resta in esecuzione per più di 10 minuti senza completare.

Soluzione:

1. Se sei un amministratore globale, verifica se una finestra del browser è in attesa del consenso amministratore. Completa il flusso di consenso per sbloccare la procedura di configurazione.

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

   # Check generated config
   Get-Content a365.generated.config.json | ConvertFrom-Json
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. Esegui la pulizia e riprova.

   a365 cleanup
   a365 setup all
   

Pulisci un agente senza configurazione

Sintomo: hai fornito un agente a365 setup all --agent-name <name> e ora vuoi rimuoverlo, ma non hai un file a365.config.json.

Soluzione: usa a365 cleanup --agent-name per rimuovere l'agente senza un file di configurazione. L'interfaccia della riga di comando legge gli ID risorsa dalla configurazione globale generata scritta durante la configurazione iniziale.

a365 cleanup --agent-name <your-agent-name>

Se non hai più la configurazione generata globalmente (ad esempio, dopo aver reinstallato la CLI), usa a365 cleanup con un a365.config.json minimo creato manualmente oppure rimuovi le risorse direttamente tramite portale di Azure e Interfaccia di amministrazione di Microsoft Entra.

Impossibile inviare il primo messaggio in Teams

Sintomo: Dopo il provisioning di un'istanza dell'agente, non riesce a inviare al gestore agenti un messaggio come il messaggio di benvenuto.

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

• Per l'implementazione, configura le autorizzazioni ereditabili del blueprint per includere l'ambito Chat.Create.
• Configura un messaggio di chat di Teams da inviare dopo il provisioning di un'istanza dell'agente.
• Crea una nuova istanza di agente dal blueprint e testa il messaggio di prima esecuzione.