内容
# 游戏后端与基础设施 Agentic 工作流指南
本指南演示了如何使用 AWS 上的多专家代理架构构建 AI 游戏服务器管理平台。该平台使用 Amazon Bedrock AgentCore Runtime 与 Strands Agents 和 Model Context Protocol（MCP）服务器，提供与 AWS 游戏基础设施服务的自然语言交互，包括 Amazon GameLift、Amazon EKS 和 AWS Cost Explorer。
## 目录
- [概述](#概述)
- [架构](#架构)
- [成本](#成本)
- [前提条件](#前提条件)
- [部署](#部署)
- [本地开发](#本地开发)
- [使用](#使用)
- [MCP 集成](#mcp-集成)
- [测试](#测试)
- [监控和可观察性](#监控和可观察性)
- [项目结构](#项目结构)
- [安全](#安全)
- [清理](#清理)
- [贡献](#贡献)
- [许可证](#许可证)
- [注意事项](#注意事项)
## 概述
该解决方案实现了一个对话式 AI 助手，帮助游戏开发者通过自然语言查询管理 AWS 基础设施。中央调度代理将请求路由到特定领域的专家代理，每个专家代理都配备了 MCP 服务器或 AWS SDK 工具，用于其各自的 AWS 服务。
关键功能：
- **GameLift 管理** -- 集群监控、扩缩配置和游戏会话分析
- **EKS/Kubernetes 操作** -- 集群管理、Pod 监控和故障排除
- **成本智能** -- 支出分析、预测和优化建议
- **对话记忆** -- 会话范围的上下文，具有可选的跨会话长期记忆
- **防护栏** -- 通过 Amazon Bedrock 防护栏进行内容过滤、PII 保护和提示注入检测
### 专家代理
| 代理 | 领域 | 集成 |
|-------|--------|-------------|
| **调度器** | 查询路由和多轮推理 | 委托给专家 |
| **GameLift 专家** | 集群管理、扩缩、优化 | boto3 工具 + 知识库 |
| **EKS 专家** | Kubernetes 集群操作 | EKS MCP 服务器 + 知识库 |
| **成本专家** | 支出分析和预测 | Cost Explorer MCP 服务器 + 知识库 |
## 架构
该解决方案使用 AWS Bedrock AgentCore Runtime 和嵌入式 stdio MCP 服务器。所有 MCP 服务器都在 AgentCore 容器内作为子进程运行 -- 不需要外部基础设施。
### 请求流程
1. 用户通过 ECS Express 上的 Next.js 前端（Fargate + ALB）使用 Amazon Cognito（HTTPOnly cookie 中的 JWT token）进行身份验证
2. 用户通过 Next.js 前端发送自然语言查询
3. 前端使用 SigV4 身份验证通过 AWS SDK 调用 Bedrock AgentCore Runtime
4. AgentCore 将请求路由到调度器代理
5. Amazon Bedrock 防护栏过滤输入以防止提示注入、非主题内容和 PII
6. 调度器分类查询并委派给适当的专家代理
7. 专家查询其 Bedrock 知识库以获取特定领域的上下文（RAG）
8. 专家调用 MCP 服务器（EKS、Cost Explorer）或 boto3 工具（GameLift）以获取实时 AWS 数据
9. 只读 API 调用使用最小权限 IAM 策略对目标 AWS 服务执行
10. 响应通过链式返回给用户
### 技术栈
| 层 | 技术 |
|-------|------------|
| 前端 | Next.js、TypeScript、CopilotKit、AWS SDK v3 |
| 后端 | Python 3.13、Strands Agents、Bedrock AgentCore SDK |
| AI 模型 | Amazon Bedrock（Claude Haiku 4.5 用于调度，Claude Sonnet 4.5 用于专家） |
| MCP 服务器 | AWS Labs MCP 服务器（EKS、CCAPI、Cost Explorer）通过 stdio 传输 |
| 身份验证 | Amazon Cognito，具有基于组的授权 |
| 基础设施 | AWS CloudFormation、ECS Express（Fargate + ALB）、ECR |
| 可观察性 | Amazon CloudWatch、AWS X-Ray、OpenTelemetry |
## 成本
您需要为运行此指南时使用的 AWS 服务付费。截至 2026 年 6 月，在 US East（N. Virginia）区域使用默认设置运行此指南的成本约为每月 **1,129.23 美元**，适用于大约 10,000 次代理查询。
我们建议通过 [AWS Cost Explorer](https://aws.amazon.com/aws-cost-management/aws-cost-explorer/) 创建预算以帮助管理成本。价格可能会发生变化。有关详细信息，请参阅每项 AWS 服务的定价网页。
### 样本成本表
以下表格提供了在 US East（N. Virginia）区域部署此指南的样本成本明细，假设使用默认参数，约 10,000 次代理查询（每次查询调用 Haiku 调度和 Sonnet 专家，并带有 RAG 上下文）。
| AWS 服务 | 维度 | 成本 [USD] |
| ----------- | ------------ | ------------ |
| Amazon Bedrock (Claude Sonnet 4.5) | 8 亿输入令牌 @ $3.30/M + 2000 万输出令牌 @ $16.50/M（专家代理） | $594.00 |
| Amazon OpenSearch Serverless (知识库) | 2 OCUs（索引 + 搜索）@ $0.24/OCU-hour × 730 小时 | $350.40 |
| Amazon Bedrock (Claude Haiku 4.5) | 4,000 万输入令牌 @ $1.10/M + 1000 万输出令牌 @ $5.50/M（调度器） | $99.00 |
| Amazon CloudWatch + AWS X-Ray | 所有组件的日志、指标和分布式跟踪 | $25.00 |
| Elastic Load Balancing (ALB) | 1 ALB @ $0.0225/hour × 730 小时 + ~730 LCU-hours @ $0.008 | $22.27 |
| Amazon ECS (Fargate) | 1 个任务，0.5 vCPU @ $0.04048/hour + 1 GB @ $0.004445/GB-hour × 730 小时 | $18.02 |
| Amazon Bedrock AgentCore Runtime | ~10,000 次调用，~30s 每次：1 vCPU @ $0.0895/hour + 2 GB @ $0.00945/GB-hour | $9.04 |
| AWS WAF | 1 个 WebACL，具有托管规则 + ~100 万请求 | $8.00 |
| AWS CloudTrail | 管理事件（免费）+ 数据事件 | $2.00 |
| Amazon Inspector | 容器镜像扫描（~10 个镜像） | $1.30 |
| Amazon ECR | 镜像存储（~2 GB）@ $0.10/GB-month | $0.20 |
| Amazon Cognito | 1,000 个月活跃用户（免费额度内） | $0.00 |
| **总计** | | **~$1,129.23/月** |
## 前提条件
### 所需工具
| 工具 | 版本 | 安装 |
|------|---------|--------------|
| AWS CLI | v2+ | [安装指南](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) |
| Node.js | 18+ | [下载](https://nodejs.org/) |
| uv | 0.9+ | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| yq | v4+ | [安装指南](https://github.com/mikefarah/yq#install) |
| Docker | 最新（可选） | [安装指南](https://docs.docker.com/get-docker/) |
Python 3.13 和 AgentCore CLI 将在设置过程中由 `uv` 自动安装。Docker 仅在构建和部署前端容器镜像时需要；如果 Docker 不可用，前端部署步骤将被跳过。
### AWS 账户要求
- **Bedrock 模型访问**：在目标区域启用 Claude Sonnet 4.5 和 Claude Haiku 4.5
- **服务配额**：默认配额足以满足大多数部署需求
- **IAM 权限**：初始部署的管理员访问权限（或等效权限）
<details>
<summary><strong>最低 IAM 权限（点击展开）</strong></summary>
如果您无法使用管理员访问权限，则部署主体需要以下权限：
| 服务 | 操作 | 目的 |
|---------|-----------------|---------|
| CloudFormation | 完整的堆栈 CRUD | 部署/更新/删除所有堆栈 |
| IAM | 创建/管理角色和策略 | ECS、AgentCore 等服务角色 |
| Amazon ECR | 仓库 CRUD、镜像推送 | 前端容器注册表 |
| Amazon ECS | 服务/任务管理 | 前端托管 |
| Amazon Cognito | 用户池 CRUD | 身份验证 |
| Amazon Bedrock | 模型访问、防护栏、知识库、AgentCore | AI 代理和安全 |
| Amazon S3 | 桶 CRUD、对象操作 | 知识库存储、CloudTrail 日志 |
| CloudWatch Logs | 日志组 CRUD、交付管理 | 可观察性 |
| AWS X-Ray | 跟踪读取/写入 | 分布式跟踪 |
| AWS CodeBuild | 项目 CRUD、构建执行 | AgentCore Runtime 部署 |
| AWS WAF | WebACL CRUD | 前端保护 |
| AWS CloudTrail | 跟踪 CRUD | API 审计日志 |
| Amazon Inspector | 启用扫描 | 容器漏洞扫描 |
| AWS STS | GetCallerIdentity | 凭证验证 |
CloudFormation 模板使用 `CAPABILITY_NAMED_IAM` 创建具有最小权限访问的范围服务角色。
</details>
要启用 Bedrock 模型：
1. 打开 [Amazon Bedrock 控制台](https://console.aws.amazon.com/bedrock/)
2. 导航到 **模型访问**
3. 启用 Anthropic Claude 4.5 Sonnet 和 Anthropic Claude 4.5 Haiku
4. 保存更改
### Windows 用户
`scripts/powershell/` 目录中的 PowerShell 模块提供原生 Windows 支持。请参阅 [scripts/powershell/README.md](scripts/powershell/README.md) 以了解设置和使用方法。
```powershell
Import-Module ./scripts/powershell/GameAgent.psd1
Deploy-GameAgent -Profile <your-profile> # 完整部署
Remove-GameAgent -Profile <your-profile> # 完整清理
```
**前提条件：** PowerShell 7.0+ 和 AWS CLI v2。不需要 WSL2 或 Linux 环境。
## 部署
### 完整的 AWS 部署
**步骤 1：** 配置和验证 AWS 凭证（单独运行 `aws configure`）：
```bash
aws configure
aws sts get-caller-identity # 验证凭证是否有效
```
**步骤 2：** 创建环境配置并部署：
```bash
# 创建环境配置
cp ui/.env.local.example ui/.env.local
# 部署所有基础设施（8 个自动化步骤）
./deploy-all.sh
# 可选：覆盖 AWS 配置文件（也可以在 ui/.env.local 中设置）
# AWS_PROFILE=<your-profile> ./deploy-all.sh
# 为 Cognito 用户池创建管理员用户
./scripts/infrastructure/add-admin-user.sh
# 对部署的堆栈运行测试
./test-full.sh
```
部署脚本配置以下资源：
1. 基础架构（Cognito 用户池、IAM 角色、ECR 仓库）
2. Bedrock 防护栏（内容过滤、PII 保护）
3. 托管提示（Bedrock 提示管理）
4. 账户级可观察性配置
5. AgentCore Runtime（通过 CodeBuild 的后端容器）
6. Bedrock 知识库（GameLift、EKS、Cost 文档）
7. 前端基础设施（ECS Express + ALB）
8. 安全基础设施（WAF、CloudTrail、Inspector）
有关详细的分步部署说明和环境变量参考，请参阅 [docs/DEPLOYMENT_GUIDE.md](docs/DEPLOYMENT_GUIDE.md)。
## 本地开发
```bash
# 安装后端依赖
cd backend && uv sync && cd ..
# 创建环境配置（如果尚未创建）
cp ui/.env.local.example ui/.env.local
# 启动后端（端口 8080）和前端（端口 3000）
./dev-start.sh
# 访问 UI：http://localhost:3000
# 停止所有服务
./dev-stop.sh
```
在本地开发模式下：
- AgentCore Runtime 在本地运行，带有所有专家代理
- MCP 服务器通过 stdio 传输嵌入式运行
- 前端直接连接到本地后端（默认情况下不进行 Cognito 身份验证）
- AWS 服务访问（GameLift、EKS、Cost Explorer）使用您的本地 AWS 凭证
### 仅后端
```bash
cd backend
uv sync
source .venv/bin/activate
python src/agentcore_main.py
```
### 仅前端
```bash
cd ui
npm install
npm run dev
```
## 使用
应用程序运行时（本地或部署），请通过聊天界面与 AI 助手交互。
### GameLift 管理
```
"显示我的 GameLift 集群"
"我的生产集群表现如何？"
"我的集群使用什么扩缩配置？"
```
### EKS/Kubernetes 操作
```
"列出我的 EKS 集群"
"显示默认命名空间中的失败 Pod"
"我的 game-agones-cluster 状态如何？"
```
### 成本分析
```
"我的当前 AWS 支出是多少？"
"我对 GameLift 和 EKS 的支出是多少？”
“显示我成本优化机会”
```
### 身份验证
- **开发模式**（`NEXT_PUBLIC_SKIP_AUTH=true`）：不需要身份验证（`.env.local 中的默认值）
- **生产模式**（`NEXT_PUBLIC_SKIP_AUTH=false`）：强制执行 Cognito 身份验证；用户必须位于 `admin` 或 `users` 组中
## MCP 集成
所有三个 MCP 服务器都只使用 stdio 传输。它们在 AgentCore Runtime 容器内作为嵌入式子进程运行。
| MCP 服务器 | 目的 | 专家 |
|------------|---------|------------|
| `awslabs.eks-mcp-server` | Kubernetes 集群管理 | EKS 专家 |
| `awslabs.aws-api-mcp-server` | AWS CLI 桥接，用于资源发现（例如 `aws eks list-clusters`） | EKS 专家 |
| `awslabs.cost-explorer-mcp-server` | 成本分析和预测 | 成本专家 |
MCP 客户端通过线程安全工厂 (`utils/mcp_client_factory.py`) 创建，自动重试，当 MCP 服务器不可用时回退到 boto3。
### 注册 EKS 集群
要启用完整的 Kubernetes API 访问（Pod、部署、服务），请注册您的 EKS 集群：
```bash
cd infrastructure/kubernetes
# 基本注册
./enroll-cluster.sh my-cluster us-west-2
# 启用审计日志
./enroll-cluster.sh my-cluster us-west-2 --enable-audit-logs
# 注销集群
./deregister-cluster.sh my-cluster us-west-2
```
注册配置只读 Kubernetes RBAC 并更新 `aws-auth` ConfigMap。密钥明确排除在只读权限之外。
## 测试
该项目包括单元测试、集成测试、端到端测试和 AI 评估测试。
### 快速入门
```bash
# 仅单元测试（不需要部署或运行服务）
./test-unit.sh
# 完整的智能测试套件（自动检测部署状态）
./test-full.sh
```
### 测试类别
| 命令 | 描述 | 需求 |
|---------|-------------|--------------|
| `./test-unit.sh` | 后端 + 前端单元测试 | 无 |
| `./test-local.sh` | 仅单元测试 | 无 |
| `./test-cloud.sh` | 云集成测试 | 已部署的堆栈 |
| `./test-e2e.sh` | 端到端浏览器测试 | 运行服务 |
| `./test-ai-evals.sh` | AI 行为评估 | 已部署的堆栈 |
| `./test-stress.sh` | 性能和负载测试 | 已部署的堆栈 |
| `./test-memory.sh` | 内存子系统测试 | 已部署的堆栈 |
### 后端测试（pytest）
```bash
cd backend
pytest -m unit # 快速单元测试（模拟）
pytest -m integration # 集成测试（真实服务）
pytest -m cloud # 云测试（需要部署）
pytest -m ai_eval # AI 评估测试
```
### 前端测试
```bash
cd ui
npm test # Jest 单元测试
npm run test:coverage # 覆盖率报告
npm run test:e2e # Playwright 端到端测试
npm run test:e2e:smoke # 仅限烟雾测试
```
## 监控和可观察性
该解决方案与 Amazon CloudWatch 和 AWS X-Ray 集成，用于监控和分布式跟踪。
- **CloudWatch 日志**：来自所有组件的结构化 JSON 日志（应用程序日志保留 14 天，审计日志保留 90 天）
- **AWS X-Ray**：跨整个请求流程的分布式跟踪，从前端通过 AgentCore 到 AWS 服务调用
- **OpenTelemetry**：通过 ADOT（AWS Distro for OpenTelemetry）导出跟踪和指标
```bash
# 查看运行时日志
aws logs tail /aws/bedrock-agentcore/runtimes/gameagentruntime-<ID>-DEFAULT --follow
# 查看前端日志
aws logs tail /ecs/game-agent-frontend --follow
```
可在 AWS 控制台的 CloudWatch > Gen AI Observability > AgentCore 下查看 X-Ray 跟踪。
## 项目结构
```
sample-game-backend-agentic-workflows/
├── backend/ # Python AgentCore 运行时后端
│ ├── src/
│ │ ├── agents/ # 调度器和专业代理
│ │ ├── config/ # 配置（settings.py）
│ │ ├── models/ # AI 模型配置
│ │ ├── utils/ # MCP 客户端工厂、日志记录、计时
│ │ └── agentcore_main.py # AgentCore 运行时入口
│ └── tests/ # 单元测试、集成测试和 AI 评估测试
├── ui/ # Next.js 前端
│ ├── src/
│ │ ├── components/ # React 组件（聊天）
│ │ ├── pages/ # Next.js 页面和 API 路由
│ │ └── lib/ # 实用库
│ └── __tests__/ # 前端测试
├── infrastructure/ # CloudFormation 模板和 Kubernetes 脚本
│ ├── cloudformation/ # IaC 部署模板
│ └── kubernetes/ # EKS 集群注册脚本
├── scripts/ # 部署和开发自动化
│ ├── deploy.sh # 主部署逻辑
│ ├── teardown.sh # 主销毁逻辑
│ ├── powershell/ # Windows PowerShell 模块（Deploy-GameAgent 等）
│ ├── dev/ # 开发环境脚本
│ ├── test/ # 测试自动化
│ └── infrastructure/ # 基础设施实用程序
├── docs/ # 附加文档
│ ├── ARCHITECTURE.md # 详细架构文档
│ ├── DEPLOYMENT_GUIDE.md # 分步部署指南
│ ├── SECURITY.md # 安全控制和合规性
│ ├── THREAT_MODEL.md # STRIDE 威胁分析
│ └── DEPENDENCY_MATRIX.md # 依赖版本和固定原理
├── deploy-all.sh # 完整 AWS 部署（包装器）
├── teardown-all.sh # 完整 AWS 销毁（包装器）
├── dev-start.sh # 启动本地开发
├── dev-stop.sh # 停止本地开发
├── test-full.sh # 运行所有测试（自动检测模式）
└── test-unit.sh # 运行单元测试
```
根级 shell 脚本是便捷的包装器，它们将委托给 `scripts/` 中的相应脚本。
## 安全
> **📖 完整文档：** [SECURITY.md](SECURITY.md)（加密、数据保护、信任边界、修补） | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)（STRIDE 威胁分析，带有攻击树）
该解决方案在所有层实施纵深防御安全控制：
| 层 | 控制 |
|-------|----------|
| **身份验证** | Amazon Cognito 与 JWT 令牌、基于组的授权、仅限管理员用户创建 |
| **传输** | 所有连接均强制使用 TLS 1.2+（AWS 托管证书） |
| **加密** | 所有数据（S3、CloudWatch、AgentCore 内存）静止时均使用 AES-256 加密 |
| **授权** | IAM 最小权限策略，具备对目标服务的只读访问权限 |
| **AI 安全** | Amazon Bedrock Guardrails，用于内容过滤、PII 匿名化和提示注入检测 |
| **输入验证** | 提示净化、注入模式检测、敏感数据编辑（[utils/security.py](backend/src/utils/security.py)） |
| **审计** | CloudTrail 日志记录所有 AWS API 调用，CloudWatch 记录应用程序活动 |
| **漏洞扫描** | AWS Inspector 扫描容器镜像，Dependabot 用于依赖项更新 |
| **无静态凭证** | 所有服务到服务身份验证均使用 IAM 角色，自动轮换凭证 |
## 清理
要删除所有已部署的资源：
```bash
AWS_PROFILE=<your-profile> ./teardown-all.sh
```
销毁脚本是幂等的，并按部署顺序逆序删除资源。
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)，了解有关报告错误、建议功能和提交拉取请求的指南。
## 许可证
此库在 MIT-0 许可证下获得许可。请参阅 [LICENSE](LICENSE) 文件。
## 通知
客户负责对本指南中的信息进行独立评估。本指南：（a）仅用于信息目的；（b）代表 AWS 当前的产品提供和实践内容，这些内容可能会有所变更，不予通知；（c）不创建 AWS 及其关联公司、供应商或许可方的任何承诺或保证。AWS 产品或服务按“原样”提供，不附带任何明示或暗示的保证、声明或条件。AWS 对客户的责任和义务受 AWS 协议的约束，本指南不属于任何 AWS 与其客户之间的协议的一部分，也不会修改任何该等协议。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器