Share via

Agent 365 troubleshooting guide

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.

Use this guide to diagnose and resolve problems across the entire Agent 365 development lifecycle. Use this article as your starting point for troubleshooting, and then go to specific sections for detailed solutions.

Troubleshooting steps

Each of the links in this table provides troubleshooting steps for specific areas. The content is grouped by the stage of the Agent 365 SDK development lifecycle.

Stage Troubleshooting content
Build and run agent Agent 365 CLI
Custom client app registration for Agent 365 CLI
Mock tooling server
Agent observability
Testing agents
Setup Agent 365 config Set up Agent 365 config
Add and manage tools
Setup agent blueprint Setup Agent blueprint
Deploy Deploy agent to Azure
Deploy agent to Amazon Web Services (AWS)
Deploy agent to Google Cloud Platform (GCP)
Publish agent to Microsoft 365 admin center Publish agent to Microsoft admin center
Create agent instances Create agent instances

Diagnostic commands reference

Before diving into specific problems, use these commands to check the current state of your Agent 365 setup:

Check CLI and configuration

Use these commands to validate your CLI and configuration.

# Verify CLI is installed and check version
a365 --version

# Display current configuration
a365 config display

# Display generated configuration (after setup)
a365 config display -g

Verify Azure resources

Use these commands to inspect Azure resources and app status.

# Set these variables with appropriate data for your app
$resource-group = <your-resource-group>
$app-name = <your-app-name>

# Authenticate with Azure
az login

# List resources in your resource group
az resource list --resource-group $resource-group --output table

# Check Web App status
az webapp show --name $app-name --resource-group $resource-group --query state

# View Web App logs (real-time)
az webapp log tail --name $app-name --resource-group $resource-group

Verify agent blueprint

Confirm your agent blueprint exists and is correctly configured.

# Check if blueprint ID is set
a365 config display -g | Select-String "agentBlueprintId"

Verify blueprint in Microsoft Entra

  1. Go to https://entra.microsoft.com > App registrations > All applications.
  2. Search for your agentBlueprintId.

Preventive best practices

Use these recommendations to prevent common issues and streamline troubleshooting.

Before you start

Prerequisites checklist:

✅ .NET 8.0 SDK installed
✅ Azure CLI installed and authenticated
✅ Required Entra permissions assigned
✅ Custom client app created and configured
✅ Tenant enabled for Microsoft Agent 365 Frontier

Validation commands:

# Check .NET
dotnet --version

# Check Azure CLI
az --version
az account show

# Check CLI installation
a365 --version

During development

Save your configurations:

  • Keep backups of configuration files.
  • Document your setup choices.
  • Save generated IDs, such as blueprint ID and managed identity ID.

Keep CLI updated:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli --prerelease

Test incrementally:

  • Test after each major step.
  • Verify success before moving on.
  • Keep working configurations.

Before deployment

Pre-deployment checklist:

✅ Agent works locally with Agents Playground.
✅ All environment variables documented.
✅ Configuration files committed to source control.
✅ MCP servers configured and tested.
✅ Observability enabled and verified.

Get additional help

To review sample code, report problems, or search existing problems, use these repositories:

  • Last updated on