Automating agentic AI Well-Architected reviews with the AWS Agentic AI Lens

使用 AWS Agentic AI Lens 自动化智能代理 AI 架构审查 | AWS 架构博客

使用 AWS Agentic AI Lens 自动化智能代理 AI 架构审查

在受监管的行业中，"快速行动、不惜一切代价"的策略没有容身之地，尤其是在 AI 代理处理敏感客户通信数据时。在本文中，我们将展示 Smarsh（一家领先的通信情报归档和合规平台）如何使用 AWS 架构审查框架的智能代理 AI 透镜，对其首个智能代理工作负载进行了严谨的、基于证据的审查。智能代理 AI 透镜今天以指导性建议的形式提供，但目前还无法在 AWS 架构审查框架中作为独立的透镜进行选择。

为实现审查的自动化，Smarsh 为 Claude（Anthropic 的 AI 助手）构建了一个自定义技能。该技能根据透镜中的所有 150 项最佳实践对工作负载进行评估，直接从工作负载的 GitHub 仓库中提取证据，并在数小时内而非数天内生成一份全面的审查工作簿。在本文中，我们将逐步介绍该技能的架构、评估方法、团队如何验证该技能本身，以及最终的发现结果如何加强了 Smarsh 与其 AWS 账户团队的协作。

关于 Smarsh

Smarsh 是电子通信归档和数字通信治理领域的全球公认领导者。这家跨国 SaaS 公司在过去 20 多年里，帮助全球 7000 多家组织（从小型企业到大型跨国金融机构）大规模地捕获、保留、监控和分析跨 100 多个渠道（包括电子邮件、移动设备、语音、视频、聊天和 AI 助手）的通信数据。该公司的企业归档业务运行在亚马逊 Web 服务（AWS）上，其下一代 AI 能力正在基于亚马逊 Bedrock AgentCore 构建——这是一个用于大规模构建、连接和优化代理的平台，支持任何框架或模型。Smarsh 使用 AgentCore 的运行时、网关、注册表和身份功能来驱动这些解决方案。作为 2025 年 AWS 年度合作伙伴奖的获奖者，Smarsh 与 AWS 拥有深度合作关系。

先决条件

要跟随本文所述方法进行操作，您需要以下条件：

• 具有访问 Amazon Bedrock 和 Amazon Bedrock AgentCore 的 AWS 账户。

• 熟悉 AWS 架构审查框架及其透镜模型。

• 包含您的智能代理工作负载源代码、基础设施定义和文档的 GitHub 仓库。

• 具备安装自定义技能能力的 Claude（Anthropic 的 AI 助手）访问权限。

挑战：一个可以阅读但无法运行的透镜

Smarsh 运营在高度受监管的行业中，合规性和安全性至关重要。每个智能代理解决方案在到达终端客户之前都必须通过架构审查。因此，当一位 Smarsh 架构师开始审查公司首个多代理工作负载时，自然的选择是使用 AWS 架构审查框架的智能代理 AI 透镜。该工作负载是一个基于亚马逊 Bedrock AgentCore 的运行时、网关、注册表和身份功能构建的智能代理审查系统，用于合规警报。

Serverless Applications Lens 和其他镜像可以直接在 AWS Well-Architected Tool 中添加。相比之下，Agentic AI 镜像此前仅以发布文档的形式存在：涵盖 41 个问题和六个支柱的 150 项最佳实践，每项都有风险等级和期望结果，但无法在控制台原生运行审查。这导致出现两个明显选择：要么投入数天时间进行人工审查（每位审查者采用不同评估方式），要么等待控制台支持。Smarsh 选择了第三种方案：以一种未来所有工作负载都能复用的方式，使该镜像可执行。

解决方案架构：将镜像作为数据，将审查者作为技能

Smarsh 将审查流程封装为 Claude 技能：一个包含指令、参考数据和可执行脚本的版本化捆绑包，Claude 通过前置元数据描述发现该技能并按需加载。渐进式披露机制确保在实际请求审查前，令牌成本接近零。该技能包含三个组件：

• lens_data.json – 从已发布镜像文档中提取的全部 150 项最佳实践，以结构化 JSON 数据集形式存储：最佳实践 ID、支柱、审查问题、标题、风险等级（90 项高风险，59 项中风险，1 项低风险）和期望结果。风险等级通过与镜像附录交叉验证来捕获提取错误。该数据集是唯一事实来源，技能被明确指示不得虚构或重新编号条目。

• assessment-guide.md – 五级状态评估标准（合规、部分合规、不合规、不适用、未审查）、证据收集清单、各支柱需关注的信号，以及一套诚实规则。清单涵盖 README 和架构文档、决策记录、基础设施即代码、持续集成与持续交付（CI/CD）工作流、测试与评估套件。每个状态必须引用仓库中的证据，无信号条目标记为“未审查”而非猜测，相同事实在各支柱中必须产生一致状态。

• build_report.py – 一个确定性 Python 脚本（使用 openpyxl 库），将模型评估结果渲染为格式化工作簿。生成器会验证输入，未知的最佳实践 ID 或无效状态将中止构建，幻觉生成的条目无法静默发布。输出包含带数据验证下拉菜单和条件格式的单项状态，同时提供引用证据、差距分析和修复建议列，以及包含实时 COUNTIF 公式的汇总表（支柱统计和高风险暴露追踪）而非硬编码数字。

推理与渲染之间的评估契约通过单一 JSON 文档定义：

{
  "AGENTSEC08-BP01": {
    "status": "Partially Compliant",
    "evidence": "Two-stage input validation (JSON Schema + Pydantic); 5 MB payload cap; typed prompts.",
    "gap": "No prompt-injection screening on message content.",
    "remediation": "Add injection screening; treat communication text as untrusted data in prompts."
  }
}

运行审查只需一行指令：将 Claude 指向一个仓库并请求 Well-Architected 审查。从此时起，技能将驱动以下工作流：

• Claude 加载技能并读取前置元数据描述，以理解审查范围和方法论。

• 技能提取包含六个支柱下全部 150 项最佳实践的 lens_data.json 数据集。

• Claude 仅从目标仓库中读取证据：README 文件、架构文档、基础设施即代码、CI/CD 工作流程和测试套件。

• 该技能根据评估指南（assessment-guide.md）中的五级评分标准和诚实规则，对收集到的证据进行所有 150 项的评估。

• Claude 调用 build_report.py 生成格式化的工作簿，验证行数并标记空白状态。

• 该技能返回高风险差距的高管摘要。

• 人工审核员验证发现的问题，建立修复待办事项清单，并提出开放系统问题以进行针对性的 AWS 深度分析。

图1：从已发布的镜片文档到基于证据的审查工作簿

测试测试者：在信任之前评估技能

Smarsh 在依赖其输出之前评估了该技能。团队构建了两个合成测试仓库：一个中等成熟度的 LangGraph 风格工作负载，以及一个故意粗糙的概念验证，包含硬编码凭证和历史中的失控成本事件。团队在有和没有该技能的情况下分别进行了审查。每次运行都根据每个测试用例的八个可验证预期进行评分：所有 150 项镜片指标均存在、无空白状态、每个明确状态均有证据引用、诚实校准，以及特定于测试用例的发现（如硬编码凭证被标记）。使用该技能时，运行符合 16 个预期中的 16 个。没有使用该技能的基线运行仅符合 8 个预期，生成了 18-39 项的临时检查清单，且没有镜片可追溯性。评估集内置于技能中，因此随着技能的演进，回归测试将持续进行。

首次审查发现的问题

针对真实工作负载，该技能读取了仓库的架构和认证文档、AWS 云开发工具包（AWS CDK）基础设施定义、GitHub Actions 工作流程、注册表和网关设计记录以及测试套件。该技能随后在数小时内评估了所有 150 项指标。工作簿显示了可信的优劣势混合情况。优势包括每个代理的 AWS 身份和访问管理（IAM）执行角色限定到命名运行时 Amazon 资源名称（ARN），以及通过 AgentCore 网关的 SigV4 签名模型上下文协议（MCP）调用，这是 Amazon Bedrock AgentCore 的一项功能。工作簿还记录了经过模式验证的输入、带类型错误契约的导出决策审计跟踪，以及通过 AgentCore 在线评估实现的持续质量监控。高风险差距包括网关入口授权器在已记录的风险接受下禁用认证运行、对恶意行为者影响的消息内容未进行提示注入筛查、速率限制被标记为 TODO，以及无自动化成本控制。每个差距均与镜片条目、证据和推荐的修复措施相关联。

随后，Smarsh 架构师召集了工程团队。他们共同对发现的问题进行分类，将团队已知的信息与工作簿中的状态进行验证，直接在工作簿中接受或挑战结果，并对修复待办事项进行排序。工程团队的反馈重塑了审查：多个条目合并为一个异常检测史诗，当团队指出仓库遗漏的证据后，一个发现被升级。依赖项扫描已经在每个拉取请求上运行。

为什么选择 AWS

Amazon Bedrock 和 Amazon Bedrock AgentCore 在运行时、网关、注册表、身份和评估能力方面的安全性和合规性，符合 Smarsh 受监管客户所期望的标准。AWS Well-Architected Framework 已经是 Smarsh 评估工作负载的基础。通过已发布的视角将该框架扩展到代理 AI 领域，并结合 AWS 解决方案架构师的专业知识进行自动化审查，以弥补关键差距，这是两个团队协作的自然延续。

结果与预期成果

这些数据反映了 Smarsh 的首次内部使用情况以及团队正在追踪的成果。

• 审查工作量 – 通过小时而非多日手动操作完成包含 150 项并附有证据的完整草案，人工时间重新聚焦于验证和优先级排序。
• 可比审查 – 每个工作负载生成相同的标准化工作簿，Smarsh 期望将其转化为更快的安全审批和更短的代理解决方案上市时间。
• 更精准地使用 AWS 专业知识 – 与广泛讨论不同，AWS 合作变为针对具体最佳实践差距的条目化工作会。

下一步计划

• 在公司内部发布该工具作为 Smarsh 代理工作负载的标准评估工具。该工具已提交至公司内部 AI-SDLC 插件市场，并已对第二个架构不同的代理仓库运行过评估。
• 将审查流程嵌入软件开发生命周期，使架构良好的检查在开发过程中持续运行，而非仅作为最终阶段的一次性关卡。
• 通过将审查工作簿作为 Smarsh 项目里程碑和关卡流程中的必要证据，强化治理，确保代理工作负载进入生产环境前完成审查。
• 将视角作为数据的模式扩展到其他 AWS Well-Architected 视角和更多仓库，最终覆盖更广泛的应用组合。

结论

Smarsh 遇到的差距——即规范性指导的发布速度超过控制台工具的吸收速度——是许多客户在代理 AI 最佳实践演进过程中将面临的共同挑战。答案具有普遍性：将视角视为数据，将审查者的专业能力编码为带有强制诚实规则的技能，通过自身的评估套件验证工具，保持人类在判断环节的主导地位，并让发现结果驱动与 AWS 的精准对话。曾经需要数天手动操作的审查，现在已成为整个组织可在代理工作负载接触受监管客户之前重复运行的可复用能力。

要开始使用：

• 了解 AWS Well-Architected Framework 和 Agentic AI Lens 文档。

• 请参阅Amazon Bedrock AgentCore文档，了解如何构建自主代理工作负载。

• 请联系您的AWS账户团队，安排对您自身自主代理工作负载的Well-Architected架构审查。

我们很想了解您是如何针对自身自主代理工作负载开展Well-Architected架构审查的。欢迎在评论区分享您的经验，或联系您的AWS账户团队立即开始。

About the authors

'"`