Agent 365 CLI `setup` command reference

Important

You need to be part of the Frontier preview program to get early access to Microsoft Agent 365. Frontier connects you directly with Microsoft’s latest AI innovations. Frontier previews are subject to the existing preview terms of your customer agreements. As these features are still in development, their availability and capabilities may change over time.

Set up your Agent 365 environment with granular control over each step. This command manages the initial setup workflow for Agent 365 blueprints.

Minimum role required: Azure Contributor + Agent ID Developer

Note

The role you hold determines how much of the setup completes in a single run. Global Administrator can complete all steps at once. Agent ID Administrator and Agent ID Developer can complete all steps except OAuth2 permission grants (admin consent), which require a separate step by a Global Administrator. To learn more about the handoff workflow, see setup admin.

Syntax

a365 setup [command] [options]

Options

Option	Description
`-?`, `-h`, `--help`	Show help and usage information.

Recommended execution order

# 0. Check prerequisites (optional)
a365 setup requirements

# 1. Create infrastructure (or skip if infrastructure exists)
a365 setup infrastructure

# 2. Create blueprint
a365 setup blueprint

# 3. Configure MCP permissions
a365 setup permissions mcp

# 4. Configure bot permissions
a365 setup permissions bot

# 5. Configure CopilotStudio permissions (if needed)
a365 setup permissions copilotstudio

# 6. Configure custom permissions (if needed)
a365 setup permissions custom

Or run all steps at once:

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

# Skip infrastructure if it already exists
a365 setup all --skip-infrastructure

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

If you're running as Agent ID Administrator or Agent ID Developer (not Global Administrator), a365 setup all completes all steps except OAuth2 permission grants. After it finishes, a Global Administrator must complete the grants:

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

Validate prerequisites for Agent 365 setup. Runs modular requirement checks and provides guidance for any problems it finds.

a365 setup requirements [options]

This command runs the following steps:

Checks all prerequisites needed for Agent 365 setup.
Reports any problems with detailed resolution guidance.
Continues checking all requirements even if some checks fail.
Provides a summary of all checks at the end.

`requirements` options

Option	Description
`-c`, `--config <config>`	Configuration file path. The default is `a365.config.json`.
`-v`, `--verbose`	Shows detailed output for all checks.
`--category <category>`	Runs checks for a specific category only, such as `Azure`, `Authentication`, or `Configuration`.
`-?`, `-h`, `--help`	Show help and usage information.

`setup infrastructure`

Create Azure infrastructure.

Minimum required permissions: Azure Subscription Contributor or Owner

a365 setup infrastructure [options]

`infrastructure` options

Option	Description
`-c`, `--config <config>`	Configuration file path. The default is `a365.config.json`.
`-v`, `--verbose`	Show detailed output.
`--dry-run`	Show what the command would do without executing it.
`-?`, `-h`, `--help`	Show help and usage information.

`setup blueprint`

Create agent blueprint (Entra ID application registration).

Minimum required permissions: Agent ID Developer role

a365 setup blueprint [options]

`blueprint` options

Option	Description
`-c`, `--config <config>`	Configuration file path. The default is `a365.config.json`.
`-v`, `--verbose`	Show detailed output.
`--dry-run`	Show what the command would do without executing it.
`--no-endpoint`	Don't register messaging endpoint (blueprint only).
`--endpoint-only`	Register messaging endpoint only. Requires existing blueprint.
`-?`, `-h`, `--help`	Show help and usage information.

`setup permissions`

Configure OAuth2 permission grants and inheritable permissions.

Minimum required permissions: Global Administrator

a365 setup permissions [command] [options]

Options

Option	Description
`-?`, `-h`, `--help`	Show help and usage information.

Subcommands

Subcommand	Description
`mcp`	Configure MCP server OAuth2 grants and inheritable permissions.
`bot`	Configure Messaging Bot API OAuth2 grants and inheritable permissions.
`custom`	Applies custom API permissions to your agent blueprint that go beyond the standard permissions required for agent operation.
`copilotstudio`	Configures OAuth2 permission grants and inheritable permissions for the agent blueprint to invoke Copilot Studio copilots via the Power Platform API.

`setup permissions mcp`

Configure MCP server OAuth2 grants and inheritable permissions.

Minimum required permissions: Global Administrator

a365 setup permissions mcp [options]

This command:

Reads ToolingManifest.json from the deploymentProjectPath specified in a365.config.json.
Grants OAuth2 delegated permission grants for each MCP server scope to the agent blueprint.
Configures inheritable permissions so agent instances can access MCP tools.
Is idempotent and safe to run multiple times.

Important

Before running this command, run a365 config display to verify that deploymentProjectPath points to the project folder containing the updated ToolingManifest.json. If the developer adds MCP servers on a different machine, share the updated ToolingManifest.json with the Global Administrator first. Running without the correct ToolingManifest.json doesn't add the new MCP server permissions to the blueprint.
Run this command after the developer runs a365 develop add-mcp-servers. Adding MCP servers to the manifest and granting permissions to the blueprint are two separate steps. After this command completes, the MCP server permissions are visible in the agent blueprint.

`permissions mcp` options

Option	Description
`-c`, `--config <config>`	Configuration file path. The default is `a365.config.json`.
`-v`, `--verbose`	Show detailed output.
`--dry-run`	Show what the command would do without executing it.
`-?`, `-h`, `--help`	Show help and usage information.

`setup permissions bot`

Configure Messaging Bot API OAuth2 grants and inheritable permissions.

Minimum required permissions: Global Administrator

Prerequisites: Blueprint and MCP permissions (run a365 setup permissions mcp first)

Next step: Deploy your agent (run a365 deploy if hosting on Azure)

a365 setup permissions bot [options]

`permissions bot` options

Option	Description
`-c`, `--config <config>`	Configuration file path. The default is `a365.config.json`.
`-v`, `--verbose`	Show detailed output.
`--dry-run`	Show what the command would do without executing it.
`-?`, `-h`, `--help`	Show help and usage information.

`setup permissions custom`

Applies custom API permissions to your agent blueprint that go beyond the standard permissions required for agent operation. By using this command, you grant your agent access to additional Microsoft Graph scopes, such as Presence, Files, and Chat, or to custom APIs registered in your organization's Microsoft Entra ID tenant.

Minimum required permissions: Global Administrator

Prerequisites: Run a365 setup blueprint first. Add custom permissions to a365.config.json by using a365 config permissions before running this command.

a365 setup permissions custom [options]

This command:

Configures OAuth2 delegated permission grants with admin consent for each configured resource.
Sets inheritable permissions so agent users can inherit access from the blueprint.
Reconciles Microsoft Entra with the current config by adding new permissions and removing any permissions that you deleted from the config.
Is idempotent and safe to run multiple times.

`permissions custom` options

Option	Description
`-c`, `--config <config>`	Configuration file path. The default is `a365.config.json`.
`-v`, `--verbose`	Show detailed output.
`--dry-run`	Show what the command would do without executing it.
`-?`, `-h`, `--help`	Show help and usage information.

Configure custom permissions

Use a365 config permissions to add custom permissions to your config before running this command:

# 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

During setup, the resource name is auto-resolved from Azure. You don't need to specify it in the config.

Remove custom permissions

To remove custom permissions from both the config and Microsoft Entra:

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

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

Integration with `setup all`

When your config includes custom permissions, running a365 setup all automatically configures them as part of a single batch permission phase. The full setup order is:

Infrastructure
Blueprint
Permissions batch (MCP, Bot API, Custom blueprint permissions — all configured together)

`setup permissions copilotstudio`

Configures OAuth2 permission grants and inheritable permissions for the agent blueprint to invoke Copilot Studio copilots via the Power Platform API.

Minimum required permissions: Global Administrator

Prerequisites: Run a365 setup blueprint first.

a365 setup permissions copilotstudio [options]

This command:

Ensures the Power Platform API service principal exists in your tenant.
Creates an OAuth2 permission grant from the blueprint to the Power Platform API with the CopilotStudio.Copilots.Invoke scope.
Sets inheritable permissions so agent instances can invoke Copilot Studio copilots.

`permissions copilotstudio` options

Option	Description
`-c`, `--config <config>`	Configuration file path. The default is `a365.config.json`.
`-v`, `--verbose`	Show detailed output.
`--dry-run`	Show what the command would do without executing it.
`-?`, `-h`, `--help`	Show help and usage information.

Use this command when your agent needs to invoke Copilot Studio copilots at runtime or call Power Platform APIs that require CopilotStudio permissions.

`setup all`

Perform all setup steps to set up your Agent 365 environment

a365 setup all [options]

Runs the complete Agent 365 setup, all steps in sequence.

Includes: Infrastructure, Blueprint, and Permissions.

The steps that complete depend on your role:

Step	Global Administrator	Agent ID Administrator	Agent ID Developer
Prerequisites check	Yes	Yes	Yes
Azure infrastructure	Yes	Yes	Yes
Agent blueprint creation	Yes	Yes	Yes
Inheritable permissions	Yes	Yes	Yes
OAuth2 permission grants (admin consent)	Yes	Requires GA step	Requires GA step

When you run a365 setup all without Global Administrator, the CLI:

Completes all steps it can (infrastructure, blueprint creation, and inheritable permissions).
Generates per-resource admin consent URLs and saves them to a365.generated.config.json.
Displays next steps showing how a Global Administrator can complete the OAuth2 grants using either a365 setup admin or the generated consent URLs.

Tip

If you're a Global Administrator, a365 setup all completes everything in a single run with no handoff needed.

Minimum required permissions:

Azure Subscription Contributor or Owner (for infrastructure)
Agent ID Developer role (for blueprint creation)
Global Administrator (for OAuth2 permission grants - if not available, use setup admin handoff)

`setup all` options

Option	Description
`-c`, `--config <config>`	Configuration file path. The default is `a365.config.json`. Ignored when `--agent-name` is provided.
`-v`, `--verbose`	Show detailed output.
`--dry-run`	Show what the command would do without executing it.
`--skip-infrastructure`	Skip Azure infrastructure creation (use if infrastructure already exists). This option still creates: Blueprint and Permissions.
`--skip-requirements`	Skip requirements validation check. Use with caution: setup might fail if prerequisites aren't met.
`--aiteammate <true\\|false>`	Set to `true` to run the AI teammate setup flow. Default is `false` (agent). Overrides the `aiTeammate` field in `a365.config.json`.
`--agent-instance-only`	Agent only. Skip blueprint and permissions and only register the agent instance. Use to retry a failed registration step.
`-n`, `--agent-name <name>`	Agent base name (for example, `"MyAgent"`). When provided, no config file is required. Derives display names as `"<name> Agent"` and `"<name> Blueprint"`. TenantId is auto-detected from `az account show` (override with `--tenant-id`). ClientAppId is resolved by looking up `Agent 365 CLI` in your tenant.
`--tenant-id <tenantId>`	Azure AD tenant ID. Overrides auto-detection from `az account show`. Use with `--agent-name` when running in a non-interactive environment or to target a specific tenant.
`-?`, `-h`, `--help`	Show help and usage information.

Agent setup

By default, a365 setup all runs the agent flow. This flow creates an agent without a Dataverse or AI teammate dependency. It works for agents that communicate directly with the Agent 365 platform without requiring an AI teammate license.

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

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

To run the AI teammate flow instead, pass --aiteammate true.

This flow performs the following steps in sequence:

Requirements validation — checks Azure roles and prerequisites.
Infrastructure creation — creates Azure resources (skip with --skip-infrastructure if they already exist; skipped automatically when --agent-name is used).
Blueprint creation — creates or reuses the Entra ID Agent Blueprint application.
Batch permissions — configures delegated permission grants on the blueprint for Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API, Power Platform, and any custom resources.
Agent Identity creation — creates an Agent Identity in Entra ID via the Agent Identity Graph API.
Agent registration — registers the agent via the AgentX V2 Agent Registration API.
Config sync — writes the runtime connection settings and observability configuration to your project files (appsettings.json, .env).

Note

The agent setup requires six additional beta API permissions on your custom client app: AgentIdentityBlueprint.AddRemoveCreds.All, AgentIdentityBlueprint.DeleteRestore.All, AgentInstance.ReadWrite.All, AgentIdentity.ReadWrite.All, AgentIdentity.Create.All, and AgentIdentity.DeleteRestore.All. See Custom client app registration for the complete list.

Config-free setup with `--agent-name`

If you don't have an a365.config.json file, use --agent-name to run setup without one. The CLI auto-detects your tenant and resolves the client app by looking up the well-known Agent 365 CLI app registration in your 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"

When using --agent-name:

TenantId is auto-detected from az account show. Pass --tenant-id to override.
ClientAppId is resolved by looking for an Entra app named Agent 365 CLI in your tenant. If not found, the CLI exits with an error. See Custom client app registration for how to register this app.
Display names are derived as "<name> Agent" (identity) and "<name> Blueprint" (blueprint).
Infrastructure is always skipped (external hosting assumed).
Config sync (writing appsettings.json) is skipped since there's no project path configured.

If your client app doesn't have AllPrincipals admin consent for the required permissions, the CLI detects this and prompts you to grant consent interactively:

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

Enter y to grant consent in-line. If you're not a Global Administrator, decline and use the setup admin handoff workflow instead.

Config sync

After a successful run, the CLI automatically writes runtime settings to your project files:

Setting	Written to	Description
`Connections.ServiceConnection`	`appsettings.json` / `.env`	Blueprint client ID, client secret, tenant ID, and token endpoint
`Agent365Observability`	`appsettings.json` / `.env`	Agent ID (Agent Identity), blueprint ID, tenant ID, client ID, and client secret for telemetry export
`TokenValidation`	`appsettings.json`	Token validation settings (disabled by default for non-DW)
`ConnectionsMap`	`appsettings.json` / `.env`	Default service URL to connection mapping

The CLI creates the file if it doesn't exist and updates individual fields without overwriting the rest of your configuration.

Retry a failed registration

If the setup completes blueprint and permissions successfully but fails during agent registration, use --agent-instance-only to retry only that step without repeating earlier work:

a365 setup all --agent-instance-only

`setup admin`

Completes the OAuth2 permission grants (admin consent) that require Global Administrator. Run this command after an Agent ID Administrator or Agent ID Developer runs a365 setup all.

Minimum required permissions: Global Administrator

a365 setup admin [options]

When to use `setup admin`

Use this command when:

After an Agent ID Administrator or Agent ID Developer runs a365 setup all.
The setup summary shows that OAuth2 grants are pending and instructs the Global Administrator to run this command.
You want to re-run consent grants after changing permissions in the config.

Typical handoff workflow

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

This command:

Loads the agent config from the specified directory or the current directory by default.
Reads the agent blueprint ID and configured resource permissions from the generated config.
Creates AllPrincipals OAuth2 permission grants for all configured resources, including:
- Microsoft Graph (delegated scopes)
- Agent 365 Tools (MCP server scopes)
- Messaging Bot API
- Observability API
- Power Platform API
- Any custom permissions defined in your config
Displays a confirmation prompt before making changes. Use --yes to bypass the prompt.

Warning

OAuth2 grants created by this command are tenant-wide (consentType=AllPrincipals). This configuration means all users in the tenant can use the agent's delegated permissions. Review the listed scopes carefully before confirming.

`setup admin` options

Option	Description
`-d`, `--config-dir <dir>`	Directory containing `a365.config.json` and `a365.generated.config.json`. Defaults to current directory.
`-v`, `--verbose`	Show detailed output.
`--dry-run`	Show what the command would do without executing it.
`--skip-requirements`	Skip requirements validation check. Use with caution.
`-y`, `--yes`	Skip confirmation prompt and proceed automatically.
`-?`, `-h`, `--help`	Show help and usage information.

Instead of running a365 setup admin, the Global Administrator can open the combined consent URL that a365 setup all saves to a365.generated.config.json. This URL covers all required resources in a single browser visit.

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

Feedback

Was this page helpful?

Last updated on 2026-04-21

Share via

Agent 365 CLI setup command reference

Syntax

Options

Recommended execution order

setup requirements

requirements options

setup infrastructure

infrastructure options

setup blueprint

blueprint options

setup permissions

Options

Subcommands

setup permissions mcp

permissions mcp options

setup permissions bot

permissions bot options

setup permissions custom

permissions custom options

Configure custom permissions

Remove custom permissions

Integration with setup all

setup permissions copilotstudio

permissions copilotstudio options

setup all

setup all options

Agent setup

Config-free setup with --agent-name

Admin consent during setup

Config sync

Retry a failed registration

setup admin

When to use setup admin

Typical handoff workflow

setup admin options

Alternative: consent URL

Feedback

Additional resources

Agent 365 CLI `setup` command reference

`setup requirements`

`requirements` options

`setup infrastructure`

`infrastructure` options

`setup blueprint`

`blueprint` options

`setup permissions`

`setup permissions mcp`

`permissions mcp` options

`setup permissions bot`

`permissions bot` options

`setup permissions custom`

`permissions custom` options

Integration with `setup all`

`setup permissions copilotstudio`

`permissions copilotstudio` options

`setup all`

`setup all` options

Config-free setup with `--agent-name`

`setup admin`

When to use `setup admin`

`setup admin` options