myattj/agentcore-sre-reference

# Agent：基于 AWS Bedrock AgentCore 的多租户 AI SRE [](https://github.com/myattj/agentcore-sre-reference/actions/workflows/ci-cd.yml) [](./LICENSE) **一个已归档的、基于 AWS Bedrock AgentCore 的面向 Slack 的多租户 AI SRE 参考实现。** Agent 诞生于一个简单的设想：如果 Slack 中的告警能直接变成调查、建议的修复方案以及团队事后分享的产出物，会怎样？ 大多数事件处理机器人止步于总结。Agent 的设计旨在将这一线索进一步延伸： 1. 告警出现在 Slack 中。 2. Agent 组装特定租户的上下文、频道历史、记忆和操作手册。 3. AgentCore Gateway 工具从可观测性和运营系统中提取证据。 4. GitHub 工具将症状与代码、提交和最近的部署进行关联。 5. 一次性的 Fargate 沙箱可以在隔离的分支上工作并创建 Pull Request。 6. Agent 可以将结果转化为短暂的交互式仪表板，并将链接发回到会话中。 这一完整的闭环——**告警 → 证据 → 代码 → 变更 → 共识**——是本项目的创意核心。  ## 架构 Agent 特意将传输层与推理层分离。Bridge 负责处理 Slack 交互和快速响应；而 Agent 负责管理工具、记忆、调查和执行操作。 ``` flowchart LR Slack["Slack alert, question, or incident thread"] --> Bridge["Bridge
FastAPI, OAuth, tenant resolution, async replies"] Bridge --> Runtime["AgentCore Runtime
Strands agent"] Runtime --> Bridge Bridge --> Slack Config["DynamoDB
tenant config, audit, spend, jobs"] <--> Runtime Memory["AgentCore Memory
tenant and channel namespaces"] <--> Runtime Runtime <--> Gateway["AgentCore Gateway
observability, docs, ticketing, BYO tools"] Runtime <--> GitHub["GitHub App
code search, files, symbols, commits"] Runtime --> Sandbox["One-shot Fargate sandbox
isolated branch, agent loop, pull request"] Runtime --> Dashboard["Ephemeral dashboard spec
charts, tables, stats, text"] Dashboard --> Web["Next.js renderer
unguessable bearer URL, 7-day TTL"] ``` 运行时在每次调用时都会重新加载全新的 TenantConfig。租户可以自行选择其模型、人格设定、目录工具、Gateway 集成、记忆行为、频道人格、技能、升级路由、成本上限以及已连接的代码库，而无需更改共享的 Agent 部署。 ## 目录说明 这是一个参考代码库，并不意味着每个子系统都已经同样成熟。 | 能力 | 本仓库中的状态 | 重要限制 | |---|---|---| | Slack 传输、OAuth、签名检查、重试去重、异步回复路径 | 已实现，并由 bridge 测试覆盖 | 您必须创建并配置自己的 Slack 应用 | | 基于租户的提示词、工具、频道人格、技能、升级路由、成本上限、审计 | 已实现 | 隔离性通过共享 AWS 资源上的应用程序代码实现；请针对您的威胁模型进行审查 | | AgentCore Runtime 和 Memory 集成 | 已实现 | 需要您自己的 AWS 账户、模型访问权限、IAM 以及 Memory 预配 | | AgentCore Gateway 集成 | 作为连接器和预配模式实现 | 共享 Gateway 的工具元数据不是租户私有的；如果目标名称或 schema 敏感，请使用基于租户的独立 Gateway | | 事件/操作手册/轮班/部署技能 | 作为内置的提示词驱动工作流实现 | 输出质量取决于所连接的数据和选定的模型 | | GitHub 代码与提交关联 | 通过 GitHub App 实现 | 需要安装权限、谨慎的代码库范围限定，以及经操作员批准的安装到租户的绑定 | | 自主 PR 沙箱 | 实验性参考；默认禁用 | 当前 worker 会将任务内凭证暴露给模型生成的 shell 命令。在重新设计信任边界期间，请仅在配合可丢弃凭证时使用；参见沙箱警告 | | 短暂的交互式仪表板 | 实验性参考实现 | 链接即持有者凭证：在 7 天到期前，任何拥有该 URL 的人都可以查看 | | 新手引导、工作区设置和操作员视图 | 已实现的参考 UI | 身份验证和 RBAC 尚非完善的多用户产品 | | Discord/Teams 传输、计费、市场、持久化仪表板 | 未实现 | 这些仍是设计方向，而非隐藏功能 | 本归档不包含任何公开的 Agent endpoint 或云环境。 ## 为什么它可能有用 有趣且可复用的模式其实超越了这款特定产品本身： - 一个轻量级的、仅负责传输的 Slack bridge，能在 Slack 的期限内完成响应，并异步分发 Agent 任务。 - 一个共享的运行时，其行为在每次调用时均由租户配置动态生成。 - 租户白名单内的进程内工具，以及位于 AgentCore Gateway 背后的客户特定工具。 - 感知频道的上下文组装、记忆 namespace、操作手册触发器、升级路由，以及 bot 与 bot 之间的策略。 - 代码调查和长期运行的写入操作跨越信任边界进行分离。 - 针对后台任务的健康/忙碌生命周期追踪。 - 专为“即使可观测性失效也不会中断用户请求路径”而设计的审计和消费记录。 - 可转化为临时交互式产出物的会话原生输出。 ## 本地试用 — 无需云账户 体验 Agent 最有趣部分的捷径只需三条命令： ``` make doctor make setup make demo ``` 打开输出的 URL，即可看到由真实的 FastAPI bridge 和 Next.js 渲染器支撑的、贴近现实的调查仪表板。该示例讲述了一个微型的事件故事——延迟飙升、相关的缓存崩溃、证据追踪以及建议的缓解措施——且不需要您提供 AWS 凭证、AgentCore、Bedrock、Slack、Docker 或 API key。按下 Ctrl+C 即可干净地停止这两个进程。 make setup 会根据已提交的 lockfile 安装所有四个独立的 Python 环境以及所有三个 Node 环境。它还会根据被追踪的示例文件创建 bridge/.env.local 和 onboarding/.env.local，为它们赋予相同的密码学随机本地会话密钥，并将其权限模式设置为 0600。现有的环境变量文件绝不会被覆盖；如果它们的密钥不一致，安装程序将会停止运行并提示修复方法，而不是进行盲目猜测。 您需要 Git、Python **3.13**、[uv](https://docs.astral.sh/uv/)、Node.js **22+** 以及 npm。make doctor 会逐一检查这些工具，区分必需工具和可选的云端工具套件，并针对任何缺失的内容打印出确切的安装路径。下面列出的四个开发者入口程序均支持 --help，并兼容当前 macOS 和主流 Linux 发行版自带的 Bash 版本。 Make 仅是一个为了方便而提供的包装器：如果未安装它，您可以直接运行对应的 ./scripts/doctor.sh、./scripts/setup.sh、./scripts/demo.sh 或 ./scripts/check.sh 入口脚本。 为了验证该演示能在不打开浏览器的情况下启动并正常关闭： ``` scripts/demo.sh --check ``` ## 验证仓库 在执行 make setup 后，只需一条命令即可运行等同于 CI 门控的本地检查：服务和合成事件的 Python 测试套件、沙箱测试、新手引导身份验证测试及生产环境构建、生成的 CDK 测试与格式化、每一个手工编写的 CDK synth 变体、shell/工具测试、可选的本地 gitleaks 扫描，以及无云环境的服务启动检查。 ``` make check ``` 为了实现更快的编辑循环，scripts/check.sh --quick 会跳过 CDK synth 和实时演示的启动。这两条命令均不会部署资源，也不会调用 AWS、Slack 或 GitHub API。该检查同样适用于不含 Git 索引的 GitHub 源码归档：生成的本地环境变量文件、依赖项和构建输出都会被排除在仅针对源代码的密钥扫描之外。 ## 完整 AgentCore 路径的前置条件 若要运行 AgentCore 闭环或进行 AWS 部署： - [Amazon Bedrock AgentCore CLI](https://github.com/aws/agentcore-cli)，使用 npm install -g @aws/agentcore@0.24.1 安装 - AWS CLI v2 以及您自己账户的凭证 - AWS CDK v2 - 在您选定区域中拥有兼容 Bedrock 模型的访问权限 - 如果您想测试真实的传输层，则需要一个 Slack 应用 AWS 身份验证使用标准的 AWS CLI/SDK 凭证链，包括命名的 profile、SSO 会话、环境凭证以及工作负载角色。所选定的单一区域将贯穿 AgentCore、CDK、bridge、部署脚本以及手动的 GitHub Actions 发布作业。示例和无需凭证的 synth 的默认回退区域是 us-west-2。 这并不意味着每个 AWS 分区和区域都具有相同的服务集。完整的 CLI 驱动发布路径支持被固定 AgentCore CLI 接受的九个区域中的任何商业 AWS 账户，前提是 Runtime、所选的 Bedrock 模型、Gateway、Memory 及其他已启用的功能在该区域可用。确切的发布白名单记录在 [scripts/agentcore_cli_regions.txt](./scripts/agentcore_cli_regions.txt) 中，并与签入本仓库的 CLI schema 保持同步。 这九个区域的列表是工具的边界，而非完整的 AgentCore 服务目录。AgentCore Runtime 可在其他商业区域和 GovCloud 中使用。因此，bridge、runtime 解析器和手工编写的 CDK 验证可以附加到现有的 Runtime，或者在更广泛的商业区和 GovCloud 分区中合成基础设施。make aws-configure 和 make agent-deploy 在被固定的 CLI 支持的九个区域之外仍会拒绝执行。GovCloud 必须替换或禁用默认的全局 Bedrock 模型和可选的 AgentCore 功能。不支持 AWS 中国、隔离区和其他主权分区。在花费资金之前，请查阅当前的 [AgentCore 区域矩阵](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html)。选择区域本身并不能保证隐私或合规性。 ## 完整的本地 AgentCore 闭环 本地模式使用 examples/ 中的 JSON 固定数据来提供租户数据和工作区映射。这两个本地标志故意使用了不同的名称： - Agent：AGENT_LOCAL_STORES=1 - Bridge：LOCAL_DEV=1 AgentCore CLI 在内部保留了 LOCAL_DEV 关键字，因此如果将其用作 Agent 的存储标志，会导致令人困惑的行为。 请首先运行 make setup。各服务目录依然拥有独立的环境；请勿从 Agent 中导入 bridge 包，反之亦然。 AgentCore 需要一个被忽略的、特定于开发者的部署目标文件。请勿将账户 ID 编辑进被追踪的配置中。选择您用于开发的同一个 profile 和区域，验证实时的 STS 身份和 AgentCore 控制平面，然后根据该身份生成目标文件： ``` export AWS_PROFILE=my-sandbox-profile # omit for the default credential chain export AWS_REGION=eu-west-1 make aws-doctor make aws-configure ``` make aws-doctor 是只读的。make aws-configure 仅写入 coreAgent/agentcore/aws-targets.json，权限模式为 0600。除非您明确传入 AWS_CONFIGURE_ARGS="--force"，否则它将拒绝替换为不同的账户或区域。该脚本还会报告所选的账户/区域是否已进行 CDK 引导。 AWS CLI 调用默认在 30 秒后超时；如果 SSO 或凭证助手需要不同的限制，请设置 AGENTCORE_AWS_CLI_TIMEOUT_SECONDS。 预检会在联系 STS 或写入目标文件之前，拒绝被固定的 CLI 发布白名单之外的区域。 然后从仓库根目录启动三个终端： ``` # Terminal 1 — agent 在 :8080 cd coreAgent AGENT_LOCAL_STORES=1 agentcore dev --logs ``` ``` # Terminal 2 — bridge 在 :8000 cd bridge # make setup 已创建 .env.local，包含 local routing + shared secret。 uv run uvicorn bridge.main:app --reload --port 8000 --env-file .env.local ``` ``` # Terminal 3 — Next.js UI 在 :3000 cd onboarding # make setup 已创建 .env.local，包含 shared local secret。 npm run dev ``` 在 bridge 处于 LOCAL_DEV=1 模式时，其调试传输通道将被启用： ``` curl -X POST http://localhost:8000/debug/message \ -H 'Content-Type: application/json' \ -d '{"workspace_id":"demo-ws","user_id":"u1","text":"Investigate the latest alert"}' ``` 最后的请求会调用模型，因此需要有效的 AWS 凭证和 Bedrock 访问权限。如果要在不启动浏览器的情况下进行冒烟测试（该测试会启动所有三个服务，但会跳过实时的 Bedrock 请求）： ``` scripts/smoke.sh --no-agent ``` 冒烟测试套件依然需要 AgentCore CLI。它会临时更新本地固定数据，并在退出时恢复它们。如需体验完全无云、仅包含两个服务的流程，请改用 make demo。 ## 合成事件实验室 本仓库提供了两种利用合成数据来探索该想法的方法： - [seed/](./seed/README.md) 在 Datadog 指标和 Slack 会话中创建一个聚焦于 N+1 查询问题的微型事件。 - [scripts/testenv/](./scripts/testenv/README.md) 构建一个更大、持久化的 Acme 风格租户，包含频道、历史记录、操作手册、代码库以及可重复的告警场景。 这两个实验室都会写入外部系统。请使用可丢弃的工作区、账户、代码库以及受限的凭证。在运行脚本之前请进行检查；较大的测试环境在意图上比单元测试数据更接近真实的部署环境。 ## 部署参考技术栈 这里不存在一条绝对安全的“部署一切”的命令。真实的部署会跨越多个安全和计费边界： 1. 审查并合成 [infra/data/](./infra/data/README.md) 中的共享数据和 IAM 技术栈。 2. 从 [coreAgent/](./coreAgent/README.md) 配置并部署 AgentCore 运行时；运行时源位于 [coreAgent/app/coreAgent/](./coreAgent/app/coreAgent/)。 3. 根据 [bridge/slack_manifest.json](./bridge/slack_manifest.json) 创建您自己的 Slack 应用，然后配置 OAuth、签名、重定向和事件 URL。设置 CERTIFICATE_ARN 和 DOMAIN_NAME；如果没有它们，生产环境工作流将拒绝部署。通过该单一的 HTTPS 公共源路由 bridge 回调和新手引导 UI，以便使作用于特定主机的 HttpOnly 新手引导 cookie 能够在重定向后继续保留，同时避免将 Bearer Token 放入 URL 中。 4. 如果您启用了 GitHub App 代码访问权限，请通过特权审批 endpoint 显式地将每个数字安装 ID 绑定到预期的租户。租户会话无法创建或更改 codebases.github_installation_id。 5. 仅为您打算暴露的集成预配 Gateway 目标和凭证。 6. 将 [infra/sandbox/](./infra/sandbox/) 中的 Fargate PR 沙箱视为恶意的代码执行环境，并在启用 propose_pr 之前对其进行强化。 7. 如果您启用了仪表板，请设置 DOMAIN_NAME；部署包装器会将其 HTTPS 源作为运行时的 DASHBOARD_BASE_URL 注入。 对于 GitHub Actions 部署，请将仓库变量 AWS_REGION 设置为与配置的 OIDC 角色及所有区域性 ARN 相同的区域。默认值为 us-west-2。工作流会拒绝来自不同账户、分区或区域的运行时 ARN，并且 CDK 会在合成前验证提供的 AgentCore、ACM、ECS 和 Secrets Manager ARN。 由于 [AWS 控制平面 API](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_GetAgentRuntime.html) 和 [运行时开发者指南](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-security-best-practices.html) 目前同时包含带版本的 agent/<uuid>:<version> 和旧版 runtime/<id> AgentCore ARN 资源，因此发现和验证过程会接受这两种形式，但依然要求其具有实时的控制平面 ID 和版本。 签入的辅助程序会执行 GitHub 账户检查和独占的租户绑定，且不会将操作员密钥放在命令行中： ``` read -rsp 'Operator secret: ' ADMIN_SECRET printf '\n' export ADMIN_SECRET python3.13 scripts/approve_github_installation.py \ tenant-id 123456 expected-github-owner \ --bridge-url https://agent.example.com unset ADMIN_SECRET ``` 默认情况下，Agent 端的 manage_config 写入也是只读的，因为 admin_user_ids 初始为空。如果您有意启用它们，请通过经过审查的操作员工具或直接在租户的 DynamoDB 配置中添加确切的 Slack 用户 ID（而不是通过租户的 PATCH API），并且像对待其他任何特权授予操作一样审计此更改。 ### 成本与清理 部署此架构可能会产生计费用的 AgentCore、Bedrock、Gateway、ECS/Fargate、负载均衡器、CloudWatch、Secrets Manager、ECR 和 DynamoDB 用量。模型调用和沙箱运行会产生额外的可变成本。 某些 DynamoDB 资源使用了保留策略。销毁 CDK 技术栈可能有意留下数据，因此在清理时，请同时验证 CloudFormation 状态和底层资源。在使用真实流量进行测试之前，请设置 AWS Budgets 和服务级别的上限。 ### 需要重新审查的安全边界 在任何生产环境使用之前： - 替换所有示例密钥，并轮换开发期间使用过的任何凭证。 - 将密钥保留在专用的密钥管理器中；切勿提交 .env 文件、Slack token、API key、GitHub key 或部署状态。 - 验证 Slack 签名，并在 LOCAL_DEV=1 之外的环境中保持调试路由禁用。 - 将 bridge 的 OAuth 回调和新手引导保持在同一个 HTTPS 公共源上；切勿将新手引导会话 token 放入 URL 中。 - 针对 DynamoDB、Gateway、Slack、记忆、仪表板和 GitHub 的每一次访问路径，重新审查租户授权。 - 将每个 GitHub App 安装 ID 视为经过操作员批准的租户绑定，而不是租户可编辑的设置。 - 将 IAM 策略和 GitHub App 权限收窄至每个组件实际需要的资源范围。 - 在模型生成的代码变更周围增加明确的人工审批和更强的隔离性。 - 请勿将敏感数据放入短暂的仪表板中；它们的 URL 即是持有者凭证。 - 审查 [SECURITY.md](./SECURITY.md) 并运行您自己的威胁模型。 ## 仓库结构映射 ``` . ├── bridge/ Slack/OAuth transport and AgentCore client ├── coreAgent/ │ ├── agentcore/ AgentCore CLI configuration │ └── app/coreAgent/ Strands runtime, tools, memory, tenant config ├── onboarding/ Next.js onboarding, workspace, ops, dashboards ├── workers/gateway_interceptor/ Gateway JWT and tenant-isolation interceptor ├── infra/ │ ├── data/ Hand-authored CDK: data, services, Gateway, IAM │ └── sandbox/ One-shot agentic PR worker + frozen Python lock ├── examples/ Local tenant and workspace fixtures ├── seed/ Focused synthetic incident generator └── scripts/testenv/ Persistent integration-testing lab ``` 权威的租户 schema 是 coreAgent/app/coreAgent/tenant.py。它的 API 和 UI 镜像位于 bridge 和新手引导包中；对这些内容的更改必须保持同步。 ## 项目状态 Agent 已被归档。Issue 和 Pull Request 可能对未来读者有用，但我们不提供路线图、托管服务、支持 SLA，也不承诺进行依赖项更新。 - 阅读 [NORTH_STAR.md](./NORTH_STAR.md) 了解归档的产品理念。 - 浏览组件指南以了解 [bridge](./bridge/README.md)、[核心 agent](./coreAgent/README.md)、[新手引导 UI](./onboarding/README.md)、[AWS 基础设施](./infra/data/README.md) 和 [PR 沙箱](./infra/sandbox/README.md)。 - 在提出变更建议之前，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 - 阅读 [SUPPORT.md](./SUPPORT.md) 了解此归档的支持边界。 - 通过 [SECURITY.md](./SECURITY.md) 报告漏洞。 - 审查 [CHANGELOG.md](./CHANGELOG.md) 了解开源归档的快照。 基于 [MIT License](./LICENSE) 发布。

标签：AI SRE, AWS Bedrock, Slack 机器人, 自动化运维