Configurare il progetto dell'agente

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 directory di lavoro, impostato tramite questo passaggio: Impostazione della configurazione di Agent 365.

   Suggerimento

   Gli agenti (non i colleghi di intelligenza artificiale) possono ignorare la creazione di file di configurazione. Usa a365 setup all --agent-name <name> e la CLI risolve automaticamente il tenant e l'app client. Consulta Configurazione senza necessità di impostazioni con --agent-name.

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.

Installazione dell'agente (impostazione predefinita):

# With a config file
a365 setup all

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

Configurazione del compagno di squadra di intelligenza artificiale:

a365 setup all --aiteammate true

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
   • Applicazione Web di Azure con identità gestita abilitata

2. Registra il blueprint dell'agente:

   • Crea il modello agente nel tenant di Microsoft Entra
   • Crea registrazioni di applicazioni di Microsoft Entra
   • Configura l'identità dell'agente con le autorizzazioni necessarie
   • Imposta managerApplications nel progetto, necessario per la gestibilità della piattaforma

   Importante

   I blueprint devono avere managerApplications impostato per essere accettati dalla piattaforma. L'interfaccia a riga di comando lo imposta automaticamente. Se hai un blueprint esistente creato prima dell'introduzione di questo requisito, eliminalo ed esegui di nuovo a365 setup all, oppure correggilo manualmente tramite il 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 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

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 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 di OAuth2 (AllPrincipals consent) per Microsoft Graph, Agent 365 Tools, API Bot di Messaggistica, API di Osservabilità e API della 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

Al termine dell'installazione, viene visualizzato un riepilogo 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 blueprint
   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. Verificare le risorse di Azure in portale di Azure

   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:

     • Passare 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. Verifica le applicazioni di Microsoft Entra in portale di Azure:

   Passare a Azure Active Directory>Registrazioni app>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 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. Blueprint di Verify Agent registrato in Microsoft Entra:

   In Interfaccia di amministrazione di Microsoft Entra, cerca il 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 tenant]"

Per ulteriori aiuti, vedi:

• problemi di configurazione
• Problemi con app client personalizzate

Autorizzazioni dell'agente

Prima che le app e gli agenti possano leggere o scrivere dati Microsoft 365 (utenti, posta elettronica, file, Teams, agenti e così via), è necessario concedere in modo esplicito le autorizzazioni 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 di 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 in Amministrazione Microsoft 365 Center, 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:

• Visualizzare tutte le autorizzazioni graph disponibili.
• Visitare Graph Explorer per provare le query, esaminare le risposte e comprendere le autorizzazioni.
• Usare Microsoft 365 Agents Playground per testare l'agente in locale prima della distribuzione.

Applicare le autorizzazioni al blueprint

Usare a365 config permissions per aggiungere le autorizzazioni necessarie per la risorsa 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:

Risoluzione dei problemi

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

Questi problemi si verificano a volte durante la registrazione:

• Errore di permessi insufficienti
• Autenticazione CLI di Azure mancante
• La risorsa esiste già
• Consenso amministrativo non completato
• File di configurazione mancanti o invalidi
• L'installazione si completa ma le risorse non vengono create
• Progetto dell'agente non registrato in Microsoft Entra
• Permessi API non concessi
• Identità gestita non abilitata
• Il programma di installazione richiede troppo tempo o smette di rispondere
• Pulizia di un agente privo di configurazione
• Impossibile inviare il primo messaggio in Teams

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

Accesso di collaboratore o proprietario della sottoscrizione di Azure.

Solution: Verificare di disporre delle autorizzazioni necessarie in Microsoft Entra.

• Passare a: Interfaccia di amministrazione di Microsoft Entra> Il profilo > Ruoli assegnati
• Controllare l'accesso all'abbonamento Azure usando il comando PowerShell az account show

Autenticazione interfaccia della riga di comando di Azure mancante

Sintomo: La configurazione fallisce con errori di autenticazione.

Solution: Assicurarsi di essere connessi a 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
  

Consenso amministrativo non completato

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. Controllare le risorse create tramite il 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

Symptom: Il programma di installazione viene completato, ma non è possibile trovare il modello dell'agente nel centro di amministrazione di Microsoft Entra.

Soluzione:

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

   a365 config display -g
   # Look for: agentBlueprintId
   

2. Cercare nel centro amministrativo di Microsoft Entra:

   1. Passare a: Interfaccia 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

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

Soluzione:

1. Aprire Interfaccia di amministrazione di Microsoft Entra.

2. Trova la registrazione del progetto dell'app per il tuo 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 si esegue 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
   

Pulire un agente senza bisogno di configurazione

Sintomo: È stato effettuato il provisioning di un agente con a365 setup all --agent-name <name> e ora si vuole rimuoverlo, ma non si dispone di un a365.config.json file.

Soluzione: Usare a365 cleanup --agent-name per rimuovere l'agente senza un file di configurazione. La CLI legge gli ID risorsa dalla configurazione globale generata scritta durante la configurazione iniziale.

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

Se non si dispone più della configurazione generata globale (ad esempio, dopo aver reinstallato il CLI), usare a365 cleanup con un a365.config.json minimale creato manualmente o rimuovere 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 messaggio di benvenuto.

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.
• Configura 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.