# @aws-cdk/aws-bedrock-agentcore-alpha 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-bedrock-agentcore-alpha/

版本：2\.275\.0-alpha\.0
npm 元数据更新时间：2026-10-26T19:19:25.598Z
中文译文更新时间：2026-11-07T11:17:54.781Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-bedrock-agentcore-alpha
原文对照：https://npmcn.com/package/%40aws-cdk/aws-bedrock-agentcore-alpha/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.6 MB，144 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 20\.0\.0
- 运行依赖：0 个
- peer 依赖：constructs ^10\.5\.0，aws-cdk-lib ^2\.275\.0，@aws-cdk/aws-bedrock-alpha 2\.275\.0-alpha\.0
- 首次发布：2025-10-24T14:59:21.730Z
- 最新版本发布：2026-10-26T19:19:25.270Z
- 近 30 天下载量：166000（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 64 个）

## 中文简介

亚马逊 Bedrock 的 CDK 构建库

## 安装

```sh
npm install @aws-cdk/aws-bedrock-agentcore-alpha
```

也可以使用：`pnpm add @aws-cdk/aws-bedrock-agentcore-alpha`、`yarn add @aws-cdk/aws-bedrock-agentcore-alpha`、`bun add @aws-cdk/aws-bedrock-agentcore-alpha`

## README

# 亚马逊 Bedrock Agent Core 构造库

* * *

![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)

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

* * *

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

| **语言** | **软件包** |
| --- | --- |
| ![Typescript Logo](https://docs.aws.amazon.com/cdk/api/latest/img/typescript32.png) 类型脚本 | `@aws-cdk/aws-bedrock-agentcore-alpha` |

## 向稳定移徙

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

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

```ts
// 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 文件的政策](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html)。 。 。 .

### 策略引擎属性

| 名称 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `policyEngineName` | `string` | 没有 | 政策引擎的名称. 有效字符:a-z,A-Z,0-9, (下分数). 必须以字母开头, 1 -48 个字符. 如果不提供, 将自动生成独有名称 |
| `description` | `string` | 没有 | 政策引擎的可选描述(最大为4,096个字符). 默认: 无描述 |
| `kmsKey` | `IKey` | 没有 | 自定义加密的 KMS 密钥 . **重要性**: 一旦设定,则不能更改(需要替换). 一定是对称的 ENCRYPT DECRYPT 密钥 。 如果无法获取密钥,则所有授权决定都将被拒绝。 默认: AWS 拥有密钥 |
| `tags` | `{ [key: string]: string }` | 没有 | 策略引擎的标记(最大为50个标记). 默认: 无标签 |

### 了解代理公司锡达政策

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

#### 政策结构

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

```cedar
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
};
```

示例政策

```cedar
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` ——根据锡达政策评价,积极允许或否认代理业务.

```typescript

// 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` 建构器取而代之的是写出生锡达语法.

```typescript
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"
// );
```

#### 有具体行动的政策

```typescript
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 令牌) 或上下文的高级条件的条款:

```typescript
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` 不符合下列条件:

```typescript
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` 同一政策中的条款:

```typescript
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` 明确拒绝进入。 禁止政策优先于允许政策.

```typescript
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 字符串 :

```typescript
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 密钥加密政策数据 .

```typescript
// 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 导入现有的政策引擎 :

```typescript
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 导入现有策略 :

```typescript
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 权限

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

```typescript
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整合.

```ts
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],
}));
```

## 常见问题

### @aws-cdk/aws-bedrock-agentcore-alpha 是什么？

亚马逊 Bedrock 的 CDK 构建库

### 如何安装 @aws-cdk/aws-bedrock-agentcore-alpha？

在项目目录运行 npm install @aws-cdk/aws-bedrock-agentcore-alpha，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.5\.0）、aws-cdk-lib（^2\.275\.0）、@aws-cdk/aws-bedrock-alpha（2\.275\.0-alpha\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-bedrock-agentcore-alpha 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-cdk/aws-bedrock-agentcore-alpha 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-bedrock-agentcore-alpha 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-bedrock-agentcore-alpha 可以商用吗？

@aws-cdk/aws-bedrock-agentcore-alpha 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-bedrock-agentcore-alpha 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-bedrock-agentcore-alpha 在 2026/10/07 – 2026/11/05 这 30 天内被下载 166,000 次，日均约 5,533 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-cdk/aws-bedrock-agentcore-alpha 还在维护吗？

最新版本 2\.275\.0-alpha\.0 发布于 2026/10/27（12 天前）；至今共发布 67 个版本，其中过去 12 个月发布了 64 个；首次发布于 2025/10/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。