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

Sintassi

a365 setup [command] [options]

Options

Ordine di esecuzione consigliato

# 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, un amministratore globale deve completare le concessioni:

# Non-admin path: run setup, then hand off to Global Administrator
a365 setup all

# Global Administrator completes OAuth2 grants
a365 setup admin --config-dir "<path-to-config-folder>"

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.

Opzioni requirements

setup blueprint

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

Autorizzazioni minime necessarie: ruolo sviluppatore ID agente

a365 setup blueprint [options]

Opzioni blueprint

setup permissions

Configurare le autorizzazioni OAuth2 concede ed ereditabili le autorizzazioni.

Autorizzazioni minime necessarie: Amministratore globale

a365 setup permissions [command] [options]

Options

Sottocomandi

setup permissions mcp

Configurare il server MCP OAuth2 concede e eredita autorizzazioni ereditabili.

Autorizzazioni minime necessarie: Amministratore globale

a365 setup permissions mcp [options]

Questo comando:

• 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.

Opzioni permissions mcp

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.

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

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. Aggiungere autorizzazioni personalizzate a a365.config.json usando a365 config permissions prima di eseguire questo comando.

a365 setup permissions custom [options]

Questo comando:

• 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

Configurare autorizzazioni personalizzate

Usare a365 config permissions per aggiungere autorizzazioni personalizzate alla configurazione prima di eseguire questo comando:

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

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

# Apply all configured custom permissions
a365 setup permissions custom

Durante l'installazione, il nome della risorsa viene risolto automaticamente da Azure. Non è necessario specificarlo nella configurazione.

Rimuovere autorizzazioni personalizzate

Per rimuovere le autorizzazioni personalizzate sia dalla configurazione che dalla Microsoft Entra:

# Step 1: Remove from config
a365 config permissions --reset

# Step 2: Reconcile Microsoft Entra with updated config
a365 setup permissions custom

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. Progetto
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]

Questo comando:

• 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

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:

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. Visualizza i passaggi successivi che illustrano come un amministratore globale può completare le concessioni OAuth2 usando a365 setup admin o gli URL di consenso generati.

Autorizzazioni minime richieste:

• Ruolo sviluppatore ID agente (per la creazione del progetto)
• Amministratore globale (per le concessioni di autorizzazione OAuth2, se non disponibile, usare setup admin handoff)

Opzioni setup all

Configurazione dell'agente

Per impostazione predefinita, a365 setup all esegue il flusso dell'agente. Questo flusso crea un agente senza una dipendenza team di Dataverse o di intelligenza artificiale. Funziona per gli agenti che comunicano direttamente con la piattaforma Agent 365 senza richiedere una licenza del team di intelligenza artificiale.

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

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

Per eseguire invece il flusso del compagno di squadra di intelligenza artificiale, passare --aiteammate true.

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).

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.

Consenso amministratore durante l'installazione

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 si è un amministratore globale, rifiutare e usare il setup admin flusso di lavoro di consegna.

Sincronizzazione della configurazione

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

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-instance-only per riprovare solo a tale passaggio senza ripetere il lavoro precedente:

a365 setup all --agent-instance-only

setup admin

Completa le concessioni di autorizzazione OAuth2 (consenso amministratore) che richiedono l'amministratore globale. Eseguire questo comando dopo l'esecuzione a365 setup alldi un amministratore dell'ID agente o di un ID agente.

Autorizzazioni minime necessarie: Amministratore globale

a365 setup admin [options]

Quando usare setup admin

Usare questo comando quando:

• Dopo l'esecuzione a365 setup alldi un agente ID amministratore o ID agente sviluppatore.
• Il riepilogo dell'installazione mostra che le concessioni OAuth2 sono in sospeso e indica all'amministratore globale di eseguire questo comando.
• Si vogliono rieseguire le concessioni di consenso dopo la modifica delle autorizzazioni nella configurazione.

Flusso di lavoro di handoff tipico

# Step 1: Agent ID Admin or Developer runs setup
a365 setup all

# The CLI displays next steps, for example:
# "ACTION REQUIRED — Global Administrator must complete OAuth2 grants"
# "Option 1: a365 setup admin --config-dir '<path-to-config-folder>'"
# "Option 2: Share the consent URL displayed above with your Global Administrator"

# Step 2: Agent ID Admin shares config folder with Global Administrator
# (contains a365.config.json and a365.generated.config.json)

# Step 3: Global Administrator completes the grants
a365 setup admin --config-dir "<path-to-config-folder>"

Questo comando:

• Carica la configurazione dell'agente dalla directory specificata o dalla directory corrente per impostazione predefinita.
• Legge l'ID progetto agente e le autorizzazioni di risorsa configurate dalla configurazione generata.
• Crea AllPrincipals concessioni di autorizzazioni OAuth2 per tutte le risorse configurate, tra cui:
  • Microsoft Graph (ambiti delegati)
  • Strumenti agente 365 (ambiti server MCP)
  • API bot di messaggistica
  • API Osservabilità
  • API di Power Platform
  • Eventuali autorizzazioni personalizzate definite nella configurazione
• Visualizza una richiesta di conferma prima di apportare modifiche. Usare --yes per ignorare il prompt.

Opzioni setup admin

Alternativa: URL di consenso

Anziché eseguire a365 setup admin, l'amministratore globale può aprire l'URL di consenso combinato che a365 setup all salva in a365.generated.config.json. Questo URL copre tutte le risorse necessarie in un'unica visita al browser.

# Display the generated config to find the consent URL
a365 config display -g
# Look for: combinedAdminConsentUrl