Deploy agent to Azure

You built your agent and tested it locally. Now, bring it to life in the cloud. This step is optional. You can skip it if you already deployed your agent to some cloud (it 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.

To update the messaging endpoint, see the following resources. They show how you can update the messaging endpoint if you 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 items:

Required accounts and permissions

• Azure subscription with contributor access.
• Working agent code with a valid and reachable messaging endpoint. Ensure you tested your agent locally and optionally tested with Microsoft 365 using Dev Tunnels to verify the agent code can be built and runs as expected.
• Valid agent blueprint by completing the setup agent blueprint step.
• Up-to-date configuration files a365.config.json, a365.generated.config.json, and config file in the code (for example, .env file).

Required tools

• Azure CLI installed and authenticated (Install Azure CLI)

Deploy to Azure

Deploy your agent application code to Azure by using standard Azure tooling such as the Azure CLI, Azure portal, or GitHub Actions.

Deploy agent application

Use the Azure CLI az webapp deploy command to deploy your application:

# Build your project first (example for .NET)
dotnet publish -c Release -o ./publish

# Deploy to Azure Web App
az webapp deploy --name <your-web-app> --resource-group <your-resource-group> --src-path ./publish

For GitHub Actions, use the Azure Web Apps Deploy action.

Verify deployment

After the deployment finishes, use this list and the instructions in the following sections 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

After deployment finishes, verify success in deployment logs:

1. 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. Go 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. Go to your web app.
2. Go to Settings > Environment Variables.
3. Verify your settings exist.

If the environment variables aren't set:

• Rerun deploy to sync from the .env file.
• Or manually set them in the 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 by using 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.

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.

Deploy command fails

Symptom: Deployment to Azure fails.

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
  

• 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
  

• 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 the web app isn't running.

Solution: Use az webapp start and az webapp show to start the web app and verify it's 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 to ensure it includes 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

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.

For additional help, see: Messaging endpoint troubleshooting.