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 dell'Agente 365 deve conoscere il tuo inquilino, l'abbonamento e altri dettagli per creare le risorse necessarie come l'Agente 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 valido di Microsoft Entra tenant con uno dei seguenti ruoli:
    • Amministratore globale
    • Amministratore ID Agente
    • Sviluppatore ID Agente
  • Accesso a una sottoscrizione di Azure con autorizzazione 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. CLI offre una procedura guidata interattiva con l'integrazione dell'interfaccia di CLI di Azure e le impostazioni predefinite intelligenti per ridurre al minimo l'input manuale.

Eseguire l'autenticazione con Azure

Prima di inizializzare la configurazione, autentica con Azure usando il az login comando:

az login

Seleziona la sottoscrizione appropriata quando richiesto. La configurazione guidata usa l'interfaccia della riga di comando di Azure 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 usa l'integrazione dell'interfaccia della riga di comando di Azure e le impostazioni predefinite intelligenti per ridurre al minimo l'input manuale. Ti viene chiesto per:

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 della directory del progetto dell'agente C:\MyAgent\sample-agent
Indirizzo e-mail del responsabile E-mail del responsabile che supervisiona questo agente manager@yourtenant.com
Sottoscrizione di Azure Seleziona tra gli abbonamenti Azure disponibili 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 region for deployment 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.

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 o 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 nel tuo abbonamento 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).

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.

Completa i passaggi per Autenticare con Azure e Inizializzare la configurazione.

Valori di configurazione mancanti o invalidi

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 il mago usando il a365 config init comando.
  • Opzione 2: Modifica a365.config.json manualmente con i valori corretti.

Inquilino o abbonamento non valido

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

Soluzione:

Usa questi comandi per riautenticarti con Azure, verificare l'account effettuato l'accesso, passare all'abbonamento corretto e riavviare la configurazione della CLI dell'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 validazione dell'app client personalizzata fallisce

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.

  • Last updated on