# Amazon Bedrock AgentCore 政策 ## 概述 AgentCore 策略提供代理边界的确定性执行，与提示工程的概率性质分开。使用自然语言编写策略，自动转换为 Cedar（AWS 的开源策略语言），以便在网关层实时执行。 **目的**：通过确定性、可审计的规则定义代理可以做什么和不能做什么 **模式**：基于任务（5 个操作） **关键原则**（AWS 于 2025 年 12 月验证）： 1. **自然语言创作** \- 用简单的英语编写政策 2. **自动 Cedar 生成** \- 系统转换为有效的 Cedar 3. **实时执行** \-网关拦截每个工具调用 4. **自动推理** \- 检测过度宽松/限制性规则 5. **默认拒绝** \-无许可策略=自动拒绝 6. **禁止获胜** \- 禁止总是优先于允许 **质量目标**： * 策略生成：< 5 秒 * 执行延迟：每次工具调用 < 10 毫秒 * 验证覆盖率：100% 的工具模式 ** ** ## 何时使用在以下情况下使用 bedrock-agentcore-policy： * 为代理可以做什么设定界限 * 实施基于角色的访问控制（RBAC） * 执行合规规则（例如最大退款金额） * 暂时禁用有问题的工具 * 需要特定参数进行操作 * 审计代理行为 **何时不使用**： * 内容过滤（使用基岩护栏） * 速率限制（使用API网关） * 业务逻辑（在工具中实现） ** ** ## 先决条件 ### 必填 * 配置AgentCore网关 * 注册为网关目标的工具 * 策略操作的IAM权限 ### 推荐 * Cedar语义的理解 * 记录工具模式 * 定义测试场景 ** ** ## 操作 ### 操作 1：自然语言策略编写 **时间**：2-5 分钟 **自动化**：95% **目的**：根据简单的英语描述创建策略 **流程**： 1. **用自然语言定义要求**： “允许所有用户阅读保单详细信息和索赔状态。仅允许具有“高级理算员”角色的用户更新承保范围。除非提供说明，否则阻止所有索赔申请。” 2. **生成 Cedar 政策** : 导入boto3 control = boto3.client('bedrock-agentcore-control') # 从自然语言开始生成策略响应 = control.start_policy_ Generation( gatewayId='网关-xxx', NaturalLanguagePolicy=""" 允许所有用户获取保单并获取索赔状态。仅允许具有“高级理算员”角色的委托人更新承保范围。除非提供说明，否则阻止委托人提出索赔。 """, 保单名称='保险代理保单' ） Generation_id = 响应['policyGenerationId'] # 等待完成 waiter = control.get_waiter('PolicyGenerationCompleted') waiter.wait(policyGenerationId= Generation_id) # 获取生成的 Cedar 结果 = control.get_policy_ Generation( 策略GenerationId= Generation_id ） cedar_policy = 结果['生成的政策'] 验证结果 = 结果['验证结果'] 3. **查看生成的 Cedar** ： // 允许每个人进行只读操作许可（校长, 行动在[ AgentCore::Action::"InsuranceAPI__get_policy", AgentCore::操作::"InsuranceAPI__get_claim_status" ], 资源）； // 仅允许特定角色的更新许可（校长, 操作 == AgentCore::Action::"InsuranceAPI__update_coverage", 资源）当{ 主体.hasTag("角色") && principal.getTag("角色") == "高级调整者" }; // 阻止没有描述的声明禁止（校长, 操作 == AgentCore::操作::"InsuranceAPI__file_claim", 资源）除非{ context.input 有描述 }; ** ** ### 操作2：直接创建策略（Cedar） **时间**：5-10 分钟 **自动化**：80% **目的**：完全控制编写 Cedar 策略 **雪松语法**： // 基本许可许可（校长, action == AgentCore::Action::"ToolName__method", 资源 == AgentCore::Gateway::"arn:..." ）； // 有条件的许可（主体是 AgentCore::OAuthUser，操作 == AgentCore::Action::"RefundAPI__process_refund", 资源）当{ 上下文.input.amount < 1000 }; // 禁止使用 except 禁止（校长, 操作 == AgentCore::Action::"DeleteAPI__delete_record", 资源）除非{ 主体.hasTag("角色") && principal.getTag("角色") == "管理员" }; **通过 boto3 创建策略**：响应 = control.create_policy( name='退款限额政策', description='将非管理人员的退款限制在 1000 美元以下', 政策内容=''' 许可（校长, action == AgentCore::Action::"RefundToolTarget___refund", 资源 == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/refund" ）当{ 上下文.input.amount < 1000 }; 许可（校长, action == AgentCore::Action::"RefundToolTarget___refund", 资源 == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/refund" ）当{ 主体.hasTag("角色") && principal.getTag("角色") == "经理" }; ''' ） policy_id = 响应['policyId'] ** ** ### 操作 3：通用策略模式 **时间**：5-15 分钟 **自动化**：90% **目的**：实施标准访问控制模式 **模式 1：基于角色的访问控制 (RBAC)** // 仅限管理员操作许可（校长, 行动在[ AgentCore::Action::"AdminAPI__delete_user", AgentCore::操作::“AdminAPI__modify_permissions” ], 资源）当{ 主体.hasTag("角色") && principal.getTag("角色") == "管理员" }; **模式 2：OAuth 范围验证** // 需要特定范围许可（主体是 AgentCore::OAuthUser，操作 == AgentCore::Action::"CustomerAPI__read_profile", 资源）当{ 主体.hasTag(“范围”) && principal.getTag("scope") 就像 "*customer:read*" }; **模式 3：参数约束** // 通过参数值限制许可（校长, 操作 == AgentCore::Action::"TransferAPI__transfer_funds", 资源）当{ context.input 有金额 && context.input.amount <= 10000 }; **模式 4：多条件 AND 逻辑** // 所有条件必须为真许可（校长, 操作 == AgentCore::Action::"InsuranceAPI__update_coverage", 资源）当{ context.input 有coverageType && context.input 有 newLimit && (context.input.coverageType == "责任" || context.input.coverageType == "碰撞") }; **模式 5：禁用特定工具** // 暂时禁用工具禁止（校长, 动作 == AgentCore::Action::"ProblematicAPI__buggy_method", 资源）； **模式 6：用户特定的权限** // 授予特定用户许可（校长, 动作 == AgentCore::Action::"SpecialAPI__sensitive_action", 资源）当{ principal.hasTag("用户名") && principal.getTag("用户名") == "受信任的用户" }; ** ** ### 操作4：策略引擎配置 **时间**：5-10 分钟 **自动化**：85% **目的**：将策略附加到网关以执行 **创建策略引擎**： # 创建策略引擎来评估策略响应 = control.create_policy_engine( name='保险保单引擎', description='强制执行保险代理边界', gatewayId='网关-xxx' ） engine_id = 响应['policyEngineId'] # 等待激活服务员 = control.get_waiter('PolicyEngineActive') waiter.wait(policyEngineId=engine_id) **将策略附加到引擎**： # 使用策略更新策略引擎响应 = control.update_policy_engine( policyEngineId=engine_id, 策略ID=[ '策略读取访问', “政策角色限制”， “政策退款限额” ] ） **测试政策执行**： # 调用代理并观察策略执行情况客户端 = boto3.client('bedrock-agentcore') 响应 = client.invoke_agent_runtime( agentRuntimeArn='arn:...', runtimeSessionId='测试会话', 有效负载={ 'prompt': '处理$50000的退款', “上下文”：{ 'user_id': '普通用户', 'role': 'customer-service' # 不是经理 } } ） # 政策将阻止此行为 - 非经理金额超过 1000 美元 # 代理响应将表明操作被拒绝 ** ** ### 操作5：策略验证和调试 **时间**：5-15 分钟 **自动化**：80% **目的**：测试策略行为并排除故障 **验证检查**： # 获取策略验证结果响应 = control.get_policy_ Generation( 策略GenerationId= Generation_id ）对于response.get('validationResults', {}).get('issues', [])中的问题： print(f"问题：{问题['type']}") print(f"消息：{问题['消息']}") print(f"位置：{issue.get('位置', 'N/A')}") # 常见问题： # - 过于宽容（允许超过预期） # - 过度限制（阻止合法行为） # - 无法满足的条件（永远无法匹配） # - 架构不匹配（引用不存在的工具） **调试策略决策**： # 启用详细日志记录导入日志记录 logging.getLogger('botocore').setLevel(logging.DEBUG) # 检查 CloudWatch 的策略决策 # 日志组：/aws/bedrock-agentcore/gateway/{gateway-id} # 查找：PolicyDecision 事件 # 日志条目示例：＃{ # "eventType": "PolicyDecision", # "action": "InsuranceAPI__file_claim", #“决定”：“拒绝”， # "matchedPolicy": "策略要求描述", # "reason": "条件不满足：context.input 有描述" # } **测试场景**： def test_policy_scenarios(): """测试各种政策场景""" 测试用例= [ { 'name': '普通用户读取策略', '行动'：'获取策略'， '上下文': {'角色': '用户'}, '预期'：'允许' }, { 'name': '定期用户更新覆盖范围', '行动'：'更新覆盖率'， '上下文': {'角色': '用户'}, '预期'：'拒绝' }, { 'name': '高级理赔员更新承保范围', '行动'：'更新覆盖率'， 'context': {'role': '高级调节员'}, '预期'：'允许' }, { 'name': '没有描述的声明', '行动'：'文件声明'， '上下文': {'角色': '用户'}, 'input': {'amount': 100}, # 无描述 '预期'：'拒绝' }, { 'name': '带有描述的声明', '行动'：'文件声明'， '上下文': {'角色': '用户'}, 'input': {'amount': 100, 'description': '车祸'}, '预期'：'允许' } ] 对于 test_cases 中的情况：结果 = 模拟策略（案例）断言结果 == case['expected'], f"失败: {case['name']}" ** ** ## 雪松快速参考 ### 主要类型主体 // 任何主体主体是 AgentCore::OAuthUser // OAuth 身份验证用户主体是 AgentCore::ApiKeyUser // API 密钥经过身份验证 ### 行动操作 == AgentCore::操作::"工具名称__方法" [动作 1、动作 2、动作 3] 中的动作 ### 条件 // 标签检查主体.hasTag("角色") principal.getTag("角色") == "管理员" principal.getTag("scope") 就像 "*read*" // 上下文/输入检查 context.input 有 fieldName 上下文.input.amount < 1000 context.input.type == "高级" // 逻辑运算符 && // 与 || // 或者！ // 不 ### 策略类型 Permit(...) // 如果条件匹配则允许 Permit(...) when {} // 有条件允许 forbid(...) // 无条件拒绝 forbid(...) except {} // 除非条件匹配否则拒绝 ** ** ## 最佳实践 ### 1\.开始宽松，逐渐收紧 // 第 1 阶段：允许所有记录操作许可（主体、行动、资源）； // 第2阶段：分析后，添加限制许可（主体、行动、资源）当 { /* 特定条件 */ }; ### 2\.使用描述性策略名称控制.create_policy( name='refund-limit-1000-non-managers', # 好 # name='policy-1', # 不好 ... ） ### 3\.记录业务规则 // 业务规则：PCI-DSS 合规性要求 // 信用卡操作受到角色限制许可（校长, 操作== AgentCore::操作::"PaymentAPI__process_card", 资源）当{ 主体.hasTag("角色") && [" payment-admin", "finance"] 中的principal.getTag("role") }; ### 4\.图层策略政策堆栈： 1.全局拒绝（默认） 2. 只读许可（广义） 3. 写入许可（特定于角色） 4. 管理员许可（严格限制） 5.紧急禁止（立即禁用） ** ** ## MCP 服务器集成 AgentCore Policy 可用作 AI 辅助编码环境的 MCP 服务器： { “mcp服务器”：{ “基岩-agentcore-政策”：{ “命令”：“uvx”， "args": ["bedrock-agentcore-policy-mcp"], “环境”：{ "AWS_REGION": "us-east-1" } } } } ** ** ## 相关技能 * **bedrock-agentcore** ：核心平台和网关设置 * **bedrock-agentcore-evaluations** ：测试政策有效性 * **bedrock-agentcore-deployment** ：使用代理部署策略 * **eks-irsa** ：EKS 托管代理的 IAM 集成 ** ** ## 参考文献 * `references/cedar-syntax.md` \- 完整的 Cedar 语言指南 * `references/policy-patterns.md` \- 通用模式库 * `references/troubleshooting.md` \- 策略调试指南 ** ** ## 来源 * [Amazon Bedrock AgentCore 政策]() * [示例政策]() * [常见策略模式]() * [雪松语言]()

基岩代理核心政策

包含技能