Kommandoreferens för Agent 365 CLI setup

Konfigurera agent 365-miljön med detaljerad kontroll över varje steg. Använd kommandot Agent 365 CLI setup för att skapa ritningar, konfigurera behörigheter och slutföra det initiala arbetsflödet för Agent 365-installation. För steg-för-steg-installationsdetaljer, följ artikeln om installationsagentens ritning .

Minimum-rollen krävs: Azure Deltagare + Agent ID Developer

Syntax

a365 setup [command] [options]

Options

Rekommenderad körningsordning

# 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 alla steg samtidigt:

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

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

Om du kör som agent-ID-administratör eller agent-ID-utvecklare (inte global administratör) a365 setup all slutför du alla steg utom OAuth2-behörighetsbidrag. När det är klart innehåller utdata nästa steg för en Global Administrator att slutföra bidragen – inklusive en direktlänk eller samtyckes-URL som de kan öppna.

Val av klientapplikation

När a365.config.json specificerar en clientAppId, fortsätter installationen att använda den applikationen. För konfigurationsfri installation använder CLI denna ordning:

1. Den Microsoft-hanterade Agent 365 CLI-företagsapplikationen, applikations-ID f54280f4-395e-4ea8-9e48-bf2d4952aa14, när dess tjänsteprincip är tillgänglig i din tenant.
2. En hyresgästägd applikation vid namn Agent 365 CLI.
3. Ett applikations-ID som du anger i prompten, eller en ny tenant-owned applikation som en Global Administrator skapar från prompten.

För anpassad applikationskonfiguration, se Custom client app registration for Agent 365 CLI.

setup requirements

Validera och reparera förutsättningar för Agent 365-installation. Kör modulära kravkontroller och ger vägledning för eventuella problem som hittas. Använd setup requirements den för att kontrollera alla förutsättningar som behövs för Agent 365-installation och rapportera eventuella problem med detaljerad lösningsvägledning. Den fortsätter att kontrollera alla krav även om vissa kontroller misslyckas och ger sedan en sammanfattning av alla kontroller i slutet.

a365 setup requirements [options]

För den Microsoft-hanterade applikationen setup requirements verifieras att tjänsteprincipen är närvarande och att förvärvade tokens innehåller de nödvändiga delegerade scopes. Den ändrar inte Microsoft applikationsregistrering eller skapar ett tenant-local tillstånd för CLI-applikationen.

Om varken den Microsoft-hanterade applikationen eller en hyresgästägd app vid namn Agent 365 är tillgänglig, setup requirements ber CLI dig om ett anpassat klientapp-ID. En global administratör kan ange C i prompten för att skapa och konfigurera en hyresgästägd app.

När en hyresgästägd anpassad app väljs, setup requirements upptäcker och reparerar även en saknad wids valfri skadeanmälan. Utan detta anspråk kan rolldetektion tyst misslyckas och tillstånd för blåtryckstillstånd kan hoppas över under setup all. Om kontrollen misslyckas innehåller utdata en portallänk och ett az rest kommando för att lägga till kravet, och instruerar dig att logga ut och in igen så att nästa token bär det.

requirements Alternativ

Följande exempel visar hur man kör autentiseringskontroller:

a365 setup requirements --category authentication

setup blueprint

Skapa agentritning (Entra ID programregistrering). Använd setup blueprint för att skapa en agent identity blueprint som definierar agentens identitet, behörigheter och infrastrukturkrav. Det lägger grunden för att placera ut och driva dina agenter. Att skapa ritningen är det första steget i installationen och efterföljande installationssteg beror på denna konfiguration.

Minsta behörigheter som krävs: Rollen Agent-ID-utvecklare

a365 setup blueprint [options]

blueprint Alternativ

Följande exempel visar hur man skapar en agent identity blueprint som heter my-blueprint.

 a365 setup blueprint --agent-name my-blueprint

När installationen är klar skapar den en a365.generated.config.json fil som innehåller all konfigurationsdata.

setup permissions

Konfigurera OAuth2-behörighetsbidrag och ärvbara behörigheter. Använd setup permissions för att ge OAuth 2.0-behörighet och ärftliga behörigheter till en agent-blueprint. Varje agentinstans du skapar från blueprinten ärver automatiskt dessa behörigheter, så den kan komma åt MCP-verktyg och resurser. Till exempel inkluderar behörigheterna åtkomst att läsa metadata för alla MCP-servrar, meddelande-Bot API, Copilot Studio och alla konfigurerade Microsoft Graph- eller anpassade API-scopes.

Minsta behörigheter som krävs: Global administratör

a365 setup permissions [command] [options]

Options

Subcommands

setup permissions mcp

Konfigurera MCP-server OAuth2-beviljanden och ärvbara behörigheter.

Minsta behörigheter som krävs: Global administratör

a365 setup permissions mcp [options]

This command:

• Läser ToolingManifest.json från angivet deploymentProjectPath i a365.config.json.
• Ger OAuth2 delegerade behörighetsbidrag för varje MCP-serveromfång till agentritningen.
• Konfigurerar ärvbara behörigheter så att agentinstanser kan komma åt MCP-verktyg.
• Är idempotent och säkert att köra flera gånger.

permissions mcp Alternativ

Migrera till MCP-behörigheter per server

Använd --remove-legacy-scopes när du migrerar från den äldre modellen med delade behörigheter till behörigheter per server:

• Äldre delad modell: Ett enda resursapp-ID (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) med delade omfång som McpServers.Mail.All och McpServers.Teams.All.
• Modell per server: Varje MCP-server har ett eget app-ID med omfånget Tools.ListInvoke.All.

I följande exempel visas hur behörigheter per server visas i Microsoft Entra administrationscenter när skissen har tillämpats. Varje MCP-server, till exempel Work IQ Calendar MCP och Work IQ Mail MCP, har sitt eget delegerade Tools.ListInvoke.All omfång. Ett delat McpServersMetadata.Read.All omfång ger åtkomst till MCP-servermetadata.

setup permissions bot

Konfigurera api för meddelanderobot OAuth2-beviljanden och ärvbara behörigheter.

Minsta behörigheter som krävs: Global administratör

Förutsättningar: Skiss- och MCP-behörigheter (kör a365 setup permissions mcp först)

a365 setup permissions bot [options]

permissions bot Alternativ

setup permissions custom

Tillämpar anpassade API-behörigheter på din agentritning som går utöver de standardbehörigheter som krävs för agentåtgärd. Med det här kommandot ger du din agent åtkomst till ytterligare Microsoft Graph omfång, till exempel Närvaro, Filer och Chatt, eller till anpassade API:er som är registrerade i organisationens Microsoft Entra ID klientorganisation.

Minsta behörigheter som krävs: Global administratör

Förutsättningar: Kör a365 setup blueprint först.

a365 setup permissions custom [options]

This command:

• Konfigurerar OAuth2-delegerade behörighetsbidrag med administratörsmedgivande för varje konfigurerad resurs.
• Anger ärvbara behörigheter så att agentanvändare kan ärva åtkomst från skissen.
• Stäm av Microsoft Entra med den aktuella konfigurationen genom att lägga till nya behörigheter och ta bort eventuella behörigheter som du har tagit bort från konfigurationen.
• Är idempotent och säkert att köra flera gånger.

permissions custom Alternativ

Konfigurera anpassade behörigheter inline

Använd --resource-app-id och --scopes för att tillämpa anpassade behörigheter direkt utan att redigera 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

Resursnamnet löses automatiskt från Microsoft Entra. Du behöver inte specificera det.

Konfigurera anpassade behörigheter via konfigurationsfil

Alternativt, lägg till customBlueprintPermissionsa365.config.json och kör kommandot utan inline-flaggor:

a365 setup permissions custom

Detta kommando stämmer av Microsoft Entra med de konfigurerade behörigheterna – det lägger till nya behörigheter och tar bort alla behörigheter du tagit bort från konfigurationen.

Integration med setup all

När konfigurationen innehåller anpassade behörigheter konfigurerar körning a365 setup all automatiskt dem som en del av en enda batchbehörighetsfas. Den fullständiga installationsordningen är:

1. Blueprint
2. Behörighetsbatch (MCP, Bot API, Anpassade skissbehörigheter – alla konfigurerade tillsammans)

setup permissions copilotstudio

Konfigurerar OAuth2-behörighetsbidrag och ärvbara behörigheter för agentritningen för att anropa Copilot Studio andrepiloter via Power Platform-API:et. Använd setup permissions copilotstudio när din agent behöver anropa Copilot Studio copilots under körning eller anropa Power Platform API:er som kräver CopilotStudio-behörigheter.

Minsta behörigheter som krävs: Global administratör

Förutsättningar: Kör a365 setup blueprint först.

a365 setup permissions copilotstudio [options]

This command:

• Säkerställer att tjänstens huvudnamn för Power Platform-API:et finns i din klientorganisation.
• Skapar ett OAuth2-behörighetsbeviljande från skissen till Power Platform-API:et med omfånget CopilotStudio.Copilots.Invoke .
• Anger ärvbara behörigheter så att agentinstanser kan anropa Copilot Studio andrepiloter.

permissions copilotstudio Alternativ

setup all

Utför alla installationssteg för att konfigurera agent 365-miljön

a365 setup all [options]

Kör den fullständiga agent 365-installationen, alla steg i följd.

Innehåller: Skiss och behörigheter.

Vilka steg som slutförs beror på din roll:

När du kör a365 setup all utan global administratör kan CLI:

1. Slutför alla steg som kan utföras (skissskapande och ärvbara behörigheter).
2. Genererar URL:er för administratörsmedgivande per resurs och sparar dem till a365.generated.config.json.
3. Visar nästa steg i utdata för en global administratör för att slutföra OAuth2-bidragen, inklusive en direktlänk eller samtyckes-URL.

Nödvändiga minimibehörigheter:

• Utvecklarroll för agent-ID (för att skapa skisser)
• Global Administrator (för OAuth2-behörighetsbeviljande – om det inte finns tillgängligt skriver CLI:n ut nästa steg i utdatat)
• Application Administrator eller Global Administrator (för S2S (Server-to-Server) agentidentitet beviljas – --authmode s2s eller both; om det inte finns tillgängligt, skriver CLI:n ut en PowerShell-reservplan i setup-sammanfattningen)

setup all Alternativ

Agent setup

Som standard körs a365 setup all blueprint agent-flödet. Det här flödet skapar en agent utan ett dataversum- eller AI-teamkamratberoende. Det fungerar för agenter som kommunicerar direkt med Agent 365-plattformen.

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

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

För att köra AI-lagkamratens agentflöde istället, passa --aiteammate.

Det här flödet utför följande steg i följd:

1. Requirements-validering – kontrollerar Azure roller och förutsättningar.
2. Blueprint creation – skapar eller återanvänder Entra ID Agent Blueprint-programmet.
3. Batchbehörigheter — konfigurerar delegerade behörighetsbeviljanden på ritningen för Microsoft Graph, Agent 365 Tools, Messaging Bot API, Power Platform och eventuella anpassade resurser. För blueprint-agenter begär den inte Observability API:et. För detaljer, se Observabilitetsbehörigheter.
4. Agent Identity creation – skapar en agentidentitet i Entra ID via agentidentiteten Graph API.
5. Agentregistrering – registrerar agenten via AgentX V2-agentregistrerings-API:et. För blueprint-agenter godkänner registreringen telemetriexport, så installationen misslyckas om registreringen misslyckas.
6. Konfigurationssynkronisering – skriver inställningar för körningsanslutning och observabilitetskonfiguration till dina projektfiler (appsettings.json, .env).

Konfigurationsfri installation med --agent-name

Om du inte har en a365.config.json fil kan du använda --agent-name för att köra installationsprogrammet utan en. CLI:n upptäcker automatiskt din hyresgäst och letar först efter den Microsoft-hanterade Agent 365 CLI-företagsapplikationen.

# 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 använder --agent-name:

• TenantId identifieras automatiskt från az account show. Skicka --tenant-id till åsidosättning.
• ClientAppId går tillbaka till den Microsoft-hanterade applikationen när dess tjänsteprincip är närvarande. Annars letar CLI:n efter en hyresgästägd app som heter Agent 365 CLI. Om ingen av apparna är tillgänglig, ber CLI om ett anpassat app-ID eller, för en Global Administrator, erbjuder det att skapa en hyresgästägd app.
• Visningsnamn härleds som <name> Agent (identitet) och <name> Blueprint (skiss).
• Infrastrukturen hoppas alltid över (extern värd förutsätts).
• Konfigurationssynkronisering (skriver appsettings.json) hoppas över eftersom det inte finns någon konfigurerad projektsökväg.

Administratörsmedgivande under installationen

För den Microsoft-hanterade applikationen validerar CLI:n de delegerade scopes i förvärvade tokens och skapar AllPrincipals inget tillståndsbeviljande för CLI-applikationen.

För blueprint-agenter a365 setup all ingår inte Observability API (Agent365.Observability.OtelWrite) i administratörssamtyckes-URL:er. För detaljer, se Observabilitetsbehörigheter.

Om en hyresgästägd klientapp inte har AllPrincipals administratörssamtycke för de nödvändiga behörigheterna, upptäcker CLI:n detta och uppmanar dig att ge samtycke interaktivt:

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

Ange y för att bevilja medgivande på rad. Om du inte är Global Administrator, tacka nej — CLI skriver ut nästa steg för en Global Administrator i setup-sammanfattningen.

Meddelandeändpunkt (--m365)

När du skickar --m365, a365 setup all registrerar agentens meddelandeendpoint, HTTPS-URL:en där den distribuerade agenten tar emot meddelanden, med Agent 365-plattformen.

Endpointen är en post-deploy-artefakt: vid första installationen är agenten vanligtvis inte distribuerad än, så dess URL finns inte. CLI hanterar detta:

• Förse den direkt ( --messaging-endpoint <url> till exempel efter att du har distribuerat, eller när du använder en utvecklingstunnel för lokal testning).
• Interaktiv körning, ingen URL: CLI efterfrågar det. Lämna den tom för hopp.
• Icke-interaktiv körning (CI eller skriptad), ingen URL: steget skjuts upp och körningen slutförs ändå framgångsrikt — inget misslyckas.

När slutpunkten är uppskjuten, registrera den senare när agenten är distribuerad:

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

För mer om meddelandeändpunkten, se Agent messaging endpoint.

Agentidentitet ger (--authmode)

Som standard a365 setup all skapar principal-scoped delegerade grants på agentidentitetstjänstens principal (obo mode). Dessa bidrag kräver ingen administrativ roll.

Användning --authmode för att kontrollera bidragstypen:

# 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 inloggade användaren saknar den roll som krävs för S2S-beviljaningar, skriver CLI:n ut en PowerShell-reservblock i setup-sammanfattningen. En administratör kan köra den för att slutföra uppgifterna.

Inställt authMode så a365.config.json att det gäller vid varje genomspelning utan flaggan:

{
  "authMode": "s2s"
}

Observability permissions

För blueprint-agenter a365 setup all begär den inte Observability API (Agent365.Observability.OtelWrite) i något autentiseringsläge. Den lägger inte till API:et i ärftliga behörigheter, agentidentitetsbeviljanden, approllsbeviljanden eller administratörssamtyckes-URL:er. Agent 365-registrering ger en registrerad agentinstans rätt att exportera telemetri på S2S-rutten utan den behörigheten, så setup exit-utgår med kod 1 om registreringen misslyckas eller en befintlig registrering inte kan verifieras. För att försöka igen, se Försök om en misslyckad registrering.

AI-lagkamrater konfigurerar och a365 setup permissions bot konfigurerar Observability API:et. Att köra om setupen upphäver inte Observability som tidigare CLI-versioner lagt till.

Agenter som exporterar på den delegerade rutten, såsom agenter som använder Microsoft OpenTelemetriy-distributionens standard eller Agent 365 SDK 1.x utan S2S aktiverat, behöver delegerad Agent365.Observability.OtelWrite behörighet och administratörstillstånd. En global administratör kan lägga till behörigheten i ritningen och ge administratörssamtycke genom att köra:

a365 setup permissions custom `
  --resource-app-id 9b975845-388f-4429-889e-eab1ef63949c `
  --scopes Agent365.Observability.OtelWrite

För att använda Microsoft Entra administrationscenter istället, se Bevilja behörigheten.

Config sync

Efter en lyckad körning skriver CLI automatiskt körningsinställningar till dina projektfiler:

CLI skapar filen om den inte finns och uppdaterar enskilda fält utan att skriva över resten av konfigurationen.

Försök igen med en misslyckad registrering

Om installationen slutför skissen och behörigheterna men misslyckas under agentregistreringen kan du bara --agent-registration-only försöka utföra det steget igen utan att upprepa tidigare arbete:

a365 setup all --agent-registration-only