Esegui l'onboarding di un singolo agente con Agent 365 CLI

Usa la CLI di Agent 365 per creare gli oggetti identità di Microsoft Entra per un agente e registra l'agente con Agent 365. Inizia con un solo agente non produttivo così puoi convalidare identità, permessi, consenso e registrazione prima di configurare gli agenti in blocco.

Questo articolo utilizza Expense Review come nome base per un agente standard che esamina le note spese per conto di un dipendente registrato. Utilizza l'autenticazione on-behalf-of (OBO) e non necessita di un proprio account utente Microsoft Entra, della casella di posta o presenza su Teams.

Il flusso di lavoro senza configurazione crea:

  • Un modello di identità dell'agente chiamato Expense Review Blueprint.
  • Un'identità di agente chiamata Agente di Revisione delle Spese.
  • Concessioni di autorizzazioni delegate per l'autenticazione OBO.
  • Una registrazione Agent 365 per l'agente.
  • Un file a365.generated.config.json che registra gli identificatori generati e lo stato di configurazione.

Per una spiegazione degli oggetti identità, vedi Agent 365 identity.

Prerequisites

Prima di iniziare, assicurati di avere:

  • Un tenant Microsoft con Agent 365 abilitato. Usa un tenant non produttivo o un ambiente di test per questa guida.
  • Un abbonamento Azure nello stesso tenant.
  • Il ruolo Contributor sull'abbonamento Azure.
  • È necessario almeno il ruolo di Agent ID Developer in Microsoft Entra ID per creare il blueprint e l'identità dell'agente.
  • È disponibile un Amministratore Globale per concedere le autorizzazioni OAuth. Se ricopri questo ruolo, puoi completare il flusso di lavoro in una sola sessione. Altrimenti, la CLI fornisce URL di consenso da inviare a un Amministratore Globale.
  • È necessario il ruolo di Amministratore dell'applicazione o Amministratore globale se cambi lo scenario per usare l'autenticazione service-to-service (S2S).
  • .NET 8.0 o successivo.
  • L'interfaccia della riga di comando di Azure, con accesso effettuato al tenant e all'abbonamento che vuoi usare.
  • La CLI di Agent 365.

La configurazione dell'Agent 365 utilizza l'applicazione enterprise Agent 365 CLI gestita da Microsoft quando è disponibile nel tuo tenant. Il suo ID applicazione (client) è f54280f4-395e-4ea8-9e48-bf2d4952aa14. Se l'applicazione non è disponibile, la CLI cerca un'applicazione di proprietà del tenant chiamata Agent 365 CLI. Un Amministratore Globale può creare e configurare un'applicazione di proprietà del tenant dal prompt CLI. Per dettagli sul fallback, vedi Registrazione personalizzata dell'app client per Agent 365 CLI.

Note

Questo scenario non crea un utente agente. Gli account agente sono necessari solo quando un agente richiede le proprie risorse Microsoft 365 con licenza, come una casella di posta, e sono disponibili solo per i tenant che partecipano al programma di anteprima Frontier.

Installa la CLI di Agent 365

Installa la CLI come uno strumento .NET globale:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli

Se la CLI è già installata, aggiornala:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

Verificare l'installazione:

a365 --version

Per la risoluzione dei problemi di installazione e i percorsi dei file supportati, vedi Installa e usa la CLI dell'Agente 365.

Seleziona il tenant e l'abbonamento

Accedere a Azure:

az login

Elenca gli abbonamenti disponibili sul tuo account:

az account list --output table

Seleziona l'abbonamento nel tenant dove vuoi eseguire l'onboarding dell'agente:

az account set --subscription "<subscription-id-or-name>"

Conferma il tenant attivo e l'abbonamento:

az account show --query "{tenantId:tenantId, subscriptionId:id, subscriptionName:name}" --output table

Annota l'ID del tenant. La CLI lo rileva dall'account interfaccia della riga di comando di Azure attivo. Puoi anche fornirlo esplicitamente usando --tenant-id.

Valida i prerequisiti

Esegui il controllo dei requisiti da qualsiasi directory:

a365 setup requirements

Il comando verifica l'autenticazione, l'accesso ad Azure, la registrazione del tenant, i ruoli e l'applicazione client. Continua dopo un controllo fallito così puoi rivedere tutti i problemi rilevati insieme.

Risolvi ogni controllo obbligatorio non riuscito prima di continuare. Se l'applicazione enterprise gestita da Microsoft non è disponibile, segui il prompt per selezionare o creare un'applicazione client di proprietà del tenant e poi rieseguire il comando.

Important

Non modificare l'applicazione CLI Agent 365 gestita da Microsoft. L'interfaccia della riga di comando convalida la sua entità servizio e gli ambiti nel tuo token di accesso, ma non modifica la registrazione dell'applicazione Microsoft.

Anteprima dei cambiamenti di onboarding

Crea una directory di lavoro vuota per la configurazione generata, e poi cambia in essa:

New-Item -ItemType Directory -Path .\expense-review-agent
Set-Location .\expense-review-agent

Visualizza in anteprima le modifiche senza creare oggetti tenant:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false `
    --dry-run

Esamina l'ID tenant, i nomi degli oggetti derivati, l'applicazione client selezionata, i permessi e la modalità di autenticazione. Questo scenario utilizza la modalità di autenticazione predefinita obo perché l'agente agisce per un dipendente già loggato.

Se il tenant rilevato non è corretto, specificalo esplicitamente:

a365 setup all `
    --agent-name "Expense Review" `
    --tenant-id "<tenant-id>" `
    --aiteammate false `
    --dry-run

Eseguire l'onboarding dell'agente

Esegui lo stesso comando senza --dry-run:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false

La CLI valida nuovamente i requisiti, crea il blueprint e l'identità dell'agente, configura i permessi delegati, registra l'agente e scrive a365.generated.config.json.

Se accedi come Amministratore Globale, completa qualsiasi richiesta di consenso che si apre durante la configurazione. Se utilizzi invece il ruolo di Sviluppatore ID Agente o Amministratore ID Agente, la CLI completa i passaggi consentiti dal tuo ruolo e stampa le azioni di consenso per un Amministratore Globale. Invia gli URL di consenso generati all'Amministratore Globale e chiedigli di completare ogni grant.

Note

La configurazione senza impostazioni manuali presuppone che l'agente sia ospitato esternamente. Non crea risorse di hosting Azure né aggiorna un progetto agente.

Verifica il risultato dell'onboarding

Rivedi il riepilogo della configurazione. Ogni passaggio richiesto dovrebbe risultare completato. Se un Amministratore Globale deve ancora concedere il consenso, completa quel passaggio prima di considerare l'onboarding concluso.

Ispezionare la configurazione generata:

Get-Content .\a365.generated.config.json | ConvertFrom-Json

Conferma che l'output contiene:

  • Un ID di progetto dell'agente.
  • Stato di configurazione completata, senza azioni di consenso in sospeso.

Conferma che il riepilogo di configurazione riporti la creazione dell'identità dell'agente e la registrazione dell'agente avvenute con successo.

Poi verifica la registrazione nel interfaccia di amministrazione di Microsoft 365:

  1. Vai all'interfaccia di amministrazione di Microsoft 365.
  2. Seleziona agenti>Tutti gli agenti.
  3. Trova Expense Review Agent.
  4. Apri l'agente e conferma che i dettagli di identità e registrazione corrispondano alla configurazione generata.

Risolvere i problemi di onboarding

Sintomo Resolution
Il controllo dei requisiti segnala il tenant o l'abbonamento sbagliato. Esegui az account set --subscription "<subscription-id-or-name>", verifica il risultato con az account show, e rifai il controllo dei requisiti. In alternativa, passa --tenant-id a a365 setup all.
L'applicazione CLI Agent 365 gestita da Microsoft non è stata trovata. Aggiorna la CLI e riavvia a365 setup requirements. Se il lancio a fasi non è ancora arrivato al tuo tenant, usa un'applicazione client di proprietà del tenant.
La configurazione segnala che manca un ruolo. Assegnare i ruoli di Contributor e Agent ID Developer all'operatore. Lascia il tempo alle assegnazioni di propagarsi, accedi di nuovo e rifai il controllo dei requisiti.
La configurazione si completa ma elenca le azioni di consenso in sospeso. Fai aprire da un Amministratore Globale ogni URL di consenso stampato dalla CLI e concedere i permessi richiesti.
Il progetto o l'identità esistono, ma l'agente non è in Tutti gli agenti. Rivedi il riepilogo di configurazione per un errore nella registrazione dell'agente. Dopo aver risolto l'errore, riesegui a365 setup all --agent-name "Expense Review" --agent-registration-only.
La configurazione ha selezionato il pattern di autenticazione sbagliato. Usa la modalità OBO predefinita quando l'agente agisce per un utente che ha effettuato l'accesso. Da usare --authmode s2s per lavori di background o --authmode both quando sono necessari entrambi i pattern. I finanziamenti S2S richiedono l'Amministratore delle Applicazioni o l'Amministratore Globale.

Per risoluzioni più specifiche per la CLI, vedi Agent 365 troubleshooting.

Passaggi successivi

  • Ultimo aggiornamento: