将智能体部署到 Azure

您已经构建了智能体并在本地进行了测试。 现在，让它在云端投入使用吧。 此步骤是可选的。 如果您已经将智能体部署到某个云平台（甚至不必是 Azure），则可以跳过此步骤。

本指南将引导您将智能体代码部署到 Azure，并将其发布到 Microsoft 管理中心，在那里它将成为您组织的注册资产。

要更新消息传递端点，请参阅以下资源。 这些资源展示了如果您将智能体部署到其他云提供商（如 Amazon Web Services 或 Google Cloud Platform）时，如何更新消息传递端点：

必备条件

开始之前，请确保您具备以下条件：

必需的帐户和权限

  • 具有“参与者”访问权限的 Azure 订阅。
  • 可正常运行的智能体代码，且具有有效且可访问的消息传递端点。 请确保您已 在本地测试过智能体，并可选地 使用 Dev Tunnels 与 Microsoft 365 进行测试，以验证智能体代码能否按预期构建并运行。
  • 通过完成 设置智能体蓝图步骤 获得有效的智能体蓝图。
  • 最新的配置文件 a365.config.json、a365.generated.config.json 以及代码中的配置文件（例如 .env 文件）。

所需的工具

部署到 Azure

使用标准 Azure 工具（如 Azure CLI、Azure 门户或 GitHub Actions）将智能体应用程序代码部署到 Azure。

部署智能体应用程序

使用 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 Actions，请使用 Azure Web 应用 Deploy 操作。

警告

机密管理：将环境变量（包括 API 密钥和机密）存储为 Azure 应用设置，而不是保存在代码或配置文件中。 对于生产环境，请使用 Azure 密钥保管库 来存储敏感机密。 了解有关 在 ASP.NET Core 开发中安全存储应用机密 和 Azure 密钥保管库 配置提供程序 的更多信息。 切勿将 .env 包含敏感信息的文件提交到源代码控制。

验证部署

部署完成后，请使用此列表以及后续各节中的说明来验证部署。

✅ 部署命令已无错误地完成
✅ Web 应用正在运行
✅ 应用程序日志显示启动成功
✅ 环境变量已配置
✅ 消息传递端点响应正常

验证部署命令是否无错误完成

部署完成后，请在部署日志中验证是否成功：

  1. 在 Azure 门户中转到 Web 应用。
  2. 转到 设置>配置 以验证应用设置。
  3. 在部署中心检查部署日志。

要查看详细的部署历史记录：

  1. 转到 Azure 门户 > 您的 Web 应用
  2. 部署>部署中心
  3. 查看最新部署的日志

如果构建失败：

  • 请先在本地清理并重新构建，以确认构建正常。
  • 检查是否缺少依赖项或存在语法错误。
  • 请参阅 部署命令失败。

如果应用在部署后崩溃：

验证 Web 应用是否正在运行

使用 az webapp show 命令 验证 Web 应用是否正在运行。

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

此命令的预期输出为 Running。

验证应用程序日志是否显示启动成功

要在 Azure 门户中查看 Web 应用日志：

  1. 在 Azure 门户中按名称搜索该 Web 应用。
  2. 转到 概览>日志>日志流。

或者，您可以使用 PowerShell az webapp log tail 命令 读取 Web 应用日志：

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

如果日志中存在崩溃或错误消息，请参阅 应用程序在启动时崩溃。

验证环境变量是否已配置

在 Azure 门户中：

  1. 转到您的 Web 应用。
  2. 转到 设置>环境变量。
  3. 验证您的设置是否存在。

如果环境变量未设置：

验证消息端点是否响应

使用 PowerShell 或其他方式测试 Web 应用 概览 页面中找到的端点是否存在。 否则，请参阅消息传递端点 404 错误。

后续步骤

接下来，将您的智能体应用程序发布到 Microsoft 管理中心，以便您可以从中创建智能体实例和用户。

发布您的智能体

您的智能体现已部署到云端，并准备好响应智能体请求。 随着您的智能体处理实际请求，请考虑针对代码采取以下后续步骤：

  • 监控性能：使用 可观测性功能 来跟踪智能体行为并优化响应。
  • 添加更多工具：探索 工具目录 以扩展智能体的功能。
  • 迭代与改进：更新智能体代码、重新部署并重新发布（记得递增版本号！）。
  • 在组织内扩展：分享智能体的成功案例，推动其采用。

故障排除

本节介绍了将智能体部署到 Azure 时常见的问题。

提示

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

  • Web 应用未创建

    列出 Web 应用以确认目标是否存在：

    # 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"

Web 应用已停止

症状： 部署成功，但 Web 应用未运行。

解决方案： 使用 az webapp start 和 az webapp show 启动 Web 应用并验证其是否正在运行。

# 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

应用程序在启动时崩溃

症状： Web 应用启动后立即崩溃；日志中显示错误。

常见原因：

  • 缺少依赖项 - 检查构建输出，确保其中包含所有必需的包。
  • 缺少环境变量 - 验证是否已配置所有必需的设置。
  • 运行时版本不匹配 - 确保 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 错误

症状： Web 应用正在运行，但 /api/messages 端点返回 404 错误。

解决方案：

  1. 验证智能体代码中的路由配置。
  2. 检查端点处理程序是否已正确注册。
  3. 确保在部署中指定了正确的入口点。

通过向 URL 发送 GET 请求来测试该端点。 使用 az webapp config show 命令 检查 Web 应用配置。

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 Web 应用 默认在 Linux 上运行）。

  • 验证运行时版本是否匹配

    运行以下命令：

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

    请与门户中的 Azure 运行时进行对比：设置>配置>常规设置>堆栈设置。

如需更多帮助，请参阅：消息传递端点故障排除。

  • Last updated on