Blueprint dell'Agente di Configurazione

Il progetto dell'agente definisce l'identità, i permessi e i requisiti infrastrutturali del tuo agente. Crea ogni istanza di agente da questo blueprint 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 ID agente
     • Sviluppatore ID agente
   • Accesso a una sottoscrizione di Azure con autorizzazione per creare risorse

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

Crea blueprint per creare agente

Usa il a365 setup comando per creare risorse Azure e registrare il tuo 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 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 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

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

Verificare l'installazione

Dopo la fine della configurazione, vedi un riassunto che mostra tutti i passaggi completati. Verificare 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",
   "botMessagingEndpoint": "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	Azure managed identity authentication	Dovrebbe essere un GUID valido
   agentBlueprintId	L'identificatore unico del tuo agente	Utilizzato nel Portale Sviluppatori e nel centro amministrativo
   agentBlueprintObjectId	Microsoft Entra ID di Blueprint
   botMessagingEndpoint	Routing dei messaggi	Dove Teams/Outlook inviano messaggi al tuo agente
   agentBlueprintClientSecret	Segreto dell'autenticazione	Dovrebbe esistere (il valore è mascherato)
   resourceConsents	Autorizzazioni API	Dovrebbe contenere risorse come Microsoft Graph, Agent 365 Tools, API Messaging Bot, API di Observability
   completed	Stato di configurazione	Dovrebbe essere true

2. Verify Azure resources in 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 (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

   • 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:

   Dovrebbe esserci un file chiamato a365.generated.config.json che contenga tutti i dati di configurazione.

   Puoi verificare che esista usando il comando PowerShell Test-Path .

   # 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. Verify Web App ha 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. Verifica il progetto dell'agente registrato a Entra:

   Nel centro amministrativi 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:

• problemi di configurazione
• Problemi con app client personalizzate

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 a volte si verificano durante la registrazione:

• Errore di permessi insufficienti
• Mancante l'autenticazione della CLI Azure
• 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 Entra
• Permessi API non concessi
• Identità gestita non abilitata
• La configurazione richiede troppo tempo o si blocca

Errore di permessi insufficienti

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

Ti serve uno dei seguenti ruoli nel tuo tenant Microsoft Entra:

• Amministratore globale
• Amministratore ID agente
• Sviluppatore ID agente

E accesso per contributori o proprietari di abbonamento Azure.

Soluzione: Verifica di avere i permessi necessari in Entra.

• Vai su: centro >amministrativo Microsoft Entra Il tuo profilo > Ruoli assegnati
• Controlla l'accesso tramite l'abbonamento Azure usando il az account show comando PowerShell

Mancante l'autenticazione della CLI Azure

Sintomo: La configurazione fallisce con errori di autenticazione.

Soluzione: Assicurati di essere connesso ad Azure e verifica il tuo account e l'abbonamento.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

La risorsa esiste già

Sintomo: La configurazione fallisce con Resource already exists errore per resource group, App Service Plan o Web App.

Soluzioni: Scegli una delle seguenti soluzioni

• 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

  Elimina il gruppo di risorse o rinomina le risorse e a365.config.json riavvia la configurazione.

  Puoi usare il az group delete comando 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

  Usa il cleanup comando per rimuovere tutte le risorse dell'Agent 365, poi il a365 setup all comando per riavviare la configurazione.

  Avvertimento

  Correre a365 cleanup è distruttivo

  a365 cleanup
  a365 setup all
  

Consenso amministrativo non completato

Sintomo: Le finestre del browser si aprono durante l'installazione ma le hai chiuse senza aver completato il consenso.

Soluzione: Esegui il a365 setup all comando. La CLI richiama il consenso dell'amministratore:

Completa tutti i flussi di consenso nelle finestre del browser che appaiono.

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, ri-inizializza usando il comando a365 config init.

# 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

Sintomo: Il comando di configurazione ha successo ma le risorse Azure non esistono.

Soluzione:

1. Controlla le risorse create usando il a365 config display -g comando.
2. Verifica l'esistenza delle risorse Azure usando il az resource list comando.
3. Se mancano risorse, verifica eventuali errori nell'output di configurazione e riesegui 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 dell'agente non registrato in Entra

Sintomo: L'installazione è completata ma non riesco a trovare il progetto dell'agente nel centro amministrazione Microsoft Entra.

Soluzione:

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

   a365 config display -g
   # Look for: agentBlueprintId
   

2. Cerca nel centro amministrativo Microsoft Entra:

   1. Vai su: centro amministrazione Microsoft Entra.
   2. Naviga su Registrazioni App Tutte>le domande
   3. Cerca il tuo agentBlueprintId

3. Se non è stato trovato, riavvia la configurazione usando il a365 setup all comando.

   a365 setup all
   

Permessi API non concessi

Sintomo: La configurazione si completa ma i permessi compaiono come "Non concessi" in Entra.

Soluzione:

1. Centro amministrativo di Open Microsoft Entra

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

3. Passare alle autorizzazioni api

4. Concedere il consenso dell'amministratore:

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

5. Verifica che tutti i permessi mostrino segni verdi

Identità gestita non abilitata

Sintomo: Esiste l'app web ma l'identità gestita non è abilitata.

Soluzione:

1. Controlla lo stato dell'identità gestita usando il az webapp identity show comando.
2. Se non è attivato, abilitalo manualmente usando il az webapp identity assign comando.
3. Verifica 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>

La configurazione richiede troppo tempo o si blocca

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

Soluzione:

1. Controlla se le finestre del browser stanno aspettando il consenso - completa tutti i flussi di consenso.

2. Se è davvero bloccato, annulla (Ctrl+C) e controlla cosa è stato creato:

   # Check generated config
   a365 config display -g
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. Pulisci e riprova:

   a365 cleanup
   a365 setup all