Deploy agent to Azure

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.

You've built your agent and tested it locally—now it's time to bring it to life in the cloud. This step is optional and can be skipped if you have already deployed your agent to some cloud (doesn't even need to be Azure).

This guide walks you through deploying your agent code to Azure and publishing it to Microsoft admin center, where it becomes a discoverable asset for your organization.

There are also resources available to show how you can update the messaging endpoint if instead of Azure, you have already deployed your agent to other cloud providers like Amazon Web Services or Google Cloud Platform:

• Use agent code deployed in Amazon Web Services
• Use agent code deployed in Google Cloud Platform

Prerequisites

Before you begin, ensure you have the following:

Required accounts and permissions

• Azure subscription with contributor access.
• Working agent code with a valid and reachable messaging endpoint. Please ensure that you have tested this locally and verify that the agent code can be built and run.
• Complete the setup agent blueprint step to have a valid agent blueprint.
• Ensure configuration files a365.config.json, a365.generated.config.json and config file in the code (eg. .env file) are up to date.

Required tools

• Azure CLI installed and authenticated (Install Azure CLI)
• A365 CLI installed (Agent 365 CLI)

Deploy to Azure

The a365 deploy command has two subcommands:

• a365 deploy app - Deploys your agent code to the Azure Web App created during setup.
• a365 deploy mcp - Updates MCP server permissions on your agent blueprint.

This guide focuses on deploying your agent application code to Azure.

Deploy agent application

Run the a365 deploy command:

a365 deploy

Deployment options

The deploy command supports several useful options:

Option	Description	Use Case
--dry-run	Shows what would be deployed without executing	Preview deployment steps before running
--inspect	Pauses before deployment to inspect publish folder and ZIP contents	Debug deployment package issues
--restart	Skips build and compresses existing publish folder	Quick iteration after manual changes
-v, --verbose	Enables detailed logging	Troubleshooting deployment issues
-c, --config	Specifies custom config file path	Using non-default configuration

Note

Use a365 deploy --help to see all available options and subcommands.

Deployment example

# Preview what will be deployed
a365 deploy --dry-run

# Deploy with verbose logging for troubleshooting
a365 deploy --verbose

# Inspect the deployment package before uploading
a365 deploy --inspect

How deployment works

Deployment works differently depending on the programming language you use.

.NET

The deploy command for .NET agents:

• Detects .NET project files (*.csproj, *.fsproj, or *.vbproj)
• Restores NuGet packages by using dotnet restore
• Publishes application by using dotnet publish with Release configuration
• Creates Oryx manifest with entry point DLL command (for example, dotnet YourApp.dll)
• Configures Azure runtime based on detected .NET version (default: DOTNET|8.0)
• Deploys via zip with real-time progress

Python

The deploy command for Python agents:

• Detects Python project structure (pyproject.toml, requirements.txt, and *.py files)
• Builds packages by using uv build if pyproject.toml exists
• Converts .env to Azure App Settings automatically
• Uses smart startup detection to find Agent 365 entry points
• Deploys via zip with real-time progress

Node.js

The deploy command for Node.js agents:

• Detects Node.js project structure (package.json file)
• Installs dependencies by using npm ci (falls back to npm install if needed)
• Runs build script (npm run build) if defined in package.json
• Copies application files: built output (dist/build) or source files
• Copies node_modules for Azure deployment
• Creates Oryx manifest with start command from package.json (or detects entry point)
• Configures Azure runtime based on detected Node version (default: NODE|18)
• Deploys via zip with real-time progress

Warning

Secrets management: When you deploy, store environment variables (including API keys and secrets) as Azure App Settings. While environment variables are commonly used for configuration, they're stored in plain text. For production environments, use Azure Key Vault for sensitive secrets. Learn more about Safe storage of app secrets in development in ASP.NET Core and Azure Key Vault configuration provider. Never commit .env files with sensitive information to source control.

Verify deployment

After the deployment finishes, use this list and the instructions below to verify deployment

✅ Deployment command completed without errors
✅ Web app is running
✅ Application logs show successful startup
✅ Environment variables are configured
✅ Messaging endpoint responds

Verify deployment command completed without errors

When you run the deploy command you should see:

✓ Build completed successfully
✓ Deployment completed successfully

You should also see success indicated in deployment logs:

1. Search for your configured webAppName and go to your Web App in the Azure portal.
2. Go to Settings > Configuration to verify the app settings.
3. Check the deployment logs in deployment center.

To see detailed deployment history:

1. Navigate to Azure Portal > Your Web App
2. Deployment > Deployment Center
3. View logs for your latest deployment

If the build fails:

• Clean and rebuild locally first to confirm the build works.
• Check for missing dependencies or syntax errors.
• See Deploy command fails.

If the app crashes after deployment:

• Check logs for specific error messages.
• Verify all required environment variables are set.
• See Application crashes on startup.

Verify web app is running

Use the az webapp show command to verify the web app is running.

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

The expected output of this command is Running.

Verify application logs show successful startup

To view web app logs in the Azure portal:

1. Search for the web app by name in the Azure portal.
2. Go to Overview > Logs > Log Stream.

Alternatively, you can use the PowerShell az webapp log tail command to read web app logs:

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

If there are crash or error messages in logs, see Application crashes on startup.

Verify environment variables are configured

In Azure portal:

1. Navigate to your Web App.
2. Go to Settings > Environment Variables.
3. Verify your settings exist

If the environment variables aren't set:

• Re-run deploy to sync from .env file.
• Or manually set in Azure Portal.
• See Environment variables not set or incorrect.

Verify messaging endpoint responds

Test that the endpoint you find in your web-app Overview page exists via Powershell or other means. Otherwise see 404 on messaging endpoint.

Next steps

Next, publish your agent application to Microsoft admin center so you can create agent instances and users from it.

Publish your agent

Your agent is now live in the cloud and ready to respond to agentic requests. As your agent handles real-world requests, consider these next steps for your code:

• Monitor performance: Use observability features to track agent behavior and optimize responses.
• Add more tools: Explore the tooling catalog to expand your agent's capabilities.
• Iterate and improve: Update your agent code, redeploy, and republish (remember to increment the version number!).
• Scale across your org: Share your agent's success stories to drive adoption.

Troubleshooting

This section describes common problems when deploying agents to Azure.

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.

Deploy command fails

Symptom: Error during a365 deploy command execution.

Common causes and solutions:

• Build errors

  Rebuild the project locally to see detailed compilation errors:

  # .NET
  dotnet clean
  dotnet build --verbosity detailed
  
  # Python
  uv build
  
  # Node.js
  npm install
  npm run build
  

• Missing configuration

  Make sure both configuration files exist and are correct:

  # Verify configuration files exist
  Test-Path a365.config.json
  Test-Path a365.generated.config.json
  
  # Display configuration file contents
  a365 config display
  
  # Display generated configuration file contents
  a365 config display -g
  

• Azure authentication expired

  Sign in again to Azure:

  az login
  az account show  # Verify correct subscription
  

• Web App not created

  List Web Apps to confirm the target exists:

  # List Web Apps in resource group
  az webapp list --resource-group <your-resource-group> --output table
  

  If Web App doesn't exist, run setup again:

  # Verify setup was completed
  a365 config display -g
  # Check for: webAppName
  
  # Check Azure resources exist
  az resource list --resource-group <your-resource-group>
  

• Check deployment logs

  Use the az webapp log tail command to view detailed deployment logs:

  az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
  

• Verification:

  # Web App should be running
  az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
  # Expected: "Running"
  

Web app is stopped

Symptom: Deployment succeeds but Web App isn't running.

Solution: Use az webapp start and az webapp show to start the web app and verify it is running.

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

Application crashes on startup

Symptom: Web App starts but immediately crashes; logs show errors.

Common causes:

• Missing dependencies - Check build output included all required packages
• Missing environment variables - Verify all required settings are configured
• Runtime version mismatch - Ensure Azure runtime matches your development environment
• Code errors - Check application logs for specific exceptions

Solution: Use the az webapp log tail, az webapp config appsettings list, and az webapp config appsettings set commands to view logs, check environment variables, and set missing variables.

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

404 on messaging endpoint

Symptom: Web App is running but /api/messages endpoint returns 404.

Solution:

1. Verify route configuration in your agent code.
2. Check that the endpoint handler is properly registered.
3. Ensure the correct entry point is specified in deployment.

Test the endpoint by sending a GET request to the URL. Use the az webapp config show command to check web app configuration.

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

Environment variables not set or incorrect

Symptom: Deployment succeeds but agent doesn't work; missing configuration errors in logs.

Solution: Verify and update environment variables. Use the az webapp config appsettings list, and az webapp config appsettings set commands to check environment variables, and set missing variables. Then redeploy.

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

# Re-run deployment (it will update app settings from .env)
a365 deploy

Deployment package issues

Symptom: Deployment uploads but application doesn't start correctly.

Solution: Use the a365 deploy --inspect flag to examine the deployment package:

# Inspect what will be deployed
a365 deploy --inspect

This flag pauses before upload, allowing you to:

• Check the publish folder contents
• Verify ZIP contents
• Ensure all files are included

Common issues to check:

• Missing node_modules (Node.js)
• Missing compiled DLLs (.NET)
• Missing Python packages

Build succeeds locally but fails in Azure

Symptom: Code builds fine on your machine but fails during Azure deployment.

Solutions:

• Check for platform-specific dependencies

  • Some packages have platform-specific builds.
  • Ensure dependencies support Linux (Azure Web Apps run on Linux by default).

• Verify runtime versions match

  Run these commands:

  # Check your local version
  dotnet --version  # .NET
  node --version    # Node.js
  python --version  # Python
  

  Compare with Azure runtime in Portal: Settings > Configuration > General settings > Stack settings.

• Test with verbose logging

  a365 deploy --verbose
  

For additional help, see: Messaging endpoint troubleshooting