bedrock-agentcore-policy

用途

AgentCore Policy 用于为智能体定义确定性的行为边界，替代或补充提示工程中概率性的约束方式。用户可以用自然语言编写策略，系统会自动将其转换为 Cedar——AWS 的开源策略语言——并在 Gateway 层进行实时强制执行。

其核心目的：用确定性、可审计的规则定义智能体可以做什么、不可以做什么。

关键原则（据称由 AWS 于 2025 年 12 月验证）包括：自然语言编写；自动生成有效 Cedar；Gateway 拦截每次工具调用进行实时执行；自动推理以检测过宽或过严的规则；默认拒绝（没有 permit 策略即自动拒绝）；forbid 始终覆盖 permit。

质量目标方面，资料列出：策略生成小于 5 秒；每次工具调用强制执行延迟小于 10 毫秒；对工具 schema 的校验覆盖率达到 100%。

何时使用

为智能体设定可执行操作的边界
实现基于角色的访问控制（RBAC）
执行合规规则（例如退款金额上限）
临时禁用有问题的工具
要求操作必须携带特定参数
审计智能体行为

何时不应使用

内容过滤（应使用 Bedrock Guardrails）
限流（应使用 API Gateway）
业务逻辑（应在工具中实现）

前置条件

必需：已配置 AgentCore Gateway；工具已注册为 Gateway 目标；具备策略操作所需的 IAM 权限。

建议：了解 Cedar 语义；已记录工具 schema；已定义测试场景。

主要能力与操作方式

资料将其描述为基于任务（5 个操作）的模式。

操作 1：自然语言策略编写

从纯英文描述创建策略。示例需求包括：允许所有用户读取保单详情与理赔状态；仅允许具有 'senior-adjuster' 角色的用户更新承保范围；除非提供描述，否则阻止所有理赔提交。

使用 boto3 的 bedrock-agentcore-control 客户端调用 start_policy_generation，传入 gatewayId、naturalLanguagePolicy 与 policyName，获得 policyGenerationId；通过 waiter PolicyGenerationCompleted 等待完成；再用 get_policy_generation 取得 generatedPolicy 与 validationResults。

生成的 Cedar 示例包括：对 InsuranceAPI__get_policy 与 InsuranceAPI__get_claim_status 的 permit；仅当 principal 具有 role 标签且等于 senior-adjuster 时对 InsuranceAPI__update_coverage 的 permit；以及除非 context.input has description 否则对 InsuranceAPI__file_claim 的 forbid。

操作 2：直接用 Cedar 创建策略

可完全控制地编写 Cedar。基础 permit 结构为 permit(principal, action == AgentCore::Action::"ToolName__method", resource == AgentCore::Gateway::"arn:...")；可加条件，例如 principal is AgentCore::OAuthUser 且 context.input.amount < 1000；也可用 forbid 配合 unless，例如除非 principal 具有 admin 角色标签，否则禁止删除记录。

通过 create_policy 创建，传入 name、description 与 policyContent，返回 policyId。资料给出的示例为退款上限策略：非经理金额小于 1000 时 permit，经理角色则 permit。

操作 3：常见策略模式

资料列出六种模式：

基于角色的访问控制（RBAC）：仅 admin 角色可执行删除用户、修改权限等操作。
OAuth scope 校验：要求 principal 为 OAuth 用户且 scope 标签匹配如 *customer:read*。
参数约束：例如转账金额小于等于 10000 才 permit。
多条件 AND 逻辑：例如承保类型必须为 liability 或 collision 且同时提供新额度。
禁用特定工具：直接 forbid 某工具方法。
用户特定权限：仅当用户名标签为 trusted-user 时 permit。

操作 4：策略引擎配置

创建策略引擎：调用 create_policy_engine，传入 name、description、gatewayId，获得 policyEngineId；用 waiter PolicyEngineActive 等待激活；再通过 update_policy_engine 传入 policyIds 列表附加策略。

测试强制执行：用 bedrock-agentcore 客户端调用 invoke_agent_runtime，传入 agentRuntimeArn、runtimeSessionId 与 payload（含 prompt、context）。示例中非经理用户请求 50000 美元退款会被策略阻止，智能体响应会表明该操作被拒绝。

操作 5：策略校验与调试

调用 get_policy_generation 取得 validationResults.issues，逐条打印类型、消息与位置。常见问题包括：过宽（允许超出预期）、过严（阻止合法操作）、不可满足条件（永不匹配）、schema 不匹配（引用不存在的工具）。

调试时可开启 botocore 的 DEBUG 日志，并检查 CloudWatch 中日志组 /aws/bedrock-agentcore/gateway/{gateway-id} 的 PolicyDecision 事件，示例条目包含 eventType、action、decision、matchedPolicy 与 reason。

资料还给出测试场景函数示例，覆盖普通用户读取、普通用户更新（预期 DENY）、高级理赔员更新（预期 ALLOW）、无描述提交理赔（预期 DENY）与带描述提交理赔（预期 ALLOW）等，通过 simulate_policy(case) 断言结果。

Cedar 快速参考

Principal 类型：principal（任意）、principal is AgentCore::OAuthUser（OAuth 认证用户）、principal is AgentCore::ApiKeyUser（API key 认证）。

Action：action == AgentCore::Action::"ToolName__method" 或 action in [...]。

条件：标签检查 principal.hasTag("role")、principal.getTag("role") == "admin"、principal.getTag("scope") like "*read*"；上下文检查 context.input has fieldName、context.input.amount < 1000、context.input.type == "premium"；逻辑运算符 &&、||、!。

策略类型：permit(...)、permit(...) when {}、forbid(...)、forbid(...) unless {}。

最佳实践

从宽松开始，逐步收紧：第一阶段允许全部并记录操作；第二阶段分析后再添加限制条件。
使用描述性策略名，例如 refund-limit-1000-non-managers 而非 policy-1。
记录业务规则，例如注明 PCI-DSS 合规要求信用卡操作受角色限制。
分层策略：全局默认拒绝、宽泛的只读 permit、角色特定的写入 permit、高度受限的管理员 permit、应急 forbid。

MCP 服务器集成

AgentCore Policy 可作为 MCP 服务器用于 AI 辅助编码环境，配置为：command 为 uvx，args 为 bedrock-agentcore-policy-mcp，env 中设置 AWS_REGION。

参考资料

references/cedar-syntax.md：完整 Cedar 语言指南
references/policy-patterns.md：常见模式库
references/troubleshooting.md：策略调试指南

限制说明

资料未提供价格、收费模式、支持的全部区域、配额上限、SLA 等信息，暂未提供。上述质量目标与关键原则为资料中列出的内容，未提供独立的验证细节。

技能介绍

用途