Agent 365 CLI-kommandoreference setup

Konfigurer dit Agent 365-miljø med detaljeret kontrol over hvert trin. Brug Agent 365 CLI-kommandoreferencen setup til at oprette blueprints, konfigurere tilladelser og fuldføre den indledende Agent 365 opsætningsarbejdsgang.

Minimum-rolle kræves: Azure Contributor + Agent ID Developer

Syntax

a365 setup [command] [options]

Indstillinger

Anbefalet udførelsesrækkefølge

# 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

Eller kør alle trin på én gang:

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

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

Hvis du kører som agent-id-administrator eller agent-id-udvikler (ikke global administrator), a365 setup all fuldføres alle trin undtagen OAuth2-tilladelsestilladelser. Når det er færdigt, indeholder outputtet de næste trin for en Global Administrator til at gennemføre bevillingerne — inklusive et direkte link eller samtykke-URL, de kan åbne.

Valg af klientapplikation

Når a365.config.json angiver en clientAppId, fortsætter opsætningen med at bruge den applikation. For konfigurationsfri opsætning bruger CLI'en denne rækkefølge:

1. Den Microsoft-administrerede Agent 365 CLI enterprise-applikation, applikations-ID f54280f4-395e-4ea8-9e48-bf2d4952aa14, når dens serviceprincipal er tilgængelig i din tenant.
2. En lejer-ejet applikation ved navn Agent 365 CLI.
3. Et applikations-ID, som du indtaster ved prompten, eller en ny lejer-ejet applikation, som en Global Administrator opretter ud fra prompten.

For brugerdefineret applikationskonfiguration, se Custom client app-registrering for Agent 365 CLI.

setup requirements

Valider og reparer forudsætninger for Agent 365-opsætning. Kører modulopbyggede kravtjek og giver vejledning til eventuelle problemer, den finder.

a365 setup requirements [options]

Denne kommando kører følgende trin:

• Kontrollerer alle nødvendige forudsætninger for konfigurationen af Agent 365.
• Rapporterer eventuelle problemer med detaljeret løsningsvejledning.
• Fortsætter med at kontrollere alle krav, selvom nogle kontroller mislykkes.
• Indeholder en oversigt over alle kontroller i slutningen.

requirements indstillinger

setup blueprint

Opret agent blueprint (Entra ID programregistrering).

Minimumkrav til tilladelser: Udviklerrollen Agent-id

a365 setup blueprint [options]

blueprint indstillinger

setup permissions

Konfigurer OAuth2-tilladelser og tilladelser, der kan nedarves.

Minimumkrav til tilladelser: Global administrator

a365 setup permissions [command] [options]

Indstillinger

Subcommands

setup permissions mcp

Konfigurer MCP-serveren OAuth2-tilladelser og tilladelser, der kan nedarves.

Minimumkrav til tilladelser: Global administrator

a365 setup permissions mcp [options]

This command:

• Læser ToolingManifest.json fra den , der deploymentProjectPath er angivet i a365.config.json.
• Tildeler OAuth2 delegerede tilladelsestilskud for hvert MCP-serverområde til agentens kursusplan.
• Konfigurerer tilladelser, der kan nedarves, så agentforekomster kan få adgang til MCP-værktøjer.
• Er idempotent og sikker at køre flere gange.

permissions mcp indstillinger

Overfør til MCP-tilladelser pr. server

Bruges --remove-legacy-scopes ved overførsel fra den ældre model for delte tilladelser til tilladelser pr. server:

• Ældre delt model: Et id for en enkelt ressourceapp (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) med delte områder, f.eks McpServers.Mail.All . og McpServers.Teams.All.
• Model pr. server: Hver MCP-server har sit eget app-id med området Tools.ListInvoke.All.

I følgende eksempel kan du se, hvordan tilladelser pr. server vises i Microsoft Entra-administrationscenter, når kursusplanen er anvendt. Hver MCP-server, f.eks. Work IQ Calendar MCP og Work IQ Mail MCP, har sit eget delegerede Tools.ListInvoke.All omfang. Et delt McpServersMetadata.Read.All område giver adgang til MCP-servermetadata.

setup permissions bot

Konfigurer Messaging Bot API OAuth2-tilladelser og tilladelser, der kan nedarves.

Minimumkrav til tilladelser: Global administrator

Forudsætninger: Tilladelserne Blueprint og MCP (kør a365 setup permissions mcp først)

a365 setup permissions bot [options]

permissions bot indstillinger

setup permissions custom

Anvender brugerdefinerede API-tilladelser på din agent-kursusplan, der går ud over de standardtilladelser, der kræves til agenthandlingen. Ved hjælp af denne kommando giver du din agent adgang til yderligere Microsoft Graph områder, f.eks. Tilstedeværelse, Filer og Chat, eller til brugerdefinerede API'er, der er registreret i organisationens Microsoft Entra ID lejer.

Minimumkrav til tilladelser: Global administrator

Forudsætninger: Kør a365 setup blueprint først.

a365 setup permissions custom [options]

This command:

• Konfigurerer OAuth2-delegerede tilladelser med administratorsamtykke for hver konfigureret ressource.
• Angiver tilladelser, der kan nedarves, så agentbrugere kan nedarve adgang fra kursusplanen.
• Afstemmer Microsoft Entra med den aktuelle konfiguration ved at tilføje nye tilladelser og fjerne de tilladelser, du har slettet fra konfigurationen.
• Er idempotent og sikker at køre flere gange.

permissions custom indstillinger

Konfigurer brugerdefinerede tilladelser inline

Brug --resource-app-id og --scopes til at anvende brugerdefinerede tilladelser direkte uden at redigere 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

Ressourcenavnet er automatisk løst fra Microsoft Entra. Du behøver ikke specificere det.

Konfigurer brugerdefinerede tilladelser via konfigurationsfil

Alternativt kan du tilføje customBlueprintPermissions til a365.config.json og køre kommandoen uden inline-flag:

a365 setup permissions custom

Denne kommando afstemmer Microsoft Entra med de konfigurerede tilladelser – den tilføjer nye tilladelser og fjerner eventuelle tilladelser, du har slettet fra konfigurationen.

Integration med setup all

Når din konfiguration indeholder brugerdefinerede tilladelser, konfigurerer kørsel a365 setup all automatisk dem som en del af en enkelt batchtilladelsesfase. Den fulde konfigurationsrækkefølge er:

1. Blueprint
2. Tilladelser batch (MCP, Bot API, Brugerdefineret blueprint tilladelser – alle konfigureret sammen)

setup permissions copilotstudio

Konfigurerer OAuth2-tilladelsestilladelser og tilladelser, der kan nedarves, for agentens kursusplan for at aktivere Copilot Studio copiloter via Power Platform-API'en.

Minimumkrav til tilladelser: Global administrator

Forudsætninger: Kør a365 setup blueprint først.

a365 setup permissions copilotstudio [options]

This command:

• Sikrer, at Power Platform API-tjenesteprincipalen findes i din lejer.
• Opretter et OAuth2-tilladelsestilskud fra kursusplanen til Power Platform-API'en med CopilotStudio.Copilots.Invoke området.
• Angiver tilladelser, der kan nedarves, så agentforekomster kan aktivere Copilot Studio medpiloter.

permissions copilotstudio indstillinger

Brug denne kommando, når din agent skal aktivere Copilot Studio medpiloter på kørselstidspunktet eller kalde Power Platform-API'er, der kræver CopilotStudio-tilladelser.

setup all

Udfør alle konfigurationstrin for at konfigurere dit Agent 365-miljø

a365 setup all [options]

Kører hele konfigurationen af Agent 365– alle trin i rækkefølge.

Omfatter: Kursusplan og tilladelser.

De trin, der fuldføres, afhænger af din rolle:

Når du kører a365 setup all uden global administrator, kan kommandolinjegrænsefladen:

1. Fuldfører alle de trin, den kan udføre (oprettelse af kursusplaner og tilladelser, der kan nedarves).
2. Genererer URL-adresser til administratorsamtykke pr. ressource og gemmer dem i a365.generated.config.json.
3. Viser næste trin i outputtet for en Global Administrator til at gennemføre OAuth2-tildelingerne, inklusive et direkte link eller samtykke-URL.

Minimumkrav til tilladelser:

• Udviklerrolle som agent-id (til oprettelse af kursusplan)
• Global Administrator (for OAuth2-tilladelser – hvis ikke tilgængelig, udskriver CLI'en de næste trin i outputtet)
• Application Administrator eller Global Administrator (for S2S (Server-to-Server) agentidentitet giver - --authmode s2s eller both; hvis ikke tilgængeligt, udskriver CLI'en en PowerShell-fallback i setup-oversigten)

setup all indstillinger

Agent setup

Som standard a365 setup all kører blueprint agent-flowet. Dette flow opretter en agent uden afhængighed af dataverse eller AI-teammedlemmer. Det fungerer for agenter, der kommunikerer direkte med Agent 365-platformen.

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

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

For at køre AI-holdkammerat-agentflowet i stedet, så overhal --aiteammate.

Dette flow udfører følgende trin i rækkefølge:

1. Kræk validering – kontrollerer Azure roller og forudsætninger.
2. Blueprint creation – opretter eller genbruger programmet Entra ID Agent Blueprint.
3. Batch-tilladelser – konfigurerer delegerede tilladelsestildelinger i kursusplanen for Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API, Power Platform og eventuelle brugerdefinerede ressourcer.
4. Agent Identity creation – opretter en agentidentitet i Entra ID via agentens identitets-Graph API.
5. Agentregistrering – registrerer agenten via AgentX V2 Agent Registration API.
6. Konfigurationssynkronisering – skriver indstillingerne for kørselsforbindelsen og konfigurationen af observabilitet til dine projektfiler (appsettings.json, .env).

Konfiguration uden konfiguration med --agent-name

Hvis du ikke har en a365.config.json fil, kan du bruge --agent-name til at køre installationsprogrammet uden en. CLI'en registrerer automatisk din lejer og leder først efter den Microsoft-administrerede Agent 365 CLI-enterprise-applikation.

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

Når du bruger --agent-name:

• TenantId registreres automatisk fra az account show. Send --tenant-id til tilsidesættelse.
• ClientAppId går som standard til den Microsoft-administrerede applikation, når dens serviceprincipal er til stede. Ellers leder CLI'en efter en lejer-ejet app kaldet Agent 365 CLI. Hvis ingen af appsene er tilgængelige, beder CLI'en om et brugerdefineret app-ID eller, for en Global Administrator, tilbyder at oprette en lejer-ejet app.
• Visningsnavne afledes som <name> Agent (identitet) og <name> Blueprint (blueprint).
• Infrastruktur springes altid over (ekstern hosting antages).
• Konfigurationssynkronisering (skrivning appsettings.json) springes over, da der ikke er konfigureret nogen projektsti.

Administratorsamtykke under konfiguration

For den Microsoft-administrerede applikation validerer CLI'en de delegerede scopes i erhvervede tokens og skaber ikke en AllPrincipals tilladelsesgave til CLI-applikationen.

Hvis en bruger-ejet brugerdefineret klient-app ikke har AllPrincipals administratorsamtykke til de nødvendige tilladelser, opdager CLI'en dette og beder dig om at give samtykke interaktivt:

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

Angiv y for at give samtykke online. Hvis du ikke er Global Administrator, så afslå — CLI'en udskriver de næste trin for en Global Administrator i opsætningsoversigten.

Messaging-endpoint (--m365)

Når du sender --m365, a365 setup all registrerer agentens beskedendepunkt, HTTPS-URL'en, hvor den deployerede agent modtager beskeder, hos Agent 365-platformen.

Endpunktet er en post-deploy artefakt: ved første opsætning er agenten som regel ikke deployet endnu, så dens URL eksisterer ikke. CLI håndterer dette:

• Leverer den direkte--messaging-endpoint <url> (for eksempel efter du har deployeret, eller når du bruger en Dev Tunnel til lokal testning).
• Interaktiv kørsel, ingen URL: CLI beder om det. Lad det stå tomt for at springe over.
• Ikke-interaktiv kørsel (CI eller scriptet), ingen URL: trinnet udsættes , og kørslen fuldføres stadig med succes — intet fejler.

Når endepunktet er udskudt, registreres det senere, når agenten er deployed:

a365 setup blueprint --endpoint-only `
  --messaging-endpoint https://your-app.azurewebsites.net/api/messages

For mere om beskedendepunktet, se Agent beskedendepunkt.

Agentidentitet giver (--authmode)

Som standard a365 setup all opretter principal-scoped delegerede tildelinger på agentens identitetstjenesteprincipal (obo mode). Disse bevillinger kræver ikke en administrativ rolle.

Brug --authmode til at kontrollere tilskudstypen:

# 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

Når den indloggede bruger mangler den nødvendige rolle for S2S-tildelinger, udskriver CLI'en en PowerShell-fallback-blok i opsætningsoversigten. En administrator kan køre det for at fuldføre opgaverne.

Sat indauthMode, a365.config.json så det gælder på alle runs uden flaget:

{
  "authMode": "s2s"
}

Config sync

Når kørslen er fuldført, skriver kommandolinjegrænsefladen automatisk kørselsindstillinger til dine projektfiler:

Kommandolinjegrænsefladen opretter filen, hvis den ikke findes, og opdaterer individuelle felter uden at overskrive resten af konfigurationen.

Prøv en mislykket registrering igen

Hvis konfigurationen fuldfører kursusplanen og tilladelserne, men mislykkes under agentregistrering, skal du bruge --agent-registration-only til kun at prøve dette trin igen uden at gentage tidligere arbejde:

a365 setup all --agent-registration-only