Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
La CLI di Agent 365 è uno strumento a riga di comando multipiattaforma per distribuire e gestire applicazioni Agent 365 su Azure. Questo riferimento spiega come installare, aggiornare, disinstallare e utilizzare la CLI per automazione e risoluzione dei problemi.
Non è necessario installare la CLI manualmente.Agent 365 Skill controlla la CLI, installa o aggiorna automaticamente e esegue tutti i comandi necessari per tuo conto. Questo articolo è un riferimento per gli sviluppatori che devono installare o utilizzare direttamente la CLI - ad esempio, quando si costruisce automazione CI/CD, si lavora per risolvere problemi di un passaggio specifico o si lavora senza un agente di codifica AI.
Note
Il flusso di lavoro per sviluppatori completo, tra cui la configurazione guidata tramite intelligenza artificiale, le linee guida per i ruoli e i passaggi post-distribuzione, è disponibile in Introduzione allo sviluppo di Agent 365. Questo articolo è il riferimento alla CLI: installazione, aggiornamento, disinstallazione, comandi disponibili e risoluzione dei problemi.
Prerequisiti
L'interfaccia della riga di comando richiede .NET 8.0 o versione successiva. Per tutti gli altri prerequisiti, inclusi un abbonamento Azure e ruoli Entra obbligatori, vedi Avvio Rapido: Collega un agente esistente all'Agente 365.
autenticazione Microsoft Entra
Di default, la configurazione di Agent 365 utilizza l'applicazione enterprise Agent 365 CLI gestita da Microsoft quando è disponibile nel tuo tenant.
| Proprietà | Value |
|---|---|
| Nome visualizzato | Agent 365 CLI |
| ID applicazione (cliente) | f54280f4-395e-4ea8-9e48-bf2d4952aa14 |
Per verificare l'applicazione, vai al centro Interfaccia di amministrazione di Microsoft Entra, seleziona Applicazioni> EnterpriseTutte le applicazioni e cerca l'ID applicazione. L'Object ID del committente del servizio è unico per il tuo inquilino. Non usare l'ID oggetto dove la CLI o la documentazione richiedono un ID dell'applicazione (client).
La CLI verifica la presenza dell'entità servizio dell'applicazione aziendale nel tuo tenant e convalida gli ambiti delegati richiesti nel token di accesso. Non crea né modifica la registrazione delle applicazioni di Microsoft. L'applicazione gestita da Microsoft non eleva l'utente connesso, non bypassa Accesso Condizionale o Valori Predefiniti di Sicurezza, né elimina requisiti di consenso separati per le risorse dell'agente.
Se l'applicazione aziendale gestita da Microsoft non è disponibile, la configurazione senza impostazioni cerca un'app del tenant denominata Agent 365 CLI. Le configurazioni esistenti che specificano un custom clientAppId rimangono supportate. Per le istruzioni, consulta Registrazione dell'app client personalizzata per la CLI dell'Agente 365.
L'applicazione gestita da Microsoft utilizza questi metodi di autenticazione interattivi:
| Ambiente | Metodo di autenticazione |
|---|---|
| Windows nativi | Web Account Manager (WAM) |
| sottosistema Windows per Linux (WSL), macOS e Linux | Codice del dispositivo |
Le applicazioni personalizzate di proprietà del tenant utilizzano il browser di sistema quando il WAM non è disponibile.
Installa la CLI di Agent 365
Usa la procedura seguente per installare l'interfaccia della riga di comando di Agent 365 a livello globale nel sistema operativo.
Prerequisiti
È necessario aver installato .NET. È consigliabile .NET 8.0.
Usare il comando dotnet tool install
Installare l'interfaccia della riga di comando di Agent 365 usando il comando seguente:
dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli
Per le istruzioni più recenti e le versioni disponibili, visitare la pagina ufficiale di NuGet: Microsoft.Agents.A365.DevTools.Cli su NuGet.org
Verifica l'installazione
Dopo aver installato la CLI di Agent 365, verifica che sia installata correttamente eseguendo il --help comando:
a365 -h
Questo comando visualizza le informazioni di aiuto e conferma che l'interfaccia della riga di comando è pronta per l'uso.
Aggiorna la CLI dell'Agente 365
Aggiorna l'interfaccia della riga di comando di Agent 365 usando il comando di aggiornamento dello strumento DotNet :
dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli
Note
Per aggiornare la CLI dell'Agent 365, è necessario una connessione internet per accedere all'ultimo pacchetto NuGet: Microsoft.Agents.A365.DevTools.Cli.
Disinstalla la CLI dell'Agent 365
Disinstalla Agent 365 CLI usando il comando dotnet tool uninstall:
dotnet tool uninstall --global Microsoft.Agents.A365.DevTools.Cli
Posizioni dei file CLI dell'Agente 365
Il percorso predefinito per il file eseguibile di uno strumento dipende dal sistema operativo:
| Sistema operativo | Percorso |
|---|---|
| Linux/macOS | $HOME/.dotnet/tools |
| Windows | %USERPROFILE%\.dotnet\tools |
L'SDK aggiunge questa posizione al tuo percorso quando lo esegui per la prima volta. Quindi puoi invocare strumenti globali da qualsiasi directory senza specificare la posizione dello strumento.
L'accesso agli strumenti è specifico dell'utente, non globale del computer. Uno strumento globale è disponibile solo per l'utente che lo installa.
Comandi CLI dell'Agente 365
Per l'elenco completo dei comandi disponibili, usa il --help comando o consulta Agent 365 CLI Reference.
Tip
Non è necessario eseguire manualmente i comandi dell'interfaccia della riga di comando. Le competenze di Agent 365 automatizzano l'intero flusso di lavoro - installazione, configurazione della CLI, configurazione, distribuzione e pubblicazione dei blueprint - utilizzando un agente di codifica AI. Consulta qui la guida di riferimento per l'interfaccia della riga di comando se stai costruendo l'automazione CI/CD, per risolvere i problemi di un passaggio specifico o se si lavora senza un agente di codifica basato su intelligenza artificiale.
Per istruzioni complete su come configurare un agente agent 365 usando l'interfaccia della riga di comando, vedere Introduzione allo sviluppo di Agent 365.
Troubleshooting
Questa sezione fornisce informazioni su come risolvere errori con la CLI dell'Agente 365.
Tip
La Guida alla risoluzione dei problemi dell'Agente 365 contiene raccomandazioni di alto livello, best practice e link a contenuti di risoluzione dei problemi per ogni fase del ciclo di sviluppo dell'Agente 365.
Questioni specifiche per la CLI trattate in questa sezione:
- L'applicazione CLI Agent 365 gestita da Microsoft non è disponibile
- L'autenticazione tramite codice dispositivo è bloccata
- L'autenticazione fallisce con AADSTS70007
- Gli ambiti delegati richiesti mancano
- L'agente non appare in Teams
- Non si può creare un'istanza di agente in Teams
L'applicazione CLI Agent 365 gestita da Microsoft non è disponibile
Aggiorna la CLI e riprova a365 setup requirements . Per verificare se la distribuzione graduale ha raggiunto il tuo tenant, cerca Applicazioni aziendali in Microsoft Entra per l'ID applicazione f54280f4-395e-4ea8-9e48-bf2d4952aa14.
Se l'entità servizio non è presente, la configurazione torna a un'app di proprietà del tenant chiamata Agent 365 CLI. Se non hai già quell'app, segui la registrazione dell'app client personalizzata per la CLI dell'Agente 365.
L'autenticazione tramite codice dispositivo è bloccata
L'applicazione gestita da Microsoft utilizza l'autenticazione tramite codice dispositivo su WSL, macOS e Linux. Security Defaults o una policy di Accesso Condizionato possono bloccare questo flusso e restituire AADSTS530035.
Non disabilitare la policy di sicurezza della tua organizzazione per aggirare questo errore. Esegui la CLI su Windows nativo per usare WAM, oppure collabora con il tuo amministratore di identità per utilizzare un'applicazione personalizzata di proprietà del tenant e un flusso di autenticazione consentito dalla tua policy.
L'autenticazione fallisce con AADSTS70007
Le versioni CLI più vecchie potrebbero utilizzare una modalità di risposta del browser non supportata con l'applicazione gestita da Microsoft e restituire AADSTS70007. Aggiornamento all'ultima versione della CLI e riprova:
dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli
Mancano le autorizzazioni delegate richieste
La CLI verifica le autorizzazioni delegate effettive dell'applicazione gestita da Microsoft a partire dal claim scp del token di accesso. Aggiorna la CLI e riavvia a365 setup requirements.
Non aggiungere URI di reindirizzamento, richieste opzionali, permessi API o concessioni di permessi locali per il tenant all'applicazione gestita da Microsoft. Se la convalida segnala ancora scope mancanti, acquisisci gli ID di traccia e di correlazione dall'errore e contatta il supporto Microsoft. Se usi un'app di proprietà del tenant, segui i passaggi di validazione nella registrazione personalizzata dell'app client per l'Agent 365 CLI.
L'agente non appare in Teams
Risoluzione dei problemi delle istanze degli agenti: Un agente non appare in Teams
Non si può creare un'istanza di agente in Teams
Risoluzione problemi di creazione di istanze agenti: Non si può creare istanze agenti in Teams