Condividi tramite

Configurazione di Agent 365

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.

La CLI di Agent 365 necessita di informazioni sul tuo tenant, sull'abbonamento e su altri dettagli per creare le risorse agent necessarie come Agent Blueprint. La CLI memorizza queste informazioni in un file di configurazione centrale chiamato a365.config.json nella tua directory di lavoro. Tutti i comandi della CLI utilizzano questo file di configurazione.

Prerequisiti

Prima di iniziare, assicurarsi di avere i prerequisiti seguenti:

Autorizzazioni necessarie:

  • Utente tenant Microsoft Entra valido con uno dei ruoli seguenti:
    • Amministratore globale
    • Amministratore ID Agente
    • Sviluppatore Agente ID
  • Accesso a una sottoscrizione Azure con autorizzazioni per creare risorse

Configura la CLI dell'Agent 365

Il a365 config init comando crea a365.config.json, il file di configurazione centrale usato da tutti i comandi CLI dell'Agent 365, nella tua directory di lavoro. L'interfaccia della riga di comando offre una procedura guidata interattiva con integrazione Azure CLI e impostazioni predefinite intelligenti per ridurre al minimo l'input manuale.

Eseguire l'autenticazione con Azure

Prima di inizializzare la configurazione, eseguire l'autenticazione con Azure usando il comando az login:

az login

Seleziona la sottoscrizione appropriata quando richiesto. La configurazione guidata usa Azure CLI per eseguire query su sottoscrizioni, gruppi di risorse e piani di servizio app disponibili. Per un'esperienza di sviluppo fluida, configura il tuo account utente tenant con il ruolo e i permessi giusti, abbonamenti e piano di servizi app prima di iniziare.

Inizializzare la configurazione

Esegui il a365 config init comando per avviare il wizard di configurazione interattiva:

a365 config init

La procedura guidata utilizza l'integrazione con Azure CLI e valori predefiniti ottimali per ridurre al minimo l'inserimento manuale. Ti viene richiesto:

Campo Description Example
Client App ID Il tuo ID di registrazione personalizzato dell'app client 00001111-aaaa-2222-bbbb-3333cccc4444
Percorso del progetto di distribuzione Percorso alla directory del tuo progetto agente C:\MyAgent\sample-agent
Indirizzo e-mail del responsabile E-mail del responsabile che supervisiona questo agente manager@yourtenant.com
sottoscrizione Azure Selezionare le sottoscrizioni disponibili Azure Selezione interattiva
Gruppo di risorse Seleziona l'esistente o crea un nuovo gruppo di risorse Selezione interattiva
Piano di servizio app Seleziona il piano di servizio esistente o crea un nuovo piano di servizio app Selezione interattiva
Ubicazione Azure regione per la distribuzione eastus, canadacentral

Il wizard genera automaticamente i nomi delle risorse correlate (web app, identità dell'agente, blueprint, utente agente) e convalida il tipo di progetto. Prima di salvare, è possibile configurare facoltativamente le autorizzazioni personalizzate del progetto per le risorse esterne (ad esempio la presenza di Teams o i file OneDrive) e personalizzare uno dei nomi generati.

Scopri di più sulla struttura dei file di configurazione

Verifica i file di configurazione dell'Agent 365

L'Agent 365 utilizza più file di configurazione durante tutto il ciclo di sviluppo:

File Scopo Momento della creazione Modifica manualmente?
a365.config.json Impostazioni fornite dall'utente Dopo a365 config init Yes
a365.generated.config.json Valori generati dalla CLI (ID agente, ID risorse) Dopo a365 setup NO
.env oppure appsettings.json Variabili dell'ambiente di esecuzione Crei per lo sviluppo locale Yes

Dopo aver completato la configurazione, verifica di avere i seguenti elementi:

Verifica la creazione del a365.config.json file

Verifica visivamente che il a365.config.json file esista. Oppure, usa il comando PowerShell Test-Path in uno script per automatizzare questa verifica.

# Check file exists in current working directory
Test-Path a365.config.json
# Should return: True

Verifica a365.config.json i dati di configurazione

Esegui il a365 config display comando per visualizzare la configurazione attuale della CLI dell'Agent 365.

a365 config display

L'output di questo comando è questo:

{
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "resourceGroup": "your-resource-group",
  "location": "location-of-your-azure-resources",
  "environment": "prod",
  "needDeployment": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "appServicePlanName": "your-app-service-plan",
  "appServicePlanSku": "service-plan-sku",
  "webAppName": "your-web-app",
  "agentIdentityDisplayName": "your-agent-name Identity",
  "agentBlueprintDisplayName": "your-agent-name Blueprint",
  "agentUserPrincipalName": "youragent@yourtenant.onmicrosoft.com",
  "agentUserDisplayName": "your-agent-name Agent User",
  "managerEmail": "manager@yourtenant.com",
  "agentUserUsageLocation": "usage-location",
  "deploymentProjectPath": "C:\\path\\to\\your\\project",
  "agentDescription": "your-agent-name - Agent 365 Agent"
}

Lista di controllo per la verifica

✅ Tutti i campi hanno valori validi (nessuna stringa vuota o nulli)
✅ tenantId e subscriptionId sono GUID validi
✅ clientAppId è un GUID valido (la registrazione della tua app client personalizzata)
✅ resourceGroup e appServicePlanName esistono nella sottoscrizione di Azure
✅ managerEmail Usa il tuo dominio tenant
✅ deploymentProjectPath indica la directory del codice dell'agente
✅ agentUserPrincipalName segue il formato agentname@tenant.com
✅ environment è impostato (tipicamente prod)
✅ needDeployment è true per la configurazione iniziale. Se non hai bisogno di deployment, impara a impostare un endpoint di messaggistica agente.

Se la tua configurazione non corrisponde all'output atteso, consulta la sezione Troubleshooting per soluzioni dettagliate.

Suggerimento

Tieni un backup del tuo a365.config.json fascicolo. Puoi sottoscriverlo al controllo del fonte (non contiene segreti).

Aggiungere a365.generated.config.json nel .gitignore file. Questo file contiene segreti generati e non deve mai essere committato nel controllo del codice sorgente.

Passo successivo

Se tutto va bene, sei pronto a procedere.

Blueprint dell'agente di configurazione

Risoluzione dei problemi

Usa questi passaggi per diagnosticare rapidamente e risolvere i problemi comuni con a365.config.json la CLI dell'Agent 365.

Il file di configurazione non esiste

Sintomo: I comandi CLI falliscono con "Configurazione non trovata" o Test-Path a365.config.json restituiscono False.

Soluzione: Crea un nuovo a365.config.json file.

Completare i passaggi per Authenticate con Azure e Initialize configuration.

Valori di configurazione mancanti o non validi

Sintomo: Il file di configurazione esiste ma presenta campi vuoti o errori di validazione.

Soluzione: Segui i passaggi per verificare a365.config.json i dati di configurazione.

Se qualche campo è errato:

  • Opzione 1: Riesegui la procedura guidata usando il a365 config init comando.
  • Opzione 2: Modifica a365.config.json manualmente con i valori corretti.

Tenant o sottoscrizione non validi

Sintomo: La CLI fallisce con errori di autenticazione o autorizzazione.

Soluzione:

Usare questi comandi per ripetere l'autenticazione con Azure, verificare l'account connesso, passare alla sottoscrizione corretta e reinizializzare la configurazione dell'interfaccia della riga di comando di Agent 365.

# Re-authenticate with Azure
az login

# Verify you're logged into the correct account
az account show

# If needed, switch to the correct subscription
az account set --subscription "<subscription-name-or-id>"

# Re-initialize configuration
a365 config init

La convalida dell'app client personalizzata ha esito negativo

Sintomo: La guida di configurazione fallisce quando si convalida l'ID dell'app client personalizzato.

Soluzione: Rivedi la registrazione personalizzata dell'app client per assicurarti che la registrazione abbia tutti i permessi necessari e il consenso dell'amministratore.

Nome dell'entità utente dell'agente non valido

Sintomo: La convalida non riesce per il nome principale utente dell'agente durante il processo di configurazione.

Soluzione: Verificare che l'UPN segua il formato username@domain. Ad esempio: demo.agent@contoso.onmicrosoft.com. Un suffisso di dominio mancante è la causa più comune.

Nome dell'app Web già utilizzato

Sintomo: L'installazione non riesce perché il nome dell'app Web è già in uso.

Solution: i nomi delle app Web devono essere globalmente univoci in Azure. Esegui l'aggiornamento di webAppName in a365.config.json impostandolo a un valore univoco, oppure riesegui a365 config init per generare un nuovo nome.

  • Last updated on