亚马逊 Bedrock Agent Core 构造库

本单元中更高层次的构件的API是实验性的并正在积极开发中. 在今后任何版本中,它们都须作非背向相容的修改或去除。 这些是 不适用 语义版本 模型和断开的更改 在发行笔记中宣布. 这意味着虽然你可能使用它们,但可能需要更新 当更新到此软件包的更新版本时,您的源代码.

这个 政策 子模块是唯一留在α的子模块. 所有其他建筑已逐步稳定 aws-cdk-lib/aws-bedrockagentcore 我们建议迁移到稳定版本.

语言	软件包
类型脚本	@aws-cdk/aws-bedrock-agentcore-alpha

向稳定移徙

除Policy外的所有构造都移到 aws-cdk-lib/aws-bedrockagentcore数字 :

// Before
import * as agentcore from '@aws-cdk/aws-bedrock-agentcore-alpha';

// After (for all non-Policy constructs)
import * as agentcore from 'aws-cdk-lib/aws-bedrockagentcore';

目前,下列结构处于稳定状态:

• 运行时间数字 : Runtime, (中文(简体) ), RuntimeEndpoint, (中文(简体) ), AgentRuntimeArtifact, (中文(简体) ), NetworkConfiguration, (中文(简体) ), Observability
• 网关数字 : Gateway, (中文(简体) ), GatewayTarget, (中文(简体) ), GatewayAuthorizer, (中文(简体) ), GatewayCredentialProvider, (中文(简体) ), Interceptor
• 工具数字 : BrowserCustom, (中文(简体) ), CodeInterpreterCustom
• 内存数字 : Memory, (中文(简体) ), MemoryStrategy
• 评价数字 : OnlineEvaluationConfig, (中文(简体) ), Evaluator, (中文(简体) ), EvaluatorSelector
• 身份数字 : OAuth2CredentialProvider, (中文(简体) ), ApiKeyCredentialProvider, (中文(简体) ), WorkloadIdentity

阿尔法还剩下什么

政策分单元仍然是实验性的:

• PolicyEngine
• Policy
• PolicyStatement
• PolicyValidationMode
• PolicyEngineMode

政策引擎

政策引擎是一套评价和授权代理工具呼叫的政策。 当与网关相关联时,政策引擎会拦截所有代理请求并决定是否根据所定义的政策允许或拒绝每项行动.

更多信息,请参见 亚马逊 Bedrock Agent Core 文件的政策。 。 。 .

策略引擎属性

了解代理公司锡达政策

制定政策时使用了 锡达语,用于写作和执行授权政策的开源语言. Agent Core的雪松政策遵循一个具有三个主要组成部分的具体结构: 校长, (中文(简体) ), 行动,以及 资源了解这些组成部分如何合作对于制定有效的政策至关重要.

政策结构

每个雪松政策都有这样的基本结构:

permit(              // or forbid
  principal,         // Who is making the request
  action,            // What operation they want to perform
  resource           // What Gateway/tool they want to access
)
when {               // Optional conditions
  // Additional constraints
};

示例政策

permit(
  principal,
  action == AgentCore::Action::"ApplicationToolTarget___create_application",
  resource == AgentCore::Gateway::"<gateway-arn>"
) when {
  context.input.coverage_amount <= 1000000
};

基本政策动力和政策制定

创建政策引擎并加入政策.

政策引擎模式

当将政策引擎与网关连接时,您可以使用 PolicyEngineMode数字 :

• PolicyEngineMode.LOG_ONLY (默认)——评价诉讼并添加痕迹但不执行裁决. 在启用执行前使用此模式进行测试和验证 .
• PolicyEngineMode.ENFORCE ——根据锡达政策评价,积极允许或否认代理业务.

// Create a Policy engine
const policyEngine = new agentcore.PolicyEngine(this, "MyPolicyEngine", {
  policyEngineName: "my_policy_engine",
  description: "Policy engine for access control",
});

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
  policyEngineConfiguration: {
    policyEngine: policyEngine,
    mode: agentcore.PolicyEngineMode.ENFORCE, // Default is LOG_ONLY
  },
});

// Add policy to policy engine
policyEngine.addPolicy("AllowAllActions", {
  definition: `
    permit(
      principal,
      action,
      resource == AgentCore::Gateway::"${gateway.gatewayArn}"
    );
  `,
  description: "Allow all actions on specific gateway (development)",
  validationMode: agentcore.PolicyValidationMode.IGNORE_ALL_FINDINGS, // This will ignore all cedar warnings
});

// you can add multiple policies to the policy engine
policyEngine.addPolicy("SpecificToolPolicy", {
  definition: `
    permit(
      principal is AgentCore::OAuthUser,
      action == AgentCore::Action::"WeatherTool__get_forecast",
      resource == AgentCore::Gateway::"${gateway.gatewayArn}"
    );
  `,
  description: "Allow specific weather tool access",
  validationMode: agentcore.PolicyValidationMode.FAIL_ON_ANY_FINDINGS, // This will fail policy creation for any cedar warning
});

类型安全策略构建器

对于更安全的方法,请使用 PolicyStatement 建构器取而代之的是写出生锡达语法.

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

const policyEngine = new agentcore.PolicyEngine(this, "MyPolicyEngine", {
  policyEngineName: "my_policy_engine",
});

const allowAllPolicy = new agentcore.Policy(this, "AllowAllPolicy", {
  policyEngine: policyEngine,
  policyName: "allow_all",
  statement: agentcore.PolicyStatement.permit()
    .forAllPrincipals() // ** This will give overly permission to all principals
    .onAllActions()
    .onResource('AgentCore::Gateway', gateway.gatewayArn),
  description: "Allow all actions on specific gateway (development only)",
  validationMode: agentcore.PolicyValidationMode.IGNORE_ALL_FINDINGS,
});

// Generated Cedar:
// permit(
//   principal,
//   action,
//   resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:region:account:gateway/gateway-id"
// );

有具体行动的政策

declare const policyEngine: agentcore.PolicyEngine;
declare const gateway: agentcore.Gateway;

// Allow specific tool actions on specific gateway
// Action names follow pattern: "ToolName__operation"
policyEngine.addPolicy("SpecificToolPolicy", {
  statement: agentcore.PolicyStatement.permit()
    .forPrincipal('AgentCore::OAuthUser::your-client-id')
    .onActions([
      'AgentCore::Action::WeatherTool__get_forecast',
      'AgentCore::Action::WeatherTool__get_current',
    ])
    .onResource('AgentCore::Gateway', gateway.gatewayArn),
  description: "Allow specific weather tool operations",
  validationMode: agentcore.PolicyValidationMode.FAIL_ON_ANY_FINDINGS,
});

// Generated Cedar:
// permit(
//   principal is AgentCore::OAuthUser,
//   action in [
//     AgentCore::Action::"WeatherTool__get_forecast",
//     AgentCore::Action::"WeatherTool__get_current"
//   ],
//   resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:123:gateway/gw-123"
// );

有条件的政策

使用 when 添加基于主标记(取自 OAuth 令牌) 或上下文的高级条件的条款:

declare const policyEngine: agentcore.PolicyEngine;
declare const gateway: agentcore.Gateway;

// Policy with when conditions using principal tags
const conditionalPolicy = new agentcore.Policy(this, "ConditionalPolicy", {
  policyEngine: policyEngine,
  policyName: "conditional_access",
  statement: agentcore.PolicyStatement.permit()
    .forPrincipal('AgentCore::OAuthUser')  // Type constraint
    .onAllActions()
    .onResource('AgentCore::Gateway', gateway.gatewayArn)  // Specific ARN
    .when()
      .principalAttribute('department').equalTo('Engineering')
      .and()
      .contextAttribute('input.priority').equalTo('high')
      .done(),
  description: "Allow engineers for high-priority requests",
  validationMode: agentcore.PolicyValidationMode.FAIL_ON_ANY_FINDINGS,
});

// Generated Cedar:
// permit(
//   principal is AgentCore::OAuthUser,
//   action,
//   resource == AgentCore::Gateway::"arn:..."
// )
// when {
//   principal.department == "Engineering" && context.input.priority == "high"
// };

排除政策(除非)

使用 unless 将具体条件排除在政策之外的条款。 该政策适用于: unless 不符合下列条件:

declare const policyEngine: agentcore.PolicyEngine;
declare const gateway: agentcore.Gateway;

// Allow access unless the user is suspended
const policyWithUnless = new agentcore.Policy(this, "UnlessPolicy", {
  policyEngine: policyEngine,
  policyName: "unless_suspended",
  statement: agentcore.PolicyStatement.permit()
    .forPrincipal('AgentCore::OAuthUser')
    .onAllActions()
    .onResource('AgentCore::Gateway', gateway.gatewayArn)
    .unless()
      .principalAttribute('suspended').equalTo(true)
      .done(),
  description: "Allow all actions unless user is suspended",
  validationMode: agentcore.PolicyValidationMode.FAIL_ON_ANY_FINDINGS,
});

// Generated Cedar:
// permit(
//   principal is AgentCore::OAuthUser,
//   action,
//   resource == AgentCore::Gateway::"arn:..."
// )
// unless {
//   principal.suspended == true
// };

你可以结合 when 财务报告和审定财务报表 unless 同一政策中的条款:

declare const policyEngine: agentcore.PolicyEngine;
declare const gateway: agentcore.Gateway;

// Allow engineers unless they are on probation
policyEngine.addPolicy("CombinedConditions", {
  statement: agentcore.PolicyStatement.permit()
    .forPrincipal('AgentCore::OAuthUser')
    .onAllActions()
    .onResource('AgentCore::Gateway', gateway.gatewayArn)
    .when()
      .principalAttribute('department').equalTo('Engineering')
      .done()
    .unless()
      .principalAttribute('status').equalTo('probation')
      .done(),
  description: "Allow engineers unless on probation",
  validationMode: agentcore.PolicyValidationMode.FAIL_ON_ANY_FINDINGS,
});

禁用( Deny) 政策

使用 forbid 明确拒绝进入。 禁止政策优先于允许政策.

declare const policyEngine: agentcore.PolicyEngine;
declare const gateway: agentcore.Gateway;

// Explicitly deny dangerous tool operations
policyEngine.addPolicy("DenyDangerous", {
  statement: agentcore.PolicyStatement.forbid()
    .forAllPrincipals()
    .onAction('AgentCore::Action::DeleteTool__delete_all')
    .onResource('AgentCore::Gateway', gateway.gatewayArn),
  description: "Forbid delete_all operation for all users",
  validationMode: agentcore.PolicyValidationMode.FAIL_ON_ANY_FINDINGS,
});

// Generated Cedar:
// forbid(
//   principal,
//   action == AgentCore::Action::"DeleteTool__delete_all",
//   resource == AgentCore::Gateway::"arn:..."
// );

Raw Cedar 高级案件

对于建设者不支持的高级 Cedar 特性,使用原始 Cedar 字符串 :

declare const policyEngine: agentcore.PolicyEngine;

// Option 1: Using definition property
const advancedPolicy = new agentcore.Policy(this, "AdvancedPolicy", {
  policyEngine: policyEngine,
  definition: 'permit(principal, action, resource) when { context.custom > 10 };',
  description: "Advanced policy with custom Cedar logic",
});

// Option 2: Using fromCedar() with statement property
policyEngine.addPolicy("CustomPolicy", {
  statement: agentcore.PolicyStatement.fromCedar(
    'forbid(principal, action, resource) when { resource.confidential == true };'
  ),
  description: "Custom policy from Cedar string",
});

说明: 您必须指定 无论是 definition (raw Cedar 字符串) (英语) 或者说 statement (政策制订者),但不是两者兼有.

获取政策引擎政策

您可以使用 PolicyEngine 访问 PolicyEngine 中添加的政策列表。 政策.

带有 KMS 加密的政策引擎

用自定义的 KMS 密钥加密政策数据 .

// Create a custom KMS key
const policyKey = new kms.Key(this, "PolicyEngineKey", {
  enableKeyRotation: true,
  description: "KMS key for policy engine encryption",
});

// Create policy engine with encryption
const policyEngine = new agentcore.PolicyEngine(this, "EncryptedEngine", {
  policyEngineName: "encrypted_engine",
  description: "Policy engine with KMS encryption",
  kmsKey: policyKey,
});

导入已存在的政策引擎

从 ARN 导入现有的政策引擎 :

const importedEngine = agentcore.PolicyEngine.fromPolicyEngineAttributes(
  this,
  "ImportedEngine",
  {
    policyEngineArn: "policy-engine-arn",
    kmsKeyArn: "kms-arn",
  }
);

// Use the imported engine
const policy = new agentcore.Policy(this, "PolicyForImportedEngine", {
  policyEngine: importedEngine,
  definition: "permit(principal, action, resource);",
});

导入现有政策

从 ARN 导入现有策略 :

const importedEngine = agentcore.PolicyEngine.fromPolicyEngineAttributes(
  this,
  "ImportedEngine",
  {
    policyEngineArn: "policy-engine/my-engine-id",
  }
);

const importedPolicy = agentcore.Policy.fromPolicyAttributes(
  this,
  "ImportedPolicy",
  {
    policyArn: "my-policy-arn",
    policyEngine: importedEngine,
  }
);

// Grant permissions to the imported policy
const role = new iam.Role(this, "PolicyRole", {
  assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
});

importedPolicy.grantRead(role);

政策引擎 IAM 权限

提供不同层次的政策引擎:

const policyEngine = new agentcore.PolicyEngine(this, "MyEngine", {
  policyEngineName: "my_engine",
});

const lambdaRole = new iam.Role(this, "LambdaRole", {
  assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
});

// Grant read permissions
policyEngine.grantRead(lambdaRole);

// Grant evaluation permissions
policyEngine.grantEvaluate(lambdaRole);

使用具有稳定网关的政策

由于Gateway现在在 aws-cdk-lib/aws-bedrockagentcore 使用L1逃生舱门将一个政策引擎与稳定的网关联系起来:

今后的更新将增加适当的L2整合.

import * as agentcore from 'aws-cdk-lib/aws-bedrockagentcore';
import * as agentcoreAlpha from '@aws-cdk/aws-bedrock-agentcore-alpha';

// Create policy engine (alpha)
const policyEngine = new agentcoreAlpha.PolicyEngine(this, 'Engine', {
  policyEngineName: 'my_engine',
});

// Create gateway (stable)
const gateway = new agentcore.Gateway(this, 'Gateway', {
  gatewayName: 'my-gateway',
});

// Wire policy engine to gateway via the L1 construct
const cfnGateway = gateway.node.defaultChild as agentcore.CfnGateway;
cfnGateway.policyEngineConfiguration = {
  arn: policyEngine.policyEngineArn,
  mode: agentcoreAlpha.PolicyEngineMode.ENFORCE.value,
};

// Grant evaluate permissions to the gateway role
gateway.role.addToPrincipalPolicy(new iam.PolicyStatement({
  actions: ['bedrock-agentcore:GetPolicyEngine'],
  resources: [policyEngine.policyEngineArn],
}));
gateway.role.addToPrincipalPolicy(new iam.PolicyStatement({
  actions: ['bedrock-agentcore:AuthorizeAction', 'bedrock-agentcore:PartiallyAuthorizeActions'],
  resources: [policyEngine.policyEngineArn, gateway.gatewayArn],
}));