Agent 365 troubleshooting guide

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 authentication
Agent 365 CLI
Custom client app registration for Agent 365 CLI
Mock tooling server
Agent observability
Testing agents
Test agents by using Dev Tunnels
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
Get-Content a365.config.json | ConvertFrom-Json

# Display generated configuration (after setup)
Get-Content a365.generated.config.json | ConvertFrom-Json

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
Get-Content a365.generated.config.json | Select-String "agentBlueprintId"

Verify blueprint in Microsoft Entra

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

Troubleshoot CLI authentication

Agent 365 setup uses the Microsoft-managed Agent 365 CLI enterprise application when it's available and falls back to a tenant-owned custom app. For full behavior and verification steps, see Microsoft Entra authentication.

Symptom Resolution
Microsoft-managed application isn't found Update the CLI and run a365 setup requirements. Search Enterprise applications for application ID f54280f4-395e-4ea8-9e48-bf2d4952aa14. If the staged rollout hasn't reached your tenant, use the custom app fallback.
AADSTS530035 during device code authentication Security Defaults or Conditional Access blocks device code. Don't disable organizational security policy. Run the CLI on native Windows to use WAM, or work with your identity administrator to use an approved tenant-owned custom app.
AADSTS70007 during authentication Update to the latest CLI. Older versions could use an unsupported browser response mode with the Microsoft-managed application.
Required delegated scopes are missing Run a365 setup requirements again. Don't modify the Microsoft-managed application or create a tenant-local permission grant for it. If you use a tenant-owned app, follow CLI validation fails during configuration.

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
✅ Microsoft-managed Agent 365 CLI enterprise app available, or custom client app 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

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