Ixxerja permezz ta’

Setup agent blueprint

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.

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

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 Administrator
      • Agent ID Developer
    • Access to an Azure subscription with permissions to create resources

  3. Valid a365.config.json file in your working directory, set up via this step: Setting up Agent 365 config.

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.

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

  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 Administrator or Developer, no browser window appears; the CLI generates consent URLs for a Global Administrator to complete later.

Setup by using Agent ID Administrator or Agent ID Developer

If you run as Agent ID Administrator or 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 1: Run setup as Agent ID Admin or Developer
a365 setup all
# Setup completes all steps it can. The CLI displays next steps
# showing how a Global Administrator can complete the OAuth2 grants.

# Step 2: Share the config folder with a Global Administrator.
# The folder contains a365.config.json and a365.generated.config.json.

# Step 3: The Global Administrator runs:
a365 setup admin --config-dir "<path-to-config-folder>"

Alternatively, the Global Administrator can open the combined consent URL that the CLI saves to a365.generated.config.json (field: combinedAdminConsentUrl) and grant consent in a single browser visit. For more information, see a365 setup admin.

Verify setup

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

  1. Verify generated configuration:

    a365 config display -g

    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 runs a365 setup admin to complete the OAuth2 permission grants.

  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 config permissions to add the required resource permissions to your config, and then run a365 setup permissions custom to apply them to your blueprint in Microsoft Entra.

# Add resource permissions to config
a365 config permissions `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

# Apply permissions to your blueprint
a365 setup permissions custom

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 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, a Global Administrator must run a365 setup admin 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. Use the handoff workflow:

    # Option 1: Global Admin runs setup admin
a365 setup admin --config-dir "<path-to-config-folder>"

# Option 2: Global Admin opens the combined consent URL
# Find the URL in a365.generated.config.json (combinedAdminConsentUrl field)
a365 config display -g

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. Display current configuration using the a365 config display command.
  3. If missing or invalid, reinitialize using the a365 config init command.
# Verify a365.config.json exists
Test-Path a365.config.json

# Display current configuration
a365 config display

# If missing or invalid, re-initialize
a365 config init

Setup completes but resources aren't created

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

Solution:

  1. Check created resources using the a365 config display -g command.
  2. Verify Azure resources exist using the az resource list command.
  3. If resources are missing, check for errors in setup output and rerun setup using the a365 setup all command.
# Check created resources
a365 config display -g

# 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 generated config using the a365 config display -g command.

    a365 config display -g
# Look for: 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 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 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
a365 config display -g

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

  3. Clean up and retry.

    a365 cleanup
a365 setup all

Unable to send first message in Teams

Symptom: Once an agent instance is provisioned, 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