Blueprint dell'Agente di Configurazione

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.

Crea blueprint per 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 abilitata

2. Registra il blueprint dell'agente:

   • Crea il modello agente nel tenant di Microsoft Entra
   • Crea registrazioni delle applicazioni di 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

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",
   "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	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
   botMessagingEndpoint	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

2. Verifica le risorse di Azure 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:

     • Passare a Servizi app>Web Apps
     • 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 nel Azure Portal

   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 per applicazioni)
     • 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. 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. Verifica lo schema dell'agente registrato in Entra:

   In Microsoft Entra interfaccia di amministrazione, 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 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
• Autenticazione Azure CLI 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
• Schema 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 .

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

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

Accesso come collaboratore o proprietario della sottoscrizione di Azure.

Soluzione: Verifica di avere i permessi necessari in Entra.

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

Autenticazione Azure CLI mancante

Sintomo: La configurazione fallisce con errori di autenticazione.

Solution: Assicurarsi di essere connessi con 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: 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 oppure rinomina le risorse in a365.config.json ed esegui nuovamente 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 richiede nuovamente 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

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

Symptom: l'installazione viene completata, ma non è possibile trovare il modello di agente nel centro 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: Microsoft Entra interfaccia di amministrazione.
   2. Passare a App registrations>Tutte le applicazioni
   3. Trova 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. Aprire Microsoft Entra centro di amministrazione

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