Configurazione di Agent 365

Importante

È necessario far parte del programma di anteprima Frontier per ottenere l'accesso early a Microsoft Agent 365. Frontier ti connette direttamente con le ultime innovazioni di intelligenza artificiale di Microsoft. 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.

L'interfaccia della riga di comando di Agent 365 deve conoscere il tenant e altri dettagli per creare le risorse dell'agente necessarie, ad esempio 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.

Suggerimento

Quando si sta configurando un agente (non un compagno di AI), non è necessario creare a365.config.json manualmente. Usa a365 setup all --agent-name <name> e la CLI risolve automaticamente il tenant e l'app client. Vedere Impostazione senza configurazione con --agent-name.

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

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.

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 con Azure CLI e default intelligenti per ridurre al minimo l'input 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 della directory del progetto dell'agente. L'impostazione predefinita è la directory corrente (.) se non specificata. C:\MyAgent\sample-agent
Compagno di squadra di intelligenza artificiale Indica se le istanze dell'agente fornite da questo modello ottengono la propria identità utente. Quando true, ogni istanza dell'agente ha un ID utente dedicato. Quando false, l'agente opera solo con un'identità dell'applicazione e le istanze non ottengono i singoli ID utente. Vedere Modalità di gestione delle identità degli agenti. true / false
Indirizzo e-mail del responsabile E-mail del responsabile che supervisiona questo agente manager@yourtenant.com

La procedura guidata genera automaticamente nomi di risorse correlati (identità agente, progetto, 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

Autorizzazioni di progetto personalizzate

Se l'agente deve accedere alle risorse oltre il set predefinito (Microsoft Graph, API bot di messaggistica, API Observability, Power Platform), dichiararli nel campo customBlueprintPermissions di a365.config.json:

{
  "customBlueprintPermissions": [
    {
      "resourceAppId": "00000003-0000-0000-c000-000000000000",
      "resourceName": "Microsoft Graph",
      "scopes": ["Mail.Read", "Mail.Send"]
    },
    {
      "resourceAppId": "<your-api-app-id>",
      "resourceName": "My Custom API",
      "scopes": ["MyApi.ReadWrite"]
    }
  ]
}
Campo Description
resourceAppId ID dell'applicazione (client) dell'API della risorsa. Deve essere un GUID valido.
resourceName Nome visualizzato per la risorsa (usato nei log e nei riepiloghi).
scopes Elenco degli ambiti di autorizzazione delegata OAuth2 da concedere al blueprint.

Dopo aver aggiunto autorizzazioni personalizzate a a365.config.json, applicarle al progetto:

a365 setup permissions custom

Oppure includerli nella configurazione completa:

a365 setup all

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",
  "environment": "prod",
  "aiTeammate": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "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 è un GUID valido
✅ clientAppId è un GUID valido (la registrazione della tua app client personalizzata)
✅ managerEmail usa il dominio del tenant
✅ deploymentProjectPath indica la directory del codice dell'agente
✅ agentUserPrincipalName segue il formato agentname@tenant.com
✅ environment è impostato (tipicamente prod)

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 sottoposto al commit nel controllo del codice sorgente.

Passo successivo

Se tutto va bene, sei pronto a procedere.

Blueprint dell'agente di configurazione

Configurazione senza necessità di configurazione con --agent-name

È possibile effettuare il provisioning degli agenti (non dei colleghi di intelligenza artificiale) senza creare un a365.config.json file. L'interfaccia della riga di comando risolve automaticamente i valori necessari in fase di esecuzione.

# Provision an Agent without a config file
a365 setup all --agent-name <your-agent-name>

Quando si specifica --agent-name:

  • L'interfaccia della riga di comando rileva automaticamente l'identificativo del tenant da az account show. Se necessario, sostituirlo con --tenant-id <id>.
  • La CLI trova una registrazione di un'app Entra denominata Agent 365 CLI nel tenant per gestire l'app client. Non è necessario includere clientAppId nella configurazione.
  • Per impostazione predefinita, il percorso del progetto di distribuzione è la directory corrente. Eseguire il comando dalla cartella del progetto agente.

Importante

Il tenant deve avere un'app Entra denominata Agent 365 CLI con il consenso amministratore concesso. Se l'interfaccia della riga di comando segnala che non riesce a trovare l'app, chiedere a un amministratore globale di registrarla.

Per pulire le risorse di cui è stato effettuato il provisioning senza un file di configurazione:

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

La funzione di pulizia legge gli ID risorsa dal file di configurazione globale generato dalla configurazione di bootstrap, quindi non è richiesto a365.config.json.

Annotazioni

La configurazione senza configurazione è supportata solo per gli agenti. La configurazione del compagno di intelligenza artificiale richiede a365.config.json inizializzato con a365 config init. Vedere Modalità di gestione delle identità degli agenti.

Modalità di gestione delle identità degli agenti

Il aiTeammate campo controlla il provisioning delle istanze dell'agente e l'identità che possiedono durante l'esecuzione. Scegliere la modalità corretta in base alle operazioni che l'agente deve eseguire.

Annotazioni

Agent è l'impostazione predefinita. L'esecuzione a365 setup all senza flag aggiuntivi provisiona un agente. Invece, utilizzare --aiteammate true per configurare un compagno AI.

Modalità Valore della proprietà aiTeammate Default Identità dell'istanza dell'agente
Standard (agente dell'applicazione) false Yes Agent opera con un'identità dell'applicazione; Le istanze non ottengono i singoli ID utente
Compagno di squadra di intelligenza artificiale true NO Ogni istanza dell'agente ottiene la propria identità utente (ID utente)

Modalità standard (aiTeammate: false) - impostazione predefinita

Usare questa modalità quando l'agente funge da servizio o integrazione back-end, ovvero elaborazione di messaggi, risposta agli eventi o chiamata di API, senza bisogno di un'identità utente per ogni istanza. Questa modalità amplia la gamma di agenti che è possibile compilare: qualsiasi servizio che comunica con la piattaforma Agent 365 può essere registrato come agente, anche se non rappresenta un utente o partecipa alle esperienze di collaborazione rivolte agli utenti.

Questa modalità è l'impostazione predefinita. Eseguire l'installazione senza flag o passare --aiteammate false in modo esplicito:

# Standard setup (default)
a365 setup all

# Equivalent explicit form
a365 setup all --aiteammate false

Gli agenti supportano anche il provisioning senza configurazione tramite --agent-name. Vedere Impostazione senza configurazione con --agent-name.

Modalità compagno di squadra di intelligenza artificiale (aiTeammate: true)

Usare questa modalità quando l'agente deve fungere da partecipante di prima classe insieme agli utenti umani, ad esempio partecipare a riunioni, inviare messaggi per conto di un utente o assegnare attività in un flusso di lavoro. Le istanze dell'agente di cui è stato effettuato il provisioning in questa modalità ricevono un'identità utente dedicata, consentendo alla piattaforma di identificare e interagire singolarmente con ogni istanza.

La configurazione del compagno di intelligenza artificiale richiede un a365.config.json inizializzato con a365 config init. Passare --aiteammate true per selezionare questa modalità:

a365 setup all --aiteammate true

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 inizializzare la configurazione.

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 valido

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.

  • Last updated on