Informazioni di riferimento sul comando dell'interfaccia della riga di comando di Agent 365 setup

Configurare l'ambiente Agent 365 con un controllo granulare su ogni passaggio. Questo comando gestisce il flusso di lavoro di installazione iniziale per i progetti agent 365.

Ruolo Minimum necessario: Azure Collaboratore + Agent ID Developer

Note

Il ruolo che si mantiene determina la quantità di completamento dell'installazione in una singola esecuzione. L'amministratore globale può completare tutti i passaggi contemporaneamente. L'Amministratore dell'ID Agente e lo Sviluppatore dell'ID Agente possono completare tutti i passaggi tranne la concessione dei permessi OAuth2 (consenso dell'amministratore), che richiedono un'azione da parte di un Amministratore Globale. Una volta completata la configurazione, la CLI stampa direttamente i passaggi successivi per l'Amministratore Globale nell'output.

Syntax

a365 setup [command] [options]

Options

Option Description
-?, -h, --help Mostra informazioni di aiuto e utilizzo.
# 0. Check prerequisites (optional)
a365 setup requirements

# 1. Create blueprint
a365 setup blueprint

# 2. Configure MCP permissions
a365 setup permissions mcp

# 3. Configure bot permissions
a365 setup permissions bot

# 4. Configure CopilotStudio permissions (if needed)
a365 setup permissions copilotstudio

# 5. Configure custom permissions (if needed)
a365 setup permissions custom

In alternativa, eseguire tutti i passaggi contemporaneamente:

# Full setup using config file (a365.config.json)
a365 setup all

# Config-free: no a365.config.json needed
a365 setup all --agent-name "MyAgent"

Se si esegue come Amministratore dell'ID Agente o ID Agente Sviluppatore (non Amministratore Globale), a365 setup all completa tutti i passaggi tranne le concessioni di autorizzazione OAuth2. Al termine, il risultato include i passaggi successivi per un Amministratore Globale per completare le sovvenzioni — incluso un link diretto o un URL di consenso che possono aprire.

setup requirements

Convalidare i prerequisiti per l'installazione di Agent 365. Esegue controlli dei requisiti modulari e fornisce indicazioni per eventuali problemi rilevati.

a365 setup requirements [options]

Questo comando esegue i passaggi seguenti:

  • Controlla tutti i prerequisiti necessari per l'installazione di Agent 365.
  • Segnala eventuali problemi con indicazioni dettagliate sulla risoluzione.
  • Continua a controllare tutti i requisiti anche se alcuni controlli hanno esito negativo.
  • Fornisce un riepilogo di tutti i controlli alla fine.

Tip

Se sei un Amministratore Globale e l'app client ben Agent 365 CLI nota non si trova nel tuo tenant, setup requirements ti viene chiesto di crearla automaticamente. Inserisci un ID app esistente o un tipo C per creare l'app e concedi il consenso dell'amministratore in un unico passaggio - senza bisogno di registrazione manuale su Entra.

Opzioni requirements

Option Description
-v, --verbose Abilitare la registrazione dettagliata.
--category <category> Esegui controlli solo per una categoria specifica, come Azure, Authentication, PowerShell o Tenant Enrollment.
-?, -h, --help Mostra informazioni di aiuto e utilizzo.

Note

setup requirements Non richiede un file di configurazione - eseguilo in qualsiasi directory.

setup blueprint

Creare un progetto agente (Entra ID registrazione dell'applicazione).

Autorizzazioni minime necessarie: ruolo sviluppatore ID agente

a365 setup blueprint [options]

Opzioni blueprint

Option Description
-n, --agent-name <name> Nome della base dell'agente. Quando offri questa opzione, non hai bisogno di un file di configurazione. Il comando rileva automaticamente l'ID tenant da az account show. Sovrascrivila con --tenant-id.
--tenant-id <tenantId> ID tenant di Azure AD. Overrides auto-detection. Usare con --agent-name.
-v, --verbose Mostra output dettagliato.
--dry-run Visualizzare le operazioni eseguite dal comando senza eseguirlo.
--skip-requirements Ignorare il controllo di convalida dei requisiti. Usare con cautela.
--no-endpoint Non registrare l'endpoint di messaggistica (solo progetto).
--endpoint-only Registrare solo l'endpoint di messaggistica. Richiede un progetto esistente.
--update-endpoint <url> Elimina l'endpoint di messaggistica esistente e registrane uno nuovo con l'URL specificato.
--m365 Considera questo agente come un agente M365. Registra l'endpoint di messaggistica tramite la piattaforma MCP. Il predefinito è false (opt-in).
-?, -h, --help Mostra informazioni di aiuto e utilizzo.

setup permissions

Configurare le autorizzazioni OAuth2 concede ed ereditabili le autorizzazioni.

Autorizzazioni minime necessarie: Amministratore globale

a365 setup permissions [command] [options]

Options

Option Description
-?, -h, --help Mostra informazioni di aiuto e utilizzo.

Subcommands

Subcommand Description
mcp Configurare il server MCP OAuth2 concede e eredita autorizzazioni ereditabili.
bot Configurare l'API bot di messaggistica OAuth2 concede e eredita autorizzazioni ereditabili.
custom Applica le autorizzazioni API personalizzate al progetto agente che superano le autorizzazioni standard necessarie per l'operazione dell'agente.
copilotstudio Configura le autorizzazioni OAuth2 concede ed eredita le autorizzazioni ereditabili per il progetto agente per richiamare Copilot Studio copiloti tramite l'API Power Platform.

setup permissions mcp

Configurare il server MCP OAuth2 concede e eredita autorizzazioni ereditabili.

Autorizzazioni minime necessarie: Amministratore globale

a365 setup permissions mcp [options]

This command:

  • ToolingManifest.json Legge dall'oggetto deploymentProjectPath specificato in a365.config.json.
  • Concede le concessioni di autorizzazioni delegate OAuth2 per ogni ambito del server MCP al progetto agente.
  • Configura le autorizzazioni ereditabili in modo che le istanze dell'agente possano accedere agli strumenti MCP.
  • È idempotente e sicuro da eseguire più volte.

Important

  • Prima di eseguire questo comando, verifica che deploymentProjectPath punti alla cartella del progetto contenente il file aggiornato ToolingManifest.json. Se lo sviluppatore aggiunge server MCP in un computer diverso, condividere prima l'aggiornamento ToolingManifest.json con l'amministratore globale. L'esecuzione senza la correzione ToolingManifest.json non aggiunge le nuove autorizzazioni del server MCP al progetto.
  • Eseguire questo comando dopo che lo sviluppatore esegue a365 develop add-mcp-servers. L'aggiunta di server MCP al manifesto e la concessione delle autorizzazioni al progetto sono due passaggi distinti. Al termine di questo comando, le autorizzazioni del server MCP sono visibili nel progetto agente.

Opzioni permissions mcp

Option Description
-n, --agent-name <name> Nome della base dell'agente. Quando offri questa opzione, non hai bisogno di un file di configurazione.
--tenant-id <tenantId> ID tenant di Azure AD. Overrides auto-detection. Usare con --agent-name.
-v, --verbose Mostra output dettagliato.
--dry-run Visualizzare le operazioni eseguite dal comando senza eseguirlo.
--remove-legacy-scopes Rimuove gli ambiti condivisi legacy (McpServers.*.All formato) dal progetto dopo la migrazione alle autorizzazioni per server (Tools.ListInvoke.All). Usalo solo dopo che l'SDK V2 è stato confermato attivamente - gli agenti sull'SDK V1 perdono l'accesso agli strumenti se rimossi prematuramente.
-?, -h, --help Mostra informazioni di aiuto e utilizzo.

Eseguire la migrazione alle autorizzazioni MCP per server

Usare --remove-legacy-scopes quando si esegue la migrazione dal modello di autorizzazioni condivise legacy alle autorizzazioni per server:

  • Modello condiviso legacy: ID app a singola risorsa (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) con ambiti condivisi, McpServers.Mail.All ad esempio e McpServers.Teams.All.
  • Modello per server: ogni server MCP ha il proprio ID app con l'ambito Tools.ListInvoke.All.

Nell'esempio seguente viene illustrato come vengono visualizzate le autorizzazioni per server nel Interfaccia di amministrazione di Microsoft Entra dopo l'applicazione del progetto. Ogni server MCP, ad esempio MCP Work IQ Calendar MCP e Work IQ Mail MCP, ha un proprio ambito delegato Tools.ListInvoke.All . Un ambito condiviso McpServersMetadata.Read.All fornisce l'accesso ai metadati del server MCP.

Screenshot del Interfaccia di amministrazione di Microsoft Entra che mostra le autorizzazioni API per server. McP Calendario IQ aziendale e McP mail IQ lavoro dispongono di un ambito Delegato Tools.ListInvoke.All. Work IQ Tools dispone di un delegato McpServersMetadata.Read.All scope.

setup permissions bot

Configurare l'API bot di messaggistica OAuth2 concede e eredita autorizzazioni ereditabili.

Autorizzazioni minime necessarie: Amministratore globale

Prerequisiti: autorizzazioni blueprint e MCP (esecuzione a365 setup permissions mcp prima)

a365 setup permissions bot [options]

Opzioni permissions bot

Option Description
-n, --agent-name <name> Nome della base dell'agente. Quando offri questa opzione, non hai bisogno di un file di configurazione.
--tenant-id <tenantId> ID tenant di Azure AD. Overrides auto-detection. Usare con --agent-name.
-v, --verbose Mostra output dettagliato.
--dry-run Visualizzare le operazioni eseguite dal comando senza eseguirlo.
-?, -h, --help Mostra informazioni di aiuto e utilizzo.

setup permissions custom

Applica le autorizzazioni API personalizzate al progetto agente che superano le autorizzazioni standard necessarie per l'operazione dell'agente. Usando questo comando, si concede all'agente l'accesso a ambiti di Microsoft Graph aggiuntivi, ad esempio Presenza, File e Chat o alle API personalizzate registrate nel tenant Microsoft Entra ID dell'organizzazione.

Autorizzazioni minime necessarie: Amministratore globale

Prerequisiti: eseguire a365 setup blueprint prima.

a365 setup permissions custom [options]

This command:

  • Configura le concessioni di autorizzazioni delegate OAuth2 con il consenso amministratore per ogni risorsa configurata.
  • Imposta le autorizzazioni ereditabili in modo che gli utenti dell'agente possano ereditare l'accesso dal progetto.
  • Riconcilia Microsoft Entra con la configurazione corrente aggiungendo nuove autorizzazioni e rimuovendo le autorizzazioni eliminate dalla configurazione.
  • È idempotente e sicuro da eseguire più volte.

Opzioni permissions custom

Option Description
-n, --agent-name <name> Nome della base dell'agente. Quando offri questa opzione, non hai bisogno di un file di configurazione.
--tenant-id <tenantId> ID tenant di Azure AD. Overrides auto-detection. Usare con --agent-name.
-v, --verbose Mostra output dettagliato.
--dry-run Visualizzare le operazioni eseguite dal comando senza eseguirlo.
--resource-app-id <guid> ID applicazione di risorsa (GUID) per un permesso personalizzato inline. Usare con --scopes.
--scopes <scopes> Scope delegati separati da virgole per il permesso personalizzato in linea. Usare con --resource-app-id.
-?, -h, --help Mostra informazioni di aiuto e utilizzo.

Configura i permessi personalizzati in linea

Usa --resource-app-id e --scopes applica direttamente i permessi personalizzati senza modifica a365.config.json:

# Add Microsoft Graph extended permissions
a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Presence.ReadWrite,Files.Read.All,Chat.Read

# Add custom API permissions
a365 setup permissions custom `
  --resource-app-id <your-api-app-id> `
  --scopes CustomScope.Read,CustomScope.Write

Il nome della risorsa viene risolto automaticamente da Microsoft Entra. Non è necessario specificarlo.

Configura i permessi personalizzati tramite file di configurazione

In alternativa, aggiungi customBlueprintPermissions ed a365.config.json esegui il comando senza flag inline:

a365 setup permissions custom

Questo comando riconcilia Microsoft Entra con i permessi configurati: aggiunge nuovi permessi e rimuove qualsiasi permesso che hai eliminato dalla configurazione.

Integrazione con setup all

Quando la configurazione include autorizzazioni personalizzate, l'esecuzione a365 setup all li configura automaticamente come parte di una singola fase di autorizzazione batch. L'ordine di installazione completo è:

  1. Blueprint
  2. Batch di autorizzazioni (MCP, API Bot, autorizzazioni di progetto personalizzate, tutte configurate insieme)

setup permissions copilotstudio

Configura le autorizzazioni OAuth2 concede ed eredita le autorizzazioni ereditabili per il progetto agente per richiamare Copilot Studio copiloti tramite l'API Power Platform.

Autorizzazioni minime necessarie: Amministratore globale

Prerequisiti: eseguire a365 setup blueprint prima.

a365 setup permissions copilotstudio [options]

This command:

  • Garantisce che l'entità servizio DELL'API Power Platform esista nel tenant.
  • Crea una concessione di autorizzazione OAuth2 dal progetto all'API power platform con l'ambito CopilotStudio.Copilots.Invoke .
  • Imposta autorizzazioni ereditabili in modo che le istanze dell'agente possano richiamare Copilot Studio copiloti.

Opzioni permissions copilotstudio

Option Description
-n, --agent-name <name> Nome della base dell'agente. Quando offri questa opzione, non hai bisogno di un file di configurazione.
--tenant-id <tenantId> ID tenant di Azure AD. Overrides auto-detection. Usare con --agent-name.
-v, --verbose Mostra output dettagliato.
--dry-run Visualizzare le operazioni eseguite dal comando senza eseguirlo.
-?, -h, --help Mostra informazioni di aiuto e utilizzo.

Usare questo comando quando l'agente deve richiamare Copilot Studio copiloti in fase di esecuzione o chiamare le API di Power Platform che richiedono le autorizzazioni di CopilotStudio.

setup all

Eseguire tutti i passaggi di installazione per configurare l'ambiente Agent 365

a365 setup all [options]

Esegue l'installazione completa di Agent 365, tutti i passaggi in sequenza.

Include: Progetto e autorizzazioni.

I passaggi completati dipendono dal ruolo:

Step Global Administrator Amministratore dell'ID agente Sviluppatore di ID Agente
Prerequisites check Yes Yes Yes
Creazione del progetto agente Yes Yes Yes
Permessi ereditabili (solo compagni IA) Yes Yes Yes
Concessioni di autorizzazione OAuth2 (consenso amministratore) Yes Richiede il passaggio ga Richiede il passaggio ga
Concede l'identità dell'agente (--authmode s2s o both) Yes Yes PowerShell fallback

Quando si esegue a365 setup all senza amministratore globale, l'interfaccia della riga di comando:

  1. Completa tutti i passaggi che può eseguire (creazione del progetto e autorizzazioni ereditabili).
  2. Genera URL di consenso per amministratore per risorsa e li salva in a365.generated.config.json.
  3. Mostra i passaggi successivi nell'output per un Amministratore Globale per completare le richieste OAuth2, incluso un link diretto o un URL di consenso.

Tip

Se si è un amministratore globale, a365 setup all completa tutti gli elementi in un'unica esecuzione senza alcun passaggio.

Autorizzazioni minime richieste:

  • Ruolo sviluppatore ID agente (per la creazione del progetto)
  • Amministratore Globale (per le concessioni di permessi OAuth2 - se non disponibili, la CLI stampa i passaggi successivi nell'output)
  • Agent ID Administrator, Application Administrator o Global Administrator (per le concessioni di identità di agente S2S (Server-to-Server) - --authmode s2s oppure both; se non disponibile, la CLI stampa un fallback PowerShell nel riassunto di configurazione)

Opzioni setup all

Option Description
-v, --verbose Mostra output dettagliato.
--dry-run Visualizzare le operazioni eseguite dal comando senza eseguirlo.
--skip-requirements Ignorare il controllo di convalida dei requisiti. Prestare attenzione: l'installazione potrebbe non riuscire se i prerequisiti non sono soddisfatti.
--aiteammate Usa questo parametro per indirizzare il flusso degli agenti del teammate IA a fornire solo blueprint e permessi. Senza questo parametro, il flusso dell'agente blueprint crea automaticamente il principale del servizio identità dell'agente senza alcun utente Entra. Questo parametro sovrascrive il aiteammate campo in a365.config.json.
--authmode <mode> Schema di autenticazione per la concessione dei permessi di identità degli agenti (solo agenti blueprint). obo (predefinito) — sovvenzioni delegate con ambito principale, nessun ruolo amministrativo necessario. s2s — assegnazioni di ruoli app sull'ID dell'agente, richiedono Agent ID Administrator, Application Administrator o Global Administrator; Fallback PowerShell stampato se il ruolo è assente. both — applica sovvenzioni OBO (On-Behalf-Of) e S2S. Non supportato da --aiteammate. Può anche essere impostato come authMode in a365.config.json.
--agent-registration-only Salta i passaggi di blueprint e permessi ed esegui solo la registrazione dell'agente. Usare per ripetere un passaggio di registrazione non riuscito.
--m365 Considera questo agente come un agente M365. Registra l'endpoint di messaggistica tramite la piattaforma MCP. Il predefinito è false (opt-in).
-n, --agent-name <name> Nome di base dell'agente (ad esempio, "MyAgent"). Se specificato, non è necessario alcun file di configurazione. Deriva i nomi visualizzati come "<name> Identity" e "<name> Blueprint". TenantId viene rilevato automaticamente da az account show (eseguire l'override con --tenant-id). ClientAppId viene risolto cercando Agent 365 CLI nel tenant.
--tenant-id <tenantId> ID tenant di Azure AD. Esegue l'override del rilevamento automatico da az account show. Usare con --agent-name quando è in esecuzione in un ambiente non interattivo o per specificare come destinazione un tenant specifico.
-?, -h, --help Mostra informazioni di aiuto e utilizzo.

Agent setup

Di default, a365 setup all esegue il flusso dell'agente blueprint. Questo flusso crea un agente senza una dipendenza team di Dataverse o di intelligenza artificiale. Funziona per agenti che comunicano direttamente con la piattaforma Agent 365.

# Default: uses a365.config.json
a365 setup all

# Or explicitly (same result)
a365 setup all --aiteammate false

Per eseguire invece il flusso di agenti dei compagni di squadra IA, passa --aiteammate.

Questo flusso esegue i passaggi seguenti in sequenza:

  1. Requirements validation— controlla i ruoli e i prerequisiti Azure.
  2. La creazione diBlueprint crea o riutilizza l'applicazione Entra ID Agent Blueprint.
  3. Batch permissions: configura le concessioni di autorizzazione delegate per il progetto per Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API, Power Platform ed eventuali risorse personalizzate.
  4. La creazione dell'identitàagente crea un'identità dell'agente in Entra ID tramite l'identità dell'agente API Graph.
  5. Registrazione dell'agente : registra l'agente tramite l'API di registrazione dell'agente AgentX V2.
  6. Sincronizzazione della configurazione: scrive le impostazioni di connessione di runtime e la configurazione di osservabilità nei file di progetto (appsettings.json, .env).

Note

L'installazione dell'agente richiede sei autorizzazioni API beta aggiuntive per l'app client personalizzata: AgentIdentityBlueprint.AddRemoveCreds.All, AgentIdentityBlueprint.DeleteRestore.AllAgentInstance.ReadWrite.AllAgentIdentity.ReadWrite.AllAgentIdentity.Create.Alle .AgentIdentity.DeleteRestore.All Per l'elenco completo, vedere Registrazione dell'app client personalizzata .

Configurazione senza configurazione con --agent-name

Se non si dispone di un a365.config.json file, usare --agent-name per eseguire il programma di installazione senza un file. L'interfaccia della riga di comando rileva automaticamente il tenant e risolve l'app client cercando la registrazione nota Agent 365 CLI dell'app nel tenant.

# Preview what would happen (no changes made)
a365 setup all --agent-name "MyAgent" --dry-run

# Run the full setup
a365 setup all --agent-name "MyAgent"

Quando si usa --agent-name:

  • TenantId viene rilevato automaticamente da az account show. Passare --tenant-id per eseguire l'override.
  • ClientAppId viene risolto cercando un'app Entra denominata Agent 365 CLI nel tenant. Se non viene trovato, l'interfaccia della riga di comando viene chiusa con un errore. Per informazioni su come registrare questa app, vedere Registrazione dell'app client personalizzata .
  • I nomi visualizzati sono derivati come "<name> Agent" (identità) e "<name> Blueprint" (progetto).
  • L'infrastruttura viene sempre ignorata (hosting esterno assunto).
  • La sincronizzazione della configurazione (scrittura appsettings.json) viene ignorata perché non è configurato alcun percorso di progetto.

Se l'app client non dispone AllPrincipals del consenso dell'amministratore per le autorizzazioni necessarie, l'interfaccia della riga di comando rileva questa operazione e chiede di concedere il consenso in modo interattivo:

The following permissions require admin consent:
  AgentIdentity.ReadWrite.All
  AgentIdentity.Create.All
  ...
Grant admin consent for these permissions now? [y/N]:

Immettere y per concedere il consenso in linea. Se non sei un Amministratore Globale, rifiuta — la CLI mostra i passaggi successivi per un Amministratore Globale nel riassunto di configurazione.

Concessioni di identità dell'agente (--authmode)

Di default, a365 setup all crea concessioni delegate con scopo principale sul principale del servizio identità dell'agente (obo modalità ). Questi finanziamenti non richiedono un ruolo amministrativo.

Utilizzare --authmode per controllare il tipo di finanziamento:

Value Behavior Minimum role
obo (impostazione predefinita) Grant delegati con scopo principale sull'identità dell'agente SP Nessuno (nessun utente autenticato)
s2s Assegnazioni dei ruoli dell'app sull'ID dell'agente SP Amministratore ID Agente, Amministratore Applicazione o Amministratore Globale
both Sia i finanziamenti delegati dagli OBO sia le assegnazioni di ruoli per le app S2S Ruolo S2S (sopra) per la parte S2S
# Default — OBO delegated grants (no admin role needed)
a365 setup all

# S2S app role assignments
a365 setup all --authmode s2s

# Both OBO and S2S
a365 setup all --authmode both

Quando l'utente connesso non ha il ruolo richiesto per le sovvenzioni S2S, la CLI stampa un blocco di riserva PowerShell nel riepilogo di configurazione. Un amministratore può gestirlo per completare gli incarichi.

Imposta authModea365.config.json in modo che si applichi ad ogni run senza il flag:

{
  "authMode": "s2s"
}

Note

--authmode non è supportato con --aiteammate. Gli agenti compagni IA usano automaticamente OBO tramite l'identità utente dell'agente.

Config sync

Dopo un'esecuzione corretta, l'interfaccia della riga di comando scrive automaticamente le impostazioni di runtime nei file di progetto:

Setting Written to Description
Connections.ServiceConnection appsettings.json / .env ID client del progetto, segreto client, ID tenant ed endpoint del token
Agent365Observability appsettings.json / .env ID agente (identità agente), ID progetto, ID tenant, ID client e segreto client per l'esportazione dei dati di telemetria
TokenValidation appsettings.json Impostazioni di convalida dei token (disabilitate per impostazione predefinita per non DW)
ConnectionsMap appsettings.json / .env Mapping predefinito dell'URL del servizio per la connessione

L'interfaccia della riga di comando crea il file se non esiste e aggiorna singoli campi senza sovrascrivere il resto della configurazione.

Ripetere una registrazione non riuscita

Se l'installazione completa correttamente il progetto e le autorizzazioni ma non riesce durante la registrazione dell'agente, usare --agent-registration-only per riprovare solo a tale passaggio senza ripetere il lavoro precedente:

a365 setup all --agent-registration-only