Deploy agent to Azure

Вы создали свой агент и протестировали его локально. Теперь оживите его в облаке. Этот шаг необязательный. Вы можете пропустить это, если уже развернули агента в облаке (это даже не обязательно должен быть Azure).

Это руководство проведёт вас через развертывание кода агента в Azure и публикации его в административном центре Microsoft, где он становится зарегистрированным активом вашей организации.

Чтобы обновить конечную точку обмена сообщениями, смотрите следующие ресурсы. Они показывают, как можно обновить конечную точку обмена сообщениями, если вы развернули своего агента другим облачным провайдерам, таким как Amazon Web Services или Google Cloud Platform:

• Использование кода агента, развернутого в Amazon Web Services
• Используйте код агента, развернутый в Google Cloud Platform

Предпосылки

Перед началом работы убедитесь, что у вас есть следующие элементы:

Необходимые учетные записи и разрешения

• Подписка Azure с доступом для участников.
• Рабочий код агента с корректной и доступной конечной точкой для обмена сообщениями. Убедитесь, что вы протестировали своего агента локально и по возможности с Microsoft 365 с помощью туннелей разработчика , чтобы убедиться, что код агента может быть построен и выполняться как ожидается.
• Валидный чертеж агента, выполнив шаг чертежа агента настройки.
• Актуальные конфигурационные файлы a365.config.json, a365.generated.config.json, и конфигурационный файл в коде (например, файл .env).

Необходимые средства

• Azure CLI установлен и прошел проверку подлинности (Установить Azure CLI)

Развертывание в Azure

Развернуть код вашего агентного приложения в Azure с помощью стандартных инструментов Azure, таких как Azure CLI, Azure portal или GitHub Actions.

Развертывание агентного приложения

Используйте команду Azure CLI az webapp deploy для развертывания вашего приложения:

# 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

Для действий GitHub используйте действие Azure веб-приложения Deploy.

Предупреждение

Управление секретами: храните переменные среды, включая ключи API и секреты, в настройках приложение Azure Settings, а не в коде или конфигурационных файлах. Для производственных сред используйте Azure Key Vault для чувствительных секретов. Узнайте больше о безопасном хранении секретов приложений, разрабатываемых в ASP.NET Core и провайдере конфигурации Azure Key Vault. Никогда не фиксируйте .env файлы с конфиденциальной информацией в систему контроля версий.

Проверка развертывания

После завершения развертывания используйте этот список и инструкции в следующих разделах для проверки развертывания.

✅ Команда развертывания завершена без ошибок
✅ Веб-приложение работает
✅ Журналы приложений показывают успешный запуск
✅ Переменные среды настроены
✅ Ответ на конечную точку сообщений

Проверьте выполненную команду развертывания без ошибок

После завершения развертывания проверьте успех в журналах развертывания:

1. Перейдите в веб-приложение в портал Azure.
2. Перейдите в Настройки> Настройки, чтобы проверить настройки приложения.
3. Проверьте журналы развертывания в центре развертывания.

Чтобы увидеть подробную историю развертывания:

1. Go to Azure portal > Ваше веб-приложение
2. Развертывание>Центр развертывания
3. Просмотр логов вашего последнего развертывания

Если сборка провалится:

• Сначала очистите и перестройте на месте, чтобы убедиться, что сборка работает.
• Проверьте отсутствие зависимостей или синтаксических ошибок.
• См. Команда «Развернуть» не удалась.

Если приложение вылетает после развертывания:

• Проверьте логи на наличие конкретных сообщений об ошибках.
• Проверьте, что все необходимые переменные среды установлены.
• См. раздел «Сбои приложений при запуске».

Проверьте, запущено ли веб-приложение

Используйте az webapp show команду , чтобы убедиться, что веб-приложение запущено.

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

Ожидаемый выход этой команды равен Running.

Проверьте, что журналы приложений показывают успешный запуск

Чтобы просмотреть логи веб-приложений в портале Azure:

1. Ищите веб-приложение по названию в портале Azure.
2. Перейдите в раздел Обзор>журналов>Поток журналов.

В качестве альтернативы можно использовать команду PowerShell az webapp log tail для чтения логов веб-приложений:

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

Если в журналах есть сообщения о сбоях или ошибках, см. раздел «Сбои приложений при запуске».

Проверьте, что переменные среды настроены

На портале Azure:

1. Зайдите в своё веб-приложение.
2. Перейдите в настройки>переменных окружения.
3. Убедитесь, что у вас есть настройки.

Если переменные среды не установлены:

• Перезапустите .env развертывание для синхронизации из файла.
• Или назначить их вручную в портале Azure.
• См. раздел «Переменные среды не установлены или некорректны».

Проверьте ответы на конечную точку сообщений

Проверьте, существует ли конечная точка, которую вы находите на странице обзора вашего веб-приложения, с помощью PowerShell или других способов. В противном случае см. 404 по конечной точки обмена сообщениями.

Дальнейшие шаги

Далее опубликуйте приложение агента в Microsoft Admin Center, чтобы создавать экземпляры агентов и пользователей из него.

Опубликуйте своего агента

Ваш агент теперь работает в облаке и готов отвечать на запросы агентов. Поскольку ваш агент обрабатывает реальные запросы, рассмотрите следующие шаги для вашего кода:

• Мониторинг производительности: используйте функции наблюдаемости для отслеживания поведения агентов и оптимизации реакций.
• Добавьте больше инструментов: Изучите каталог инструментов , чтобы расширить возможности вашего агента.
• Итерируйте и улучшайте: обновляйте код агента, перезапускайте и публикуйте (не забывайте увеличивать номер версии!).
• Масштабируйтесь по всей организации: делитесь историями успеха вашего агента, чтобы стимулировать внедрение.

Устранение неполадок

В этом разделе описаны распространённые проблемы при развертывании агентов в Azure.

Tip

Руководство по устранению неполадок Agent 365 содержит рекомендации по решению неполадок на высоком уровне, лучшие практики и ссылки на контент по устранению неполадок для каждой части жизненного цикла разработки Agent 365.

Команда развертывания не удаётся

Симптом: Развертывание в Azure не удалось.

Распространенные причины и решения:

• Ошибки сборки

  Перестройте проект локально, чтобы увидеть подробные ошибки компиляции:

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

• Azure аутентификация истекла

  Войдите снова в Azure:

  az login
  az account show  # Verify correct subscription
  

• Веб-приложение не создано

  Перечислите веб-приложения, чтобы подтвердить, что целевой объект существует:

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

• Проверьте журналы развертывания

  Используйте az webapp log tail команду для просмотра подробных журналов развертывания:

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

• Проверка

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

Веб-приложение остановлено

Симптом: Развертывание проходит успешно, но веб-приложение не работает.

Решение: Используйте az webapp start и az webapp show чтобы запустить веб-приложение и убедиться, что оно работает.

# 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

Сбои приложений при запуске

Симптом: Веб-приложение запускается, но сразу же вылетает; Логи показывают ошибки.

Распространенные причины:

• Отсутствующие зависимости — проверьте выход сборки, чтобы убедиться, что он включает все необходимые пакеты.
• Отсутствуют переменные среды — убедитесь, что все необходимые настройки настроены.
• Несоответствие версий во время выполнения — убедитесь, что Azure соответствует вашей среде разработки.
• Ошибки кода — проверьте логи приложений на предмет конкретных исключений.

Решение: Используйте az webapp log tailкоманды , az webapp config appsettings listи az webapp config appsettings set для просмотра логов, проверки переменных среды и установки отсутствующих переменных.

# 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 на конечной точке обмена сообщениями

Симптом: Веб-приложение работает, но /api/messages конечная точка возвращает 404.

Solution:

1. Проверьте конфигурацию маршрута в коде агента.
2. Проверьте, правильно ли регистрируется обработчик конечной точки.
3. Убедитесь, что правильная точка входа указана при развертывании.

Проверьте конечную точку, отправив GET запрос на URL. Используйте az webapp config show команду , чтобы проверить конфигурацию веб-приложения.

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

Переменные окружения не установлены или некорректны

Симптом: Развертывание проходит успешно, но агент не работает; Отсутствуют ошибки настройки в журналах.

Решение: Проверяйте и обновляйте переменные среды. Используйте az webapp config appsettings listкоманды , и az webapp config appsettings set для проверки переменных среды и установите отсутствующие переменные. Потом перебрасываться.

# 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

Сборка успешно проходит локально, но не работает в Azure

Симптом: Код хорошо накапливается на вашем компьютере, но не работает во время развертывания Azure.

Решения:

• Проверьте наличие платформенных зависимостей

  • Некоторые пакеты имеют платформенные билды.
  • Убедитесь, что зависимости поддерживают Linux (Azure веб-приложения по умолчанию работают на Linux).

• Проверьте соответствие версий по времени выполнения

  Выполните следующие команды.

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

  Сравните с Azure runtime в Portal: Настройки>Конфигурация>Общие настройки>Настройки стека.

Для дополнительной помощи см.: Устранение неисправностей с endpoint в обмене сообщениями.