将代理部署到Azure

重要

你需要成为Frontier 预览计划的一员，才能获取 Microsoft Agent 365 的提前访问权限。 边界将你直接与Microsoft最新的 AI 创新联系起来。 Frontier 预览版受客户协议中现有预览条款的约束。 由于这些功能仍在开发中，其可用性和功能可能会随时间而变化。

你已生成代理并将其在本地测试。 现在，让它在云端生动起来。 此步骤是可选的。 如果已将代理部署到某些云（甚至不需要 Azure），则可以跳过它。

本指南将指导你将代理代码部署到 Azure，并将其发布到 Microsoft 管理中心，其中它将成为组织的可发现资产。

若要更新消息传送终结点，请参阅以下资源。 它们演示了将代理部署到 Amazon Web Services 或 Google Cloud Platform 等其他云提供商时如何更新消息传送终结点：

• 使用部署在亚马逊网络服务中的代理代码
• 使用部署在 Google Cloud Platform 中的代理代码

先决条件

在开始之前，请确保具有以下项：

所需账户和权限

• 具有贡献者访问权限的 Azure 订阅。
• 拥有有效且可达的消息端点的可工作代理代码。 确保 在本地测试代理 ，并选择性地 使用开发隧道通过 Microsoft 365 进行测试 ，以验证是否可以生成代理代码并按预期运行。
• 通过完成 安装代理蓝图步骤来验证代理蓝图。
• 最新的配置文件包括a365.config.json、a365.generated.config.json和代码中的配置文件（例如 .env 文件）。

必需工具

• Azure CLI 已安装并经过身份验证（Install Azure CLI）

部署到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 应用部署操作。

警告

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

验证部署

部署完成后，请使用此列表和以下部分中的说明来验证部署。

✅ 部署命令顺利完成，没有错误
✅ 网页应用正在运行
✅ 应用日志显示启动成功
✅ 环境变量已配置
✅ 消息传送终结点响应

验证部署命令完成时没有错误

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

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

查看详细部署历史：

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

如果构建失败：

• 先在本地清理和重建，确认组装是否可行。
• 检查是否有缺失的依赖或语法错误。
• 参见 部署命令失败。

如果应用部署后崩溃：

• 查看日志中的具体错误信息。
• 确认所有必要的环境变量都已设置。
• 请参见 启动时应用程序崩溃。

确认网页应用是否运行

用命令az webapp show确认网页应用正在运行。

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 命令 读取网页应用日志：

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

如果日志中出现崩溃或错误信息，请参见 启动时的应用程序崩溃。

验证环境变量是否已配置完毕

在 Azure 门户中：

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

如果环境变量没有设置：

• 重新运行部署以从 .env 文件同步。
• 或在 Azure 门户中手动设置它们。
• 参见 环境变量未设置或错误。

验证消息端点是否响应

使用 PowerShell 或其他方式测试在 Web 应用 “概述 ”页中找到的终结点是否存在。 否则，请参阅 消息传送终结点上的 404。

后续步骤

接下来，将你的代理应用发布到 Microsoft 管理中心，这样你可以从中创建代理实例和用户。

发布您的代理

您的客服现在已在云端上线，随时准备响应代理请求。 当您的代理正在处理实际的请求时，请考虑以下步骤以优化您的代码：

• 监控性能：利用 可观测性功能 追踪代理行为并优化响应。
• 增加更多工具：探索 工具目录 ，扩展经纪人的能力。
• 迭代和改进：更新你的代理代码，重新部署并重新发布（记得增加版本号！）。
• 在组织内扩展：分享你的经纪人成功案例，推动采用。

Troubleshooting

本部分介绍将代理部署到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 Apps 以确认目标是否存在：

  # 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 应用未运行。

解决 方案： 使用 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 错误

症状： 网页应用正在运行，但 /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 中失败

Symptom：代码在您的计算机上构建成功，但在 Azure 部署时失败。

解决方案：

• 检查平台特定的依赖关系

  • 有些软件包有平台特定的构建版本。
  • 确保依赖项支持 Linux（默认情况下Azure Web Apps在 Linux 上运行）。

• 验证运行时版本匹配

  运行以下命令：

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

  将以下设置与门户中的 Azure 运行时进行比较：Settings>Configuration>General settings>Stack settings。

有关其他帮助，请参阅： 消息传送终结点故障排除。