Agent 365 CLI setup command reference

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

Syntax

a365 setup [command] [options]

Options

Recommended execution order

# 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

Or run all steps at once:

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

# 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. When it finishes, the output includes the next steps for a Global Administrator to complete the grants — including a direct link or consent URL they can open.

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

setup blueprint

Create agent blueprint (Entra ID application registration).

Minimum required permissions: Agent ID Developer role

a365 setup blueprint [options]

blueprint options

setup permissions

Configure OAuth2 permission grants and inheritable permissions.

Minimum required permissions: Global Administrator

a365 setup permissions [command] [options]

Options

Subcommands

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.

permissions mcp options

Migrate to per-server MCP permissions

Use --remove-legacy-scopes when migrating from the legacy shared permissions model to per-server permissions:

• Legacy shared model: A single resource app ID (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) with shared scopes such as McpServers.Mail.All and McpServers.Teams.All.
• Per-server model: Each MCP server has its own app ID with the scope Tools.ListInvoke.All.

The following example shows how per-server permissions appear in the Microsoft Entra admin center after the blueprint is applied. Each MCP server, such as Work IQ Calendar MCP and Work IQ Mail MCP, has its own delegated Tools.ListInvoke.All scope. A shared McpServersMetadata.Read.All scope provides access to MCP server metadata.

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)

a365 setup permissions bot [options]

permissions bot options

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.

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

Configure custom permissions inline

Use --resource-app-id and --scopes to apply custom permissions directly without editing 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

The resource name is auto-resolved from Microsoft Entra. You don't need to specify it.

Configure custom permissions via config file

Alternatively, add customBlueprintPermissions to a365.config.json and run the command without inline flags:

a365 setup permissions custom

This command reconciles Microsoft Entra with the configured permissions - it adds new permissions and removes any permissions that you deleted from the config.

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:

1. Blueprint
2. 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

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: Blueprint and Permissions.

The steps that complete depend on your role:

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

1. Completes all steps it can (blueprint creation and inheritable permissions).
2. Generates per-resource admin consent URLs and saves them to a365.generated.config.json.
3. Displays next steps in the output for a Global Administrator to complete the OAuth2 grants, including a direct link or consent URL.

Minimum required permissions:

• Agent ID Developer role (for blueprint creation)
• Global Administrator (for OAuth2 permission grants - if not available, the CLI prints the next steps in the output)
• Agent ID Administrator, Application Administrator, or Global Administrator (for S2S (Server-to-Server) agent identity grants - --authmode s2s or both; if not available, the CLI prints a PowerShell fallback in the setup summary)

setup all options

Agent setup

By default, a365 setup all runs the blueprint 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.

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

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

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

This flow performs the following steps in sequence:

1. Requirements validation — checks Azure roles and prerequisites.
2. Blueprint creation — creates or reuses the Entra ID Agent Blueprint application.
3. 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.
4. Agent Identity creation — creates an Agent Identity in Entra ID via the Agent Identity Graph API.
5. Agent registration — registers the agent via the AgentX V2 Agent Registration API.
6. Config sync — writes the runtime connection settings and observability configuration to your project files (appsettings.json, .env).

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.

Admin consent during setup

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 — the CLI prints the next steps for a Global Administrator in the setup summary.

Agent identity grants (--authmode)

By default, a365 setup all creates principal-scoped delegated grants on the agent identity service principal (obo mode). These grants don't require an admin role.

Use --authmode to control the grant type:

# 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

When the signed-in user lacks the required role for S2S grants, the CLI prints a PowerShell fallback block in the setup summary. An administrator can run it to complete the assignments.

Set authMode in a365.config.json so it applies on every run without the flag:

{
  "authMode": "s2s"
}

Config sync

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

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-registration-only to retry only that step without repeating earlier work:

a365 setup all --agent-registration-only