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

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

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

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

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

Prerequisites

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

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

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

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

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

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

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

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

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

# 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 Actions используйте действие Azure веб-приложения Deploy.

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

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

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

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

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

Проверка того, что команда развертывания завершилась без ошибок

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

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

Для просмотра подробной истории развертывания:

1. Перейдите на портал Azure > ваше веб-приложение
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 OpenTelemetry для отслеживания поведения агентов и оптимизации их реакций.
• Добавьте больше инструментов: Пересмотрите варианты MCP-сервера в Agent 365 , чтобы расширить возможности вашего агента.
• Итерируйте и совершенствуйте: обновляйте код агента, повторно развертывайте и публикуйте его (не забудьте увеличивать номер версии!).
• Масштабируйте агента на всю организацию: делитесь историями успеха вашего агента, чтобы стимулировать принятие.

Troubleshooting

В этом разделе описаны распространенные проблемы при развертывании агентов в 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 на портале: Параметры>Конфигурация>Общие параметры>Параметры стека.

Для получения дополнительной помощи см. раздел Устранение неисправностей в конечных точках обмена сообщениями.