构建部署在 Amazon Web Services (AWS) 中的 Agent 365 智能体

学习如何使用Agent 365 CLI 构建、托管、注册并发布在 AWS Elastic Beanstalk 上运行的 Agent 365 智能体。 Microsoft Entra 和 Graph 提供智能体标识、权限和蓝图，而 AWS Elastic Beanstalk 提供运行时。

如果您希望将智能体指向位于 AWS 端点后方的代码，只需执行以下步骤：配置非 Azure 托管。 然后，按照开始使用 Agent 365 开发中的所有步骤执行操作。

目标

了解如何将 Agent 365 和 Microsoft 365 用作控制平面，以及：

  • 将智能体运行时部署到 AWS Elastic Beanstalk
  • 为非 Azure 托管环境配置 a365.config.json
  • 在 Entra ID 中创建智能体蓝图
  • 配置 OAuth2 + 继承权限
  • 注册指向 AWS 的 Bot Framework 消息终结点
  • 创建智能体标识 + 智能体用户
  • （可选）发布到 Microsoft 365 应用界面
  • 测试端到端交互

必备条件

在开始之前，请确保已满足以下 Azure/Microsoft 365、AWS 和本地环境的先决条件。

Azure/Microsoft 365 先决条件

确认您的 Microsoft Entra 租户访问权限，并安装以下工具以创建标识、蓝图并注册您的智能体。

Amazon Web Services (AWS) 先决条件

请确保以下 AWS 服务和工具已配置，以便部署和管理您的 Elastic Beanstalk 环境。

本地开发环境的前提条件

在本地安装并配置以下工具，以构建、运行和部署该智能体。

创建和部署 .NET 智能体

以下说明描述了如何创建一个具有以下特征的最小智能体：

  • 响应 GET/
  • 接受 POST 上的 Bot Framework 活动/api/messages

创建项目目录

mkdir aws-a365-agent
cd aws-a365-agent

初始化 .NET 项目

为了简化你的体验，本文使用了一个已经准备好的示例。 克隆 Agent365 示例仓库，然后转到 dotnet\semantic-kernel\sample-agent 示例。

语义内核 示例智能体 - C#/.NET 包含以下内容：

  • 一个精简版的 ASP.NET Core Web API
  • Bot Framework 消息处理程序位于/api/messages
  • 健康检查端点 位于 /
  • AI 功能的 语义内核 集成

转到 dotnet\semantic-kernel\sample-agent 并验证项目是否成功生成：

dotnet restore
dotnet build

配置模型

按照步骤 2：LLM 配置中的说明，使用你的 Open API 密钥配置项目。

本地测试（可选）

  1. 在部署到 AWS 之前，先在本地测试你的智能体：

    # Run the application
dotnet run

  2. 在另一个终端测试终结点：

    # Test agent endpoint locally
curl http://localhost:3978

  3. 按 Ctrl+C 停止本地服务器。

构建和部署

选择您偏好的选项来构建并部署此示例应用：

选项 A：从 Visual Studio 构建并部署

使用 Visual Studio 的 AWS 工具包，通过引导向导将应用发布到 Elastic Beanstalk。

  1. 在解决方案资源管理器中，右键单击您的项目。

  2. 选择发布到 AWS Elastic Beanstalk。

  3. 请按照 Beanstalk 部署向导进行操作：

    • 选择您的 AWS 凭据配置文件。
    • 选择区域（例如，us-east-1）。
    • 选择平台 (.NET Core on Linux)。
    • 配置环境设置。

  4. 选择部署。

向导会构建、打包并部署您的应用到 AWS。

选项B：构建并部署到带有 CLI 的 AWS Elastic Beanstalk 上

使用 Elastic Beanstalk CLI 将 .NET 智能体打包并部署到 64 位 Amazon Linux 2 环境。 确保 AWS CLI 和 EB CLI 都已配置好。 应用绑定到由 Beanstalk 设置的 PORT 环境变量。

  1. 构建并发布您的 .NET 应用程序：

    # Publish for Linux runtime (AWS Elastic Beanstalk uses Amazon Linux)
dotnet publish -c Release -o ./publish --runtime linux-x64

    创建包含以下内容的 Procfile。

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. 初始化 Elastic Beanstalk for .NET。 您将被提示选择区域和平台：

    eb init

  3. 选择：

    • 平台：64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • 区域：您首选的 AWS 区域（例如：us-east-1）

  4. 创建部署包并部署：

    cd publish
zip -r ../deploy.zip .
cd ..
eb create aws-a365-agent-env
eb deploy

    此命令：

    • 创建一个 Elastic Beanstalk 应用程序。
    • 创建一个带有负载均衡器的环境。
    • 部署您的应用程序。
    • 预配必要的 AWS 资源。

  5. 完成后，获取您的 Elastic Beanstalk 终结点：

    eb status

    记下您的终结点。 其外观应与下图相似：

    http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com

    这是 Agent 365 开发工具 CLI 使用的 messagingEndpoint 终结点。

备注

对于生产环境，需通过在 Elastic Beanstalk 中添加 SSL/TLS 证书来配置 HTTPS。 Bot Framework 要求生产环境终结点使用 HTTPS。

针对非 Azure 托管环境进行配置

在 Elastic Beanstalk 项目文件夹中手动创建 a365.config.json：

重要提示

对于非 Azure 托管，将 messagingEndpoint 值设置为 Elastic Beanstalk URL 加上 /api/messages 路径。

a365.config.json 文件应如下所示：

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "prod",

  "messagingEndpoint": "http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/api/messages",

  "agentIdentityDisplayName": "MyAwsAgent Identity",
  "agentBlueprintDisplayName": "MyAwsAgent Blueprint",
  "agentUserDisplayName": "MyAwsAgent User",
  "agentUserPrincipalName": "myawsagent@testTenant.onmicrosoft.com",
  "agentUserUsageLocation": "US",
  "managerEmail": "myManager@testTenant.onmicrosoft.com",

  "deploymentProjectPath": ".",
  "agentDescription": "AWS-hosted Agent 365 Agent"
}

下表总结了重要的配置字段及其用途。

字段 含义
messagingEndpoint 您的 Elastic Beanstalk URL + /api/messages
deploymentProjectPath .env 处将进行标记

生成 Agent 365 智能体

针对 AWS 终结点运行智能体代码之后，按照 Agent 365 开发入门中的剩余步骤设置你的 Agent 365 智能体。

端到端验证智能体

使用这些检查确认您的 AWS 托管智能体可以联系、接收 Bot Framework 活动，并在 Agent 365 界面上正确响应。

验证 Elastic Beanstalk 连接性

向您的 Elastic Beanstalk 终结点发送 GET 请求。

curl http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/

请求应返回以下消息：

AWS Agent is running.

查看 Elastic Beanstalk 日志中是否有传入的 Bot Framework 消息

使用 Elastic Beanstalk 日志来验证你的智能体是否正在接收 Bot Framework 活动并正确响应。

eb logs

或者实时流式传输日志：

eb logs --stream

消息到达你的智能体后，你将看到：

POST 200 /api/messages
Received activity: { ... }

从 Agent 365 界面中测试智能体

根据你的环境，你可以从不同界面测试智能体：

  • 智能体操场
  • Teams（如果已发布）
  • 智能体 Shell
  • 联合表面

你可以发送消息并验证你的 Elastic Beanstalk 日志。 了解如何使用 Microsoft Agent 365 SDK 测试智能体，并用智能体操场测试工具验证智能体的功能。

开发人员工作流

设置完成后，按照以下工作流程进行迭代开发：

在本地开发和测试

使用监视模式进行快速开发，实现自动重载：

# Automatically rebuild and restart on file changes
dotnet watch run

在部署之前，先修改代码、保存并在本地进行测试。

构建并重新部署到 AWS Elastic Beanstalk

准备部署变更时：

# Clean previous builds (optional but recommended)
dotnet clean

# Publish optimized release build
dotnet publish -c Release -o ./publish --runtime linux-x64

# Create deployment package
cd publish
zip -r ../deploy.zip .
cd ..

# Deploy to AWS
eb deploy

测试和监视

使用 Agent 365 界面进行测试，并监控 Elastic Beanstalk 日志：

# Stream logs in real-time
eb logs --stream

无需重新创建标识、蓝图、机器人终结点或权限。

故障排除

使用本节内容来诊断和解决在 AWS Elastic Beanstalk 上部署和运行 Agent 365 智能体时遇到的常见问题。 本节涵盖连接性和健康检查。 它还涉及端口绑定、构建错误和许可问题。

提示

Agent 365 故障排除指南 包含高层次的故障排除建议、最佳实践，以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

消息终结点未收到请求

检查以下详细信息：

  • 终结点恰好：
    http://<your-app>.elasticbeanstalk.com/api/messages
  • 你的 Elastic Beanstalk 环境是健康的。 通过使用 eb health 使用检查。
  • 你的安全组允许入站 HTTP 或 HTTPS 流量。
  • 没有阻止访问的防火墙规则或 VPC 限制。

应用程序运行状况问题

检查环境运行状况：

eb health --refresh

查看详细日志：

eb logs

端口绑定问题

确保你的应用监听由环境变量 PORT 指定的端口。 Elastic Beanstalk 会自动设置这个值。

.NET 构建或运行时问题

使用以下命令检查构建错误：

# Clean and rebuild
dotnet clean
dotnet build --verbosity detailed

验证 .NET 版本：

dotnet --version
dotnet --list-sdks

检查包问题：

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

许可证分配失败

手动分配有效的 Microsoft 365 许可证，若支持，可采用无授权用户路径。

  • Last updated on