Referenční informace k příkazům rozhraní příkazového řádku setup agenta 365

Nastavte prostředí Agenta 365 s podrobnou kontrolou jednotlivých kroků. Tento příkaz spravuje počáteční instalační pracovní postup pro podrobné plány agenta 365.

Požaduje se roleMinimum: Azure Přispěvatel + Agent ID Developer

Note

Role, kterou uchováváte, určuje, kolik instalačního programu se dokončí v jednom spuštění. Globální správce může provést všechny kroky najednou. Správce ID agenta a vývojář agentních ID mohou dokončit všechny kroky kromě udělení oprávnění OAuth2 (souhlas administrátora), které vyžadují akci globálního administrátora. Po dokončení nastavení CLI vytiskne další kroky pro globálního správce přímo ve výstupu.

Syntax

a365 setup [command] [options]

Možnosti

Option Description
-?, , -h--help Zobrazení informací o nápovědě a využití
# 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

Nebo spusťte všechny kroky najednou:

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

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

Pokud používáte jako správce ID agenta nebo vývojář ID agenta (ne globální správce), a365 setup all provede všechny kroky s výjimkou udělení oprávnění OAuth2. Po dokončení výstup obsahuje další kroky pro Globálního administrátora, aby mohl granty dokončit — včetně přímého odkazu nebo URL souhlasu, kterou může otevřít.

setup requirements

Ověřte požadavky pro instalaci agenta 365. Spouští modulární kontroly požadavků a poskytuje pokyny pro případné problémy, které najde.

a365 setup requirements [options]

Tento příkaz spustí následující kroky:

  • Zkontroluje všechny požadavky potřebné pro instalaci agenta 365.
  • Hlásí všechny problémy s podrobnými pokyny k řešení.
  • Pokračuje ve kontrole všech požadavků, i když některé kontroly selžou.
  • Poskytuje souhrn všech kontrol na konci.

Tip

Pokud jste globální správce a Agent 365 CLI známá klientská aplikace není ve vašem tenantu, setup requirements automaticky vás vyzve k jejímu vytvoření. Zadejte existující ID aplikace nebo typ C pro vytvoření aplikace a udělení souhlasu administrátora v jednom kroku – není potřeba manuální registrace Entra.

requirements možnosti

Option Description
-v, --verbose Povolte podrobné protokolování.
--category <category> Provádějte kontroly pouze pro konkrétní kategorii, například Azure, Authentication, PowerShell nebo Tenant Enrollment.
-?, , -h--help Zobrazení informací o nápovědě a využití

Note

setup requirements Nevyžaduje konfigurační soubor – spusťte ho v jakémkoli adresáři.

setup blueprint

Vytvoření podrobného plánu agenta (Entra ID registrace aplikace)

Minimální požadovaná oprávnění: Role Vývojář ID agenta

a365 setup blueprint [options]

blueprint možnosti

Option Description
-n, --agent-name <name> Jméno základny agenta. Když tuto možnost poskytnete, konfigurační soubor nepotřebujete. Příkaz automaticky detekuje ID tenanta z az account show. Přepište to pomocí --tenant-id.
--tenant-id <tenantId> ID klienta Azure AD. Overrides auto-detection. Používejte s --agent-name.
-v, --verbose Zobrazit podrobný výstup.
--dry-run Zobrazit, co by příkaz udělal, aniž by ho spouštěl.
--skip-requirements Přeskočte kontrolu ověření požadavků. Používejte s opatrností.
--no-endpoint Neregistrujte koncový bod zasílání zpráv (jenom podrobný plán).
--endpoint-only Zaregistrovat jenom koncový bod zasílání zpráv. Vyžaduje existující podrobný plán.
--update-endpoint <url> Smažte stávající endpoint pro zprávy a registrujte nový s určenou URL.
--m365 Chovejte se s tímto agentem jako s agentem M365. Na a365 setup blueprint, účinkuje pouze s --endpoint-only nebo --update-endpoint. Pro registraci endpointu zpráv jako součást plného nastavení použijte a365 setup all --m365. Výchozí je ( false opt-in).
--show-secret Zobrazit uložené tajemství klienta blueprintu v otevřeném textu. Neprovádí se žádné nastavení nastavení. Na Windows je potřeba stejný počítač a uživatelský účet, který spouštěl nastavení.
-?, , -h--help Zobrazení informací o nápovědě a využití

setup permissions

Nakonfigurujte udělení oprávnění OAuth2 a zděděná oprávnění.

Minimální požadovaná oprávnění: Globální správce

a365 setup permissions [command] [options]

Možnosti

Option Description
-?, , -h--help Zobrazení informací o nápovědě a využití

Subcommands

Subcommand Description
mcp Nakonfigurujte server MCP OAuth2 a zděděná oprávnění.
bot Nakonfigurujte rozhraní API robota zasílání zpráv OAuth2 a zděděná oprávnění.
custom Použije vlastní oprávnění rozhraní API pro podrobný plán agenta, který překračuje standardní oprávnění požadovaná pro operaci agenta.
copilotstudio Nakonfiguruje oprávnění OAuth2 a zděděná oprávnění pro podrobný plán agenta k vyvolání Copilot Studio copilotů prostřednictvím rozhraní POWER Platform API.

setup permissions mcp

Nakonfigurujte server MCP OAuth2 a zděděná oprávnění.

Minimální požadovaná oprávnění: Globální správce

a365 setup permissions mcp [options]

This command:

  • ToolingManifest.json Čte ze zadaného parametru deploymentProjectPatha365.config.json .
  • Uděluje delegovaná oprávnění OAuth2 pro každý obor serveru MCP podrobnému plánu agenta.
  • Konfiguruje zděděná oprávnění, aby instance agenta mohly přistupovat k nástrojům MCP.
  • Je idempotentní a bezpečné spustit vícekrát.

Important

  • Před spuštěním tohoto příkazu ověřte, že směřuje deploymentProjectPath na složku projektu obsahující aktualizovanou ToolingManifest.json. Pokud vývojář přidá servery MCP na jiný počítač, nasdílejte aktualizace ToolingManifest.json nejprve globálnímu správci. Spuštění bez správného ToolingManifest.json nastavení nepřidá do podrobného plánu nová oprávnění serveru MCP.
  • Spusťte tento příkaz po spuštění a365 develop add-mcp-serversvývojáře . Přidání serverů MCP do manifestu a udělení oprávnění podrobnému plánu jsou dva samostatné kroky. Po dokončení tohoto příkazu se oprávnění serveru MCP zobrazí v podrobném plánu agenta.

permissions mcp možnosti

Option Description
-n, --agent-name <name> Jméno základny agenta. Když tuto možnost poskytnete, konfigurační soubor nepotřebujete.
--tenant-id <tenantId> ID klienta Azure AD. Overrides auto-detection. Používejte s --agent-name.
-v, --verbose Zobrazit podrobný výstup.
--dry-run Zobrazit, co by příkaz udělal, aniž by ho spouštěl.
--remove-legacy-scopes Odebere starší sdílené obory (McpServers.*.All formát) z podrobného plánu po migraci na oprávnění jednotlivých serverů (Tools.ListInvoke.All). Použití pouze poté, co je V2 SDK potvrzeno živé – agenti na V1 SDK ztratí přístup k nástrojům, pokud jsou předčasně odstraněni.
-?, , -h--help Zobrazení informací o nápovědě a využití

Migrace na oprávnění MCP pro jednotlivé servery

Používá se --remove-legacy-scopes při migraci ze starší verze modelu sdílených oprávnění na oprávnění pro jednotlivé servery:

  • Starší sdílený model: ID jedné aplikace prostředků (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) se sdílenými obory, jako McpServers.Mail.AllMcpServers.Teams.Alljsou a .
  • Model na server: Každý server MCP má vlastní ID aplikace s oborem Tools.ListInvoke.All.

Následující příklad ukazuje, jak se oprávnění jednotlivých serverů zobrazují v Centrum pro správu Microsoft Entra po použití podrobného plánu. Každý server MCP, například Pracovní IQ Calendar MCP a Work IQ Mail MCP, má svůj vlastní delegovaný Tools.ListInvoke.All obor. Sdílený McpServersMetadata.Read.All obor poskytuje přístup k metadatům serveru MCP.

Screenshot Centrum pro správu Microsoft Entra zobrazující oprávnění rozhraní API pro jednotlivé servery. Každý kalendář IQ Calendar MCP a Work IQ Mail MCP mají delegovaný rozsah Tools.ListInvoke.All. Work IQ Tools má delegovanou příponu McpServersMetadata.Read.All scope.

setup permissions bot

Nakonfigurujte rozhraní API robota zasílání zpráv OAuth2 a zděděná oprávnění.

Minimální požadovaná oprávnění: Globální správce

Požadavky: Oprávnění podrobného plánu a MCP (spusťte a365 setup permissions mcp nejprve)

a365 setup permissions bot [options]

permissions bot možnosti

Option Description
-n, --agent-name <name> Jméno základny agenta. Když tuto možnost poskytnete, konfigurační soubor nepotřebujete.
--tenant-id <tenantId> ID klienta Azure AD. Overrides auto-detection. Používejte s --agent-name.
-v, --verbose Zobrazit podrobný výstup.
--dry-run Zobrazit, co by příkaz udělal, aniž by ho spouštěl.
-?, , -h--help Zobrazení informací o nápovědě a využití

setup permissions custom

Použije vlastní oprávnění rozhraní API pro podrobný plán agenta, který překračuje standardní oprávnění požadovaná pro operaci agenta. Pomocí tohoto příkazu udělíte agentovi přístup k dalším Microsoft Graph oborům, jako je přítomnost, soubory a chat nebo vlastní rozhraní API zaregistrovaná v Microsoft Entra ID tenantovi vaší organizace.

Minimální požadovaná oprávnění: Globální správce

Požadavky: Nejprve spusťte a365 setup blueprint .

a365 setup permissions custom [options]

This command:

  • Nakonfiguruje delegovaná oprávnění OAuth2 s souhlasem správce pro každý nakonfigurovaný prostředek.
  • Nastaví zděděná oprávnění, aby uživatelé agenta mohli dědit přístup z podrobného plánu.
  • Srovná Microsoft Entra s aktuální konfigurací tím, že přidá nová oprávnění a odebere všechna oprávnění, která jste z konfigurace odstranili.
  • Je idempotentní a bezpečné spustit vícekrát.

permissions custom možnosti

Option Description
-n, --agent-name <name> Jméno základny agenta. Když tuto možnost poskytnete, konfigurační soubor nepotřebujete.
--tenant-id <tenantId> ID klienta Azure AD. Overrides auto-detection. Používejte s --agent-name.
-v, --verbose Zobrazit podrobný výstup.
--dry-run Zobrazit, co by příkaz udělal, aniž by ho spouštěl.
--resource-app-id <guid> Resource application ID (GUID) pro vlastní oprávnění v řadě. Používejte s --scopes.
--scopes <scopes> Delegované rozsahy oddělené čárkou pro vlastní oprávnění v řadě. Používejte s --resource-app-id.
-?, , -h--help Zobrazení informací o nápovědě a využití

Konfigurace vlastních oprávnění přímo v linii

Použití --resource-app-id a --scopes aplikace vlastních oprávnění přímo bez úprav 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

Název zdroje je automaticky vyřazen z Microsoft Entra. Nemusíte to specifikovat.

Nastavte vlastní oprávnění pomocí konfiguračního souboru

Alternativně přidat customBlueprintPermissions příkaz a a365.config.json spustit ho bez příznaků v textu:

a365 setup permissions custom

Tento příkaz sladí Microsoft Entra s nakonfigurovanými oprávněními – přidá nová oprávnění a odstraní všechna oprávnění, která jste z konfigurace smazali.

Integrace s aplikací setup all

Pokud konfigurace zahrnuje vlastní oprávnění, spuštění a365 setup all je automaticky nakonfiguruje jako součást jedné fáze dávkového oprávnění. Úplné pořadí nastavení je:

  1. Blueprint
  2. Dávka oprávnění (MCP, rozhraní API robota, vlastní oprávnění podrobného plánu – vše nakonfigurované společně)

setup permissions copilotstudio

Nakonfiguruje oprávnění OAuth2 a zděděná oprávnění pro podrobný plán agenta k vyvolání Copilot Studio copilotů prostřednictvím rozhraní POWER Platform API.

Minimální požadovaná oprávnění: Globální správce

Požadavky: Nejprve spusťte a365 setup blueprint .

a365 setup permissions copilotstudio [options]

This command:

  • Zajišťuje, že ve vašem tenantovi existuje instanční objekt rozhraní API Power Platform.
  • Vytvoří udělení oprávnění OAuth2 z podrobného plánu k rozhraní API Power Platform s oborem CopilotStudio.Copilots.Invoke .
  • Nastaví zděděná oprávnění, aby instance agenta mohly vyvolat Copilot Studio copiloty.

permissions copilotstudio možnosti

Option Description
-n, --agent-name <name> Jméno základny agenta. Když tuto možnost poskytnete, konfigurační soubor nepotřebujete.
--tenant-id <tenantId> ID klienta Azure AD. Overrides auto-detection. Používejte s --agent-name.
-v, --verbose Zobrazit podrobný výstup.
--dry-run Zobrazit, co by příkaz udělal, aniž by ho spouštěl.
-?, , -h--help Zobrazení informací o nápovědě a využití

Tento příkaz použijte, když váš agent potřebuje vyvolat Copilot Studio copiloty za běhu nebo volat rozhraní API Power Platform, která vyžadují oprávnění CopilotStudio.

setup all

Provedení všech kroků nastavení nastavení pro nastavení prostředí Agenta 365

a365 setup all [options]

Spustí kompletní instalaci agenta 365, všechny kroky postupně.

Zahrnuje: Podrobný plán a oprávnění.

Dokončení kroků závisí na vaší roli:

Step Global Administrator Správce ID agenta Vývojář agentního ID
Prerequisites check Yes Yes Yes
Vytvoření podrobného plánu agenta Yes Yes Yes
Dědičná oprávnění (pouze AI spoluhráči) Yes Yes Yes
Udělení oprávnění OAuth2 (souhlas správce) Yes Vyžaduje krok GA. Vyžaduje krok GA.
Identita agenta uděluje (--authmode s2s nebo both) Yes PowerShell fallback PowerShell fallback

Když spustíte a365 setup all bez globálního správce, rozhraní příkazového řádku:

  1. Dokončí všechny kroky, které může (vytvoření podrobného plánu a zděděná oprávnění).
  2. Vygeneruje adresy URL souhlasu správce prostředků a uloží je do a365.generated.config.json.
  3. Zobrazuje další kroky ve výstupu pro globálního administrátora pro dokončení grantů OAuth2, včetně přímého odkazu nebo souhlasné URL.

Tip

Pokud jste globální správce, a365 setup all dokončí vše v jediném spuštění bez nutnosti předání.

Minimální požadovaná oprávnění:

  • Role Vývojář ID agenta (pro vytvoření podrobného plánu)
  • Globální správce (pro udělení oprávnění OAuth2 – pokud nejsou dostupné, CLI vytiskne další kroky ve výstupu)
  • Aplikační administrátor nebo globální správce (pro S2S (server-to-server) agenta uděluje --authmode s2s identitu – nebo both; pokud není dostupný, CLI vytiskne PowerShell záložní příkaz v shrnutí nastavení)

setup all možnosti

Option Description
-v, --verbose Zobrazit podrobný výstup.
--dry-run Zobrazit, co by příkaz udělal, aniž by ho spouštěl.
--skip-requirements Přeskočte kontrolu ověření požadavků. Používejte s opatrností: Nastavení může selhat, pokud nejsou splněné požadavky.
--aiteammate Použijte tento parametr k nasměrování AI týmového agenta pouze na nastavení blueprintu a oprávnění. Bez tohoto parametru tok agenta blueprintu automaticky vytváří princip identity služby agenta bez uživatele Entra. Tento parametr přepisuje aiteammate pole v a365.config.json.
--authmode <mode> Autentizační vzor pro udělování oprávnění k identitě agenta (pouze agenti Blueprint). obo (výchozí) — Granty s hlavním zaměřením, bez nutnosti administrátorské role. s2s — přiřazení rolí aplikace na identitě agenta SP, vyžaduje správce aplikace nebo globálního administrátora; PowerShell záložní varianta vytištěná, pokud role chybí. both — uplatňuje granty OBO (On-Behalf-Of) a S2S. Není podpořeno .--aiteammate Lze také nastavit jako authMode .a365.config.json
--agent-registration-only Přeskočte kroky blueprintu a oprávnění a spouštějte pouze registraci agenta. Slouží k opakování kroku neúspěšné registrace.
--m365 Chovejte se s tímto agentem jako s agentem M365. Registruje endpoint pro zprávy přes MCP Platform. Výchozí je ( false opt-in).
-n, --agent-name <name> Základní název agenta (například "MyAgent"). Pokud je k dispozici, nevyžaduje se žádný konfigurační soubor. Odvozuje zobrazované názvy jako "<name> Identity" a "<name> Blueprint". ID tenanta je automaticky zjištěno ( az account show přepsáno pomocí --tenant-id). ClientAppId se vyřeší vyhledáním Agent 365 CLI v tenantovi.
--tenant-id <tenantId> ID klienta Azure AD. Přepíše automatickou detekci z az account show. Používá se --agent-name při spuštění v neinteraktivním prostředí nebo při cílení na konkrétního tenanta.
-?, , -h--help Zobrazení informací o nápovědě a využití

Agent setup

Ve výchozím nastavení běží a365 setup all blueprint agent flow. Tento tok vytvoří agenta bez závislosti týmu Dataverse nebo AI. Funguje to pro agenty, kteří komunikují přímo s platformou Agent 365.

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

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

Pro spuštění AI agentního toku místo toho přejdi .--aiteammate

Tento tok provádí následující kroky v posloupnosti:

  1. Requirements validation – kontroluje Azure role a požadavky.
  2. Vytvoření blueprintu – vytvoří nebo znovu použije aplikaci podrobného plánu agenta Entra ID.
  3. – konfiguruje delegovaná oprávnění k podrobnému plánu pro Microsoft Graph, Nástroje agenta 365, rozhraní API robota zasílání zpráv, rozhraní API pozorovatelnosti, Power Platform a všechny vlastní prostředky.
  4. Vytvoření identity agenta – vytvoří identitu agenta v Entra ID prostřednictvím Graph API identity agenta.
  5. Registrace agenta – zaregistruje agenta prostřednictvím rozhraní AGENTX V2 Agent Registration API.
  6. Synchronizace konfigurace – zapíše nastavení připojení za běhu a konfiguraci pozorovatelnosti do souborů projektu (appsettings.json, .env).

Note

Tok agentů AI Teammate vyžaduje další beta API oprávnění na vaší vlastní klientské aplikaci nad rámec základní sady. Viz Registrace vlastních klientských aplikací pro kompletní seznam požadovaných povolení.

Nastavení bez konfigurace s využitím --agent-name

Pokud soubor nemáte a365.config.json , použijte --agent-name ho ke spuštění instalace bez souboru. Rozhraní příkazového řádku automaticky rozpozná vašeho tenanta a vyřeší klientskou aplikaci vyhledáním známé Agent 365 CLI registrace aplikace ve vašem tenantovi.

# 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"

Při použití --agent-name:

  • Id tenanta je automaticky zjištěno z az account show. Předejte --tenant-id přepsání.
  • ClientAppId se vyřeší vyhledáním aplikace Entra pojmenované Agent 365 CLI ve vašem tenantovi. Pokud se nenajde, rozhraní příkazového řádku se ukončí s chybou. Informace o registraci této aplikace najdete v části Vlastní registrace klientské aplikace .
  • Zobrazované názvy se odvozují jako "<name> Agent" (identita) a "<name> Blueprint" (podrobný plán).
  • Infrastruktura se vždy přeskočí (předpokládá se externí hostování).
  • Synchronizace konfigurace (zápis appsettings.json) se přeskočí, protože není nakonfigurovaná žádná cesta k projektu.

Pokud vaše klientská aplikace nemá AllPrincipals souhlas správce s požadovanými oprávněními, rozhraní příkazového řádku to zjistí a zobrazí výzvu k interaktivnímu udělení souhlasu:

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

Zadejte, y abyste udělili souhlas v řádku. Pokud nejste globální administrátor, odmítněte — CLI vytiskne další kroky pro globálního administrátora v souhrnu nastavení.

Udělování identity agenta (--authmode)

Ve výchozím nastavení vytváří a365 setup all delegované granty s principálním rozsahem na agentovu identituobo (režim). Tyto granty nevyžadují administrativní roli.

Použití --authmode pro kontrolu typu grantu:

Value Behavior Minimum role
obo (výchozí) Delegované granty s principálním rozsahem na identitu agenta SP Žádný (žádný ověřený uživatel)
s2s Přiřazení rolí aplikace na identitě agenta SP Správce aplikací nebo globální administrátor
both Jak delegované granty OBO, tak přidělování rolí v aplikaci S2S Role S2S (výše) pro část 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

Když přihlášený uživatel nemá požadovanou roli pro udělení S2S, CLI vytiskne záložní blok PowerShellu v shrnutí nastavení. Administrátor ji může spustit a dokončit úkoly.

Nastaveno authMode tak a365.config.json , aby platilo při každém běhu bez této vlajky:

{
  "authMode": "s2s"
}

Note

--authmodenení podporován .--aiteammate AI týmoví agenti používají OBO automaticky prostřednictvím uživatelské identity agenta.

Config sync

Po úspěšném spuštění rozhraní příkazového řádku automaticky zapíše nastavení modulu runtime do souborů projektu:

Setting Written to Description
Connections.ServiceConnection appsettings.json / .env ID klienta podrobného plánu, tajný klíč klienta, ID tenanta a koncový bod tokenu
Agent365Observability appsettings.json / .env ID agenta (identita agenta), ID podrobného plánu, ID tenanta, ID klienta a tajný klíč klienta pro export telemetrie
TokenValidation appsettings.json Nastavení ověření tokenu (ve výchozím nastavení zakázáno pro jiné než DW)
ConnectionsMap appsettings.json / .env Výchozí adresa URL služby na mapování připojení

Rozhraní příkazového řádku vytvoří soubor, pokud neexistuje, a aktualizuje jednotlivá pole bez přepsání zbytku vaší konfigurace.

Opakování neúspěšné registrace

Pokud instalační program úspěšně dokončí podrobný plán a oprávnění, ale během registrace agenta selže, použijte --agent-registration-only k opakování pouze tento krok bez opakování předchozí práce:

a365 setup all --agent-registration-only