Setup agent blueprint

The agent blueprint defines your agent's identity, permissions, and infrastructure requirements. Create every agent instance from this agent blueprint.

Note

Setting up an agent blueprint is required to enable Register, Work IQ, and AI teammate capabilities. See Get started with Agent 365 development to understand which capabilities apply to your agent.

For more information about Agent 365 Identity, see Agent 365 Identity.

Prerequisites

Before you begin, ensure you have the following prerequisites:

  1. Agent 365 CLI - See Agent 365 CLI installation.

  2. Required permissions:

    • Valid tenant user with one of the following roles:
      • Global Administrator
      • Agent ID Developer
    • Access to an Azure subscription with permissions to create resources

    Tip

    Agents (not AI teammates) don't need a config file. Use a365 setup all --agent-name <name> and the CLI resolves your tenant and client app automatically. AI teammate setup requires a manually created a365.config.json.

Create agent blueprint

Use the a365 setup command to create Azure resources and register your agent blueprint. The blueprint defines your agent's identity, permissions, and infrastructure requirements. This step establishes the foundation for deploying and running your agent in Azure.

Run setup

Run the setup command:

a365 setup -h

The command has various options. You can complete the entire setup in a single command by using a365 setup all or choose more granular options.

Note

a365 setup all defaults to blueprint agent mode. To set up an AI teammate agent instead, pass --aiteammate. For M365 agents (Teams, Copilot), also pass --m365 to register the messaging endpoint automatically.

Agent setup (default):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

M365 agent setup (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

AI teammate setup:

a365 setup all --aiteammate

The entire setup process performs these operations:

  1. Creates Azure infrastructure (if it doesn't already exist):

    • Resource group
    • App Service Plan with specified SKU
    • Azure Web App with managed identity enabled

  2. Registers agent blueprint:

    • Creates the agent blueprint in your Microsoft Entra tenant
    • Creates Microsoft Entra application registrations
    • Configures the agent identity with required permissions
    • Sets managerApplications on the blueprint, which is required for platform manageability

    Important

    Blueprints must have managerApplications set to be accepted by the platform. The CLI sets this automatically. If you have an existing blueprint created before this requirement was introduced, delete it and run a365 setup all again, or manually patch it via the Graph API.

  3. Configures API permissions:

    • Sets up Microsoft Graph API scopes
    • Configures Messaging Bot API permissions
    • Applies inheritable permissions for agent instances

  4. Updates configuration files:

    • Saves generated IDs and endpoints to a new file in your working directory called a365.generated.config.json
    • Records managed identity and resource information

Note

Setup typically takes 3-5 minutes and auto-saves configuration to a365.generated.config.json. If you run as Global Administrator, the CLI might open a browser window for admin consent - complete the consent flow to proceed. If you run as Agent ID Developer, no browser window appears; the CLI generates consent URLs for a Global Administrator to complete later.

Setup by using Agent ID Developer

If you run as Agent ID Developer (not Global Administrator), a365 setup all completes most steps automatically, but OAuth2 permission grants require a separate Global Administrator step.

What steps complete automatically:

  • Azure infrastructure (resource group, App Service Plan, Web App)
  • Agent blueprint registration
  • Inheritable permissions for agent instances

What steps require a Global Administrator:

  • OAuth2 delegated permission grants (AllPrincipals consent) for Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API, and Power Platform API

How to complete setup by using a non-admin account:

Step Who Action
1 Developer Run a365 setup all. The CLI completes all steps it can and prints instructions showing what a Global Administrator must finish.
2 Developer Share the config folder with your Global Administrator. The folder contains a365.config.json and a365.generated.config.json.
3 Global Administrator Run a365 setup admin --config-dir "<path-to-config-folder>" to complete the OAuth2 permission grants.

Running the commands:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

Share the next steps printed by the CLI with your Global Administrator. They can open the provided link or consent URL to complete the OAuth2 grants.

Verify setup

When the setup finishes, you see a summary that shows all the completed steps. Verify the created resources:

  1. Verify generated configuration:

    Open a365.generated.config.json in your working directory. Or use PowerShell:

    Get-Content a365.generated.config.json | ConvertFrom-Json

    Expected output includes these critical values:

    {
"managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"agentBlueprintClientSecretProtected": true,
"botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"resourceConsents": [],
"completed": true,
"completedAt": "xxxx-xx-xxTxx:xx:xxZ",
"cliVersion": "x.x.xx"
}

    Key fields to verify:

    Field Purpose What to Check
    managedIdentityPrincipalId Azure managed identity authentication Should be a valid GUID
    agentBlueprintId Your agent's unique identifier Used in Developer Portal and admin center
    agentBlueprintObjectId Blueprint's Microsoft Entra ID
    messagingEndpoint Message routing Where Teams/Outlook send messages to your agent
    agentBlueprintClientSecret Authentication secret Should exist (value is masked)
    resourceConsents API permissions Should contain resources like Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API
    completed Setup status Should be true

    Note

    If you ran setup as Agent ID Administrator or Agent ID Developer, resourceConsents might be empty and completed might be false until a Global Administrator completes the OAuth2 permission grants using the next steps printed by the CLI.

  2. Verify Azure resources in Azure Portal:

    Or use the az resource list PowerShell command.

    # List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table

    Verify the following resources are created:

    • Resource Group:

      • Go to Resource Groups > Select your resource group
      • Verify it contains your App Service Plan and Web App

    • App Service Plan:

      • Go to App Services > App Service Plans
      • Find your plan and verify the pricing tier matches your configuration SKU

    • Web App:

      • Go to App Services > Web Apps
      • Find your web app, then go to Settings > Identity > System assigned
      • Verify status is On
      • Note the Object (principal) ID matches managedIdentityPrincipalId

  3. Verify Microsoft Entra applications in Azure Portal:

    Go to Azure Active Directory > App registrations > All applications:

    • Search for your agent blueprint by the agentBlueprintId

    • Open the application and select API permissions

    • Verify permissions are granted with green checkmarks:

      • Microsoft Graph (delegated and application permissions)
      • Messaging Bot API permissions

    • All permissions show "Granted for [Your Tenant]"

  4. Verify generated configuration file created:

    You should have a file named a365.generated.config.json that contains all the configuration data.

    Use the Test-Path PowerShell command to check that it exists.

    # Check file exists
Test-Path a365.generated.config.json
# Should return: True

    Important

    Save both a365.config.json and a365.generated.config.json files. You need these values for deployment and troubleshooting.

  5. Verify Web App has managed identity enabled:

    Use the az webapp identity show command to check whether managed identity is enabled.

    az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

    Expected:

    {
"principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "SystemAssigned"
}

  6. Verify Agent blueprint registered in Microsoft Entra:

    In Microsoft Entra admin center, search for your agentBlueprintId or search by name.

    Verify that:

    ✅ App Registration and Enterprise Application appear
    ✅ On the app registration blueprint, API permissions tab shows all permissions
    ✅ Status shows "Granted for [Your Tenant]"

For more help, see:

Agent permissions

Before apps and agents can read or write Microsoft 365 data (users, mail, files, Teams, agents, and so on), you must explicitly grant them Microsoft Graph permissions. Microsoft Graph permissions are the authorization model that controls what data and actions an app or service can access through Microsoft Graph APIs across Microsoft 365 and Microsoft Entra ID.

Learn more: Overview of Microsoft Graph permissions

To use Graph permissions for Agent 365 agent instances, the developer must declare them in the agent blueprint. When an administrator activates the blueprint in Microsoft 365 Admin Center, the portal reviews the blueprint's Graph permissions and prompts the administrator to consent to them.

To understand and validate how Graph permissions enable your agent, you can:

Apply permissions to your blueprint

Use a365 setup permissions custom to apply custom API permissions inline to your blueprint in Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

For full details on configuring and removing custom permissions, see setup permissions custom.

Next steps

Deploy your agent code to the cloud:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Publish agent to Microsoft admin center

Troubleshooting

This section describes common problems when setting up agent blueprints.

Tip

Agent 365 Troubleshooting Guide contains high-level troubleshooting recommendations, best practices, and links to troubleshooting content for each part of the Agent 365 development lifecycle.

These problems sometimes occur during registration:

Insufficient permissions error

Symptom: Insufficient permissions error during a365 setup command execution.

You need one of the following roles in your Microsoft Entra tenant:

  • Global Administrator
  • Agent ID Developer

And Azure subscription contributor or owner access.

Solution: Verify you have required permissions in Microsoft Entra.

Note

If you have Agent ID Administrator or Agent ID Developer role (not Global Administrator), a365 setup all still succeeds but skips OAuth2 permission grants. After setup completes, the CLI prints the next steps for a Global Administrator to complete the remaining grants. This workflow is expected for organizations where the agent developer and the Global Administrator are different people.

Missing Azure CLI authentication

Symptom: Setup fails with authentication errors.

Solution: Make sure you're connected to Azure and verify your account and subscription.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Resource already exists

Symptom: Setup fails with Resource already exists error for resource group, App Service plan, or Web App.

Solutions: Choose one of the following solutions.

  • Use existing resources

    If resources exist and you want to use them, ensure they match your configuration. Use the az resource list PowerShell command.

    az resource list --resource-group <your-resource-group>

  • Delete conflicting resources

    Delete the resource group or rename your resources in a365.config.json and rerun setup.

    Use the az group delete PowerShell command to delete a resource group.

    # WARNING: This command deletes all resources in it
az group delete --name <your-resource-group>

  • Use cleanup command to start fresh

    Use the cleanup command to remove all Agent 365 resources, then use the a365 setup all command to rerun setup.

    Warning

    Running a365 cleanup is destructive.

    a365 cleanup
a365 setup all

Symptom: You opened browser windows during setup but closed them without completing consent, or setup completed but OAuth2 permission grants are still pending.

Solution: Choose based on your role:

  • Global Administrator: Run a365 setup all again. The CLI prompts for admin consent. Complete the consent flow in the browser window that appears.

  • Agent ID Administrator or Developer: You can't complete OAuth2 grants directly. Run a365 setup all — the setup summary prints the next steps for a Global Administrator, including a direct link or consent URL to complete the grants. Share those details with your Global Administrator.

Configuration files missing or invalid

Symptom: Setup fails with "Configuration not found" or validation errors.

Solution:

  1. Verify the a365.config.json file exists.
  2. If missing or invalid, create it manually or use a365 setup all --agent-name <name> (agents only).
# Verify a365.config.json exists
Test-Path a365.config.json

Setup completes but resources aren't created

Symptom: Setup command succeeds but Azure resources don't exist.

Solution:

  1. Check created resources by opening a365.generated.config.json in your working directory.
  2. Verify Azure resources exist by using the az resource list command.
  3. If resources are missing, check for errors in setup output and rerun setup by using the a365 setup all command.
# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Agent blueprint not registered in Microsoft Entra

Symptom: Setup completes but you can't find agent blueprint in Microsoft Entra admin center.

Solution:

  1. Get blueprint ID from a365.generated.config.json.

    Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId

  2. Search in Microsoft Entra admin center:

    1. Go to: Microsoft Entra admin center.
    2. Navigate to App registrations > All applications.
    3. Search for your agentBlueprintId.

  3. If not found, rerun setup by using the a365 setup all command.

    a365 setup all

API permissions not granted

Symptom: Setup completes but permissions show as "Not granted" in Microsoft Entra.

Solution:

  1. Open Microsoft Entra admin center.

  2. Find your agent blueprint app registration.

  3. Go to API permissions.

  4. Grant admin consent:

    1. Select Grant admin consent for [Your Tenant].
    2. Confirm the action.

  5. Verify all permissions show green checkmarks.

Managed identity not enabled

Symptom: Web App exists, but managed identity isn't enabled.

Solution:

  1. Check managed identity status by using the az webapp identity show command.
  2. If not enabled, enable it manually by using the az webapp identity assign command.
  3. Verify it's enabled by using the az webapp identity show command.
# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

Setup takes too long or stops responding

Symptom: Setup command runs for more than 10 minutes without completing.

Solution:

  1. If you're running as Global Administrator, check if a browser window is waiting for admin consent. Complete the consent flow to unblock setup.

  2. If setup truly stops responding, cancel it (Ctrl+C) and check what was created.

    # Check generated config
Get-Content a365.generated.config.json | ConvertFrom-Json

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Clean up and retry.

    a365 cleanup
a365 setup all

Clean up a config-free agent

Symptom: You provisioned an agent with a365 setup all --agent-name <name> and now want to remove it, but you don't have an a365.config.json file.

Solution: Use a365 cleanup --agent-name to remove the agent without a config file. The CLI reads resource IDs from the global generated config that was written during bootstrap setup.

a365 cleanup --agent-name <your-agent-name>

Tip

If the command stalls on authentication, it automatically falls back to device code flow. Follow the instructions printed in the terminal to complete sign-in.

If you no longer have the global generated config (for example, after reinstalling the CLI), use a365 cleanup with a manually created minimal a365.config.json, or remove resources directly via Azure Portal and Microsoft Entra admin center.

Unable to send first message in Teams

Symptom: After provisioning an agent instance, it can't send a message to the agent manager as a welcome message.

Solution: The [Chat.Create][perm-chatcreate] permission is required to create a new chat object. If a one-on-one chat already exists, this operation returns the existing chat and doesn't create a new one.

  • To implement, configure your blueprint's inheritable permissions to include the Chat.Create scope.
  • Configure a Teams chat message to send once an agent instance is provisioned.
  • Create a new agent instance from the blueprint and test the first-run message.
  • Last updated on