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.
Informazioni di riferimento sul comando dell'interfaccia della riga di comando di Agent 365
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. |
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, 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.jsonLegge dall'oggettodeploymentProjectPathspecificato ina365.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
deploymentProjectPathpunti alla cartella del progetto contenente il file aggiornatoToolingManifest.json. Se lo sviluppatore aggiunge server MCP in un computer diverso, condividere prima l'aggiornamentoToolingManifest.jsoncon l'amministratore globale. L'esecuzione senza la correzioneToolingManifest.jsonnon 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.Allad esempio eMcpServers.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
| 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 è:
- Blueprint
- 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:
- Completa tutti i passaggi che può eseguire (creazione del progetto e autorizzazioni ereditabili).
- Genera URL di consenso per amministratore per risorsa e li salva in
a365.generated.config.json. - 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 s2soppureboth; 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:
- Requirements validation— controlla i ruoli e i prerequisiti Azure.
- La creazione diBlueprint crea o riutilizza l'applicazione Entra ID Agent Blueprint.
- 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.
- La creazione dell'identitàagente crea un'identità dell'agente in Entra ID tramite l'identità dell'agente API Graph.
- Registrazione dell'agente : registra l'agente tramite l'API di registrazione dell'agente AgentX V2.
-
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-idper eseguire l'override. -
ClientAppId viene risolto cercando un'app Entra denominata
Agent 365 CLInel 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 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