# @aws/agentcore-cdk 中文文档

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

版本：1\.0\.2
npm 元数据更新时间：2026-11-06T15:45:36.588Z
中文译文更新时间：2026-11-07T12:26:51.318Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.5 MB，471 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：4 个
- peer 依赖：constructs ^10\.0\.0，aws-cdk-lib ^2\.269\.0
- 首次发布：2026-02-12T21:23:21.352Z
- 最新版本发布：2026-11-06T15:45:36.357Z
- 近 30 天下载量：89072（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 60 个）

## 中文简介

Amazon Bedrock Agent Core 的 L3 CDK 构造

## 安装

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

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

## README

# @aws/ agentcore-cdk (英语)

L3 CCDK为亚马逊贝德罗克代理Core所建. 部署具有强型、可申报的代理基础设施 规格.

## 安装

```bash
npm install @aws/agentcore-cdk
```

**说明:** `aws-cdk-lib` 财务报告和审定财务报表 `constructs` 是同伴的依赖关系。 若你还没拿到

```bash
npm install @aws/agentcore-cdk aws-cdk-lib constructs
```

## 快速启动

AgentCore 项目是一个目录,其中包含 `agentcore/agentcore.json` (书写人: `agentcore project create`) (中文(简体) ). 光盘 将Core CLI 代理服务器应用到 `agentcore/cdk/` 这是这个图书馆最小的完整用途——三通电话 `bin/cdk.ts` 和一个构造 `lib/cdk-stack.ts`数字 :

```typescript
// bin/cdk.ts
#!/usr/bin/env node
import { App } from 'aws-cdk-lib';
import { readAgentCoreProject, resolveTargetStacks, transformAgentCoreJson } from '@aws/agentcore-cdk';
import { AgentCoreStack } from '../lib/cdk-stack';

try {
  // The AgentCore CLI runs this app from agentcore/cdk/; readAgentCoreProject walks up to agentcore/.
  const project = readAgentCoreProject();
  const app = new App();
  for (const stack of resolveTargetStacks({
    projectName: project.projectName,
    targets: project.targets,
    deployedState: project.deployedState,
  })) {
    new AgentCoreStack(app, stack.stackName, {
      env: stack.env,
      tags: stack.tags,
      description: stack.description,
      application: transformAgentCoreJson(project.agentCoreJson, {
        projectRoot: project.projectRoot,
        credentials: stack.credentials,
        target: stack.target,
      }),
    });
  }
  app.synth();
} catch (error) {
  console.error('AgentCore CDK synthesis failed:', error instanceof Error ? error.message : error);
  process.exit(1);
}
```

```typescript
// lib/cdk-stack.ts
import { AgentCoreApplication, type AgentCoreApplicationProps } from '@aws/agentcore-cdk';
import { Stack, type StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export interface AgentCoreStackProps extends StackProps {
  /** Props for the AgentCore application, produced by transformAgentCoreJson from agentcore/agentcore.json. */
  application: AgentCoreApplicationProps;
}

/**
 * The stack the AgentCore CLI deploys. Everything declared in agentcore/agentcore.json is
 * created by the AgentCoreApplication construct. Add your own resources below it and wire
 * them to your runtimes and harnesses through the application's accessors.
 */
export class AgentCoreStack extends Stack {
  public readonly application: AgentCoreApplication;

  constructor(scope: Construct, id: string, props: AgentCoreStackProps) {
    super(scope, id, props);
    this.application = new AgentCoreApplication(this, 'Application', props.application);

    // Example: give a runtime a DynamoDB table.
    //
    // import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
    // const orders = new dynamodb.Table(this, 'Orders', {
    //   partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
    // });
    // const checkout = this.application.runtime('checkout'); // or .harness('support')
    // checkout.grantReadWrite(orders);
    // checkout.addEnvironmentVariable('ORDERS_TABLE', orders.tableName);
  }
}
```

三个切入点:

| 函数 | 它会做什么 |
| --- | --- |
| `readAgentCoreProject(startDir = process.cwd())` | 走到最远处 `agentcore/agentcore.json` 并读取工程文件一次: 解析 `agentcore.json`,验证的项目名称, `aws-targets.json` (单位:千美元)`[]` (如果缺席) `agentcore/.cli/deployed-state.json` (单位:千美元)`undefined` 缺席时,文件丢出错误格式). 该应用程序唯一触及工作目录的地方. |
| `resolveTargetStacks({ projectName, targets, deployedState })` | 一个 `TargetStack` 每个部署目标, `AgentCore-<project>-<target>`,贴入目标账户/区域,贴出标签 `agentcore:project-name` 财务报告和审定财务报表 `agentcore:target-name`或环境不可知 `AgentCore-<project>` 堆栈(仅项目标记),当还没有目标时. |
| `transformAgentCoreJson(agentCoreJson, { projectRoot, credentials, target })` | 验证 `agentcore.json`,读取每个带子的 `harness.yaml` 财务报告和审定财务报表 `system-prompt.md` 和每个非S3知识库连接器文件 `projectRoot`时返回 `AgentCoreApplicationProps` 一个 `AgentCoreApplication`。 。 。 . `target` 是堆栈的部署目标,其名称变为 `AgentCoreApplicationProps.targetName`。同步、决定性、无网络、无 `process.env`。 。 。 . |

光谱中的每个相对路径都会与 `projectRoot`,所以合成从不依赖于工作目录.

每个物理 AWS 资源名称是 `<project><sep><target><sep><name>`: 项目名称、部署目标名称 和 资源 的 spec 名称,由服务接受的分隔符加入(`_` 代理核心资源 网关和知识库, `-` 为网关和Lambda的功能, `/` 用于ECR存储器,也用于 ) (中文(简体). 项目名称为字母和数字,目标名称为字母,数字和连字符. 与 `_` 每个分隔符 `-` 在目标变成 `_`因为这些服务只允许字母、数字和下划线,所以 运行时间 `checkout` 部署到目标 `prod-us` 实值 `Shop_prod_us_checkout`; 数据 `-` 财务报告和审定财务报表 `/` 分离器保留目标 就是这样 目标通过 `transformAgentCoreJson`是因为 `target` 选项,设置 `AgentCoreApplicationProps.targetName`, 和普通的 `bin/cdk.ts` 通过 `target: stack.target`运行时间 `checkout` 项目 `Shop` 部署到目标 `prodEu` 实值 `Shop_prodEu_checkout`。没有目标 `project build` 堆栈,或 `AgentCoreApplication` 未使用 `targetName`名称是 `<project><sep><name>`名称比 服务限制在合成时失败,指定资源、长度和限制.

## 构造

### 代理程序

用于部署剂环境的主要L3构造. 它需要项目的规格( :`agentcore.json`绳子 配置、 已部署的证书, 可选 `targetName` (部署目标,每个 实际资源名称)和所需名称 `projectRoot` (包含 `agentcore/`; 每一个相对路径 光谱会与之相抗衡,所以合成从来不取决于工作目录).

应用程序创造一切 `agentcore.json` 宣布,所以一个构造拥有整个光谱. 网关 (单位:千美元)`Gateway<name>`),是他们目标背后的计算结果(a`LambdaToolTarget<name>`, (中文(简体) ), `RuntimeToolTarget<name>`独立 工具运行时间`ToolRuntime<name>`)是申请的直接子女。 创建付款管理器和连接器 下划线 `Payments` cid 位于堆栈范围, 构造代号为 Agent Core CLI 使用的原始模板 (单位:千美元)`Payment<manager>` 财务报告和审定财务报表 `Payment<manager><connector>`,下划线已删除),因此,一个部署模板的堆栈将保持其 资源。 这些标识绝不能改变.

一旦每种资源都存在,应用程序就将每个资源与使用资源的工作量联系在一起(见 [约束代理 核心资源](https://npmcn.com/package/%40aws/agentcore-cdk/#readme-binding-agentcore-resources): 每一个运行时间的内存和网关,支付 管理器到 Python HTTP 运行时间, 每一个带的引用内存 和每一个带的网关, 每个 `connections[]` 输入和工具运行时间与命名它的工作量绑定.

### 运行时环境

一个条目: `runtimes[]`页:1 `AgentCoreRuntime`、建设资源、终点和产出.

## 扩展应用程序

### 获取资源

当资源必须存在时使用获取器 。 无法在合成时输入或丢失资源, 并列出可用名称 :

```typescript
const checkout = this.application.runtime('checkout');
const support = this.application.harness('support');
const tools = this.application.gateway('tools');
const history = this.application.memory('history');
```

其他获得者是: `knowledgeBase(name)`, (中文(简体) ), `evaluator(name)`, (中文(简体) ), `onlineEvalConfig(name)`, (中文(简体) ), `policyEngine(name)`, (中文(简体) ), `configBundle(name)`, (中文(简体) ), `capacityProvider(name)`, (中文(简体) ), `toolRuntime(name)`, (中文(简体) ), `paymentManager(name)` 财务报告和审定财务报表 `paymentConnector(manager, connector)`。使用相应的打入的地图,例如 `memories.get(name)`,当资源 是可选的,或者在延时. `runtimeEnvironments`, (中文(简体) ), `harnessRoles` 财务报告和审定财务报表 `toolLambdaFunctions` 只有地图。 遗产 仅限角色使用,可通过 `harnessRoles`· ; `harness(name)` 只返回一个完全合成的带子.

### 许可

具有执行角色的构造( A)`AgentCoreRuntime`, (中文(简体) ), `AgentCoreHarness`, (中文(简体) ), `AgentCoreHarnessRole` 财务报告和审定财务报表 `AgentCoreGateway`执行 `iam.IGrantable`,所以任何AWS L2赠款都接受. 跑步时间和拉带也会暴露 `grantRead` 编号 : `grantWrite` 编号 : `grantReadWrite` 用于 DynamoDB 表格、 S3 桶和保密管理器机密( 每个) 代表使用资源本身的赠款方法,因此IAM动作仍由aws-cdk-lib拥有, `grant(actions, resources)`, (中文(简体) ), `addToPolicy` 编号 : `addToRolePolicy`,以及 `addEnvironmentVariable`数字 :

```typescript
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';

const orders = new dynamodb.Table(this, 'Orders', {
  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
});
const checkout = this.application.runtime('checkout');
checkout.grantReadWrite(orders); // updates the runtime's execution role
checkout.addEnvironmentVariable('ORDERS_TABLE', orders.tableName);
orders.grantReadData(this.application.harness('support')); // any AWS L2 grant works too

const reports = new s3.Bucket(this, 'Reports');
checkout.grantWrite(reports, 'checkout/*'); // s3:PutObject + s3:DeleteObject* on checkout/* only

const apiKey = new secretsmanager.Secret(this, 'PartnerApiKey');
checkout.grantRead(apiKey); // secrets are read-only for a workload; grantWrite(secret) throws
checkout.addEnvironmentVariable('PARTNER_API_KEY_ARN', apiKey.secretArn);
```

AgentCore资源还为自己的数据平面操作提供赠款:运行时间 `grantInvoke`, (中文(简体) ), `grantExec` 财务报告和审定财务报表 `grantInvokeAll`绳子和网关 `grantInvoke`;回忆有 `grant` 财务报告和审定财务报表 `grantWithAccess`; 支付 经理有 `grantProcessPayment`。当呼叫者已经知道如何找到资源时使用这些 :

```typescript
const support = this.application.harness('support');

this.application.runtime('search').grantInvoke(support);
this.application.memory('history').grantWithAccess(support, 'read');
this.application.gateway('tools').grantInvoke(support);
this.application.paymentManager('billing').grantProcessPayment(support);
```

**导入角色.** 运行时间、 控制或网关配置 `executionRoleArn` 使用角色 CDK 无法修改. 每一个给予的路径——便利, `grant`, (中文(简体) ), `addToPolicy`,并通过 `grantPrincipal` - 发出a 包含动作的合成时间警告 **没有** 附加;输入角色必须已经携带.

**环境可变限制.** 两种资源最多接受50个变量;密钥必须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$` 和 1–100 个字符; 数值最多可能为 2048 个字符. `addEnvironmentVariable` 呼叫时间验证和 命名构造、 密钥和限制; 设置已存在的值的密钥为无, 设置为 不同的值是一个错误.

### 约束代理 核心资源

`AgentCoreMemory`, (中文(简体) ), `AgentCoreGateway`, (中文(简体) ), `AgentCorePaymentManager` 财务报告和审定财务报表 `AgentCoreRuntime` 执行 `IBindable`。 。 。 . `bind(workload)` 通过资源本身的赠款给予工作量的执行作用 方法并设定工作量代码读取的变量以找到它,全部在资源下 `discoveryPrefix`数字 : `MEMORY_<NAME>` 对于记忆, `AGENTCORE_<TYPE>_<NAME>` 用于网关、支付管理器或运行时间,以及 `<TYPE>_<ID>` 页:1 a 资源由 ARN 导入,名称大写,其他字符替换为 `_`。内存和导入 名称,以及下表中的证书名称,匹配 v0 CLI 部署的. 运行时间和绳子 工作量(`IAgentCoreWorkload`) (中文(简体) ). 使用 `grant*` 当只需要IAM许可时; 使用 `bind` 当工作量也 需要发现环境变量.

该申请对在下列文书中声明的关系具有约束力: `agentcore.json`。扩展应用程序的堆栈可以绑定 aRN 导入的额外关系或资源:

```typescript
import { AgentCoreMemory } from '@aws/agentcore-cdk';

const checkout = this.application.runtime('checkout');
const shared = AgentCoreMemory.fromMemoryArn(
  this,
  'shared',
  'arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/x'
);
shared.bind(checkout, { access: 'read' }); // MEMORY_SHARED_ID and _ARN, read actions on the ARN

const support = this.application.harness('support');
this.application.toolRuntime('search').bind(support, { envVarName: 'SEARCH_TOOL_ARN', exec: true });
this.application.paymentManager('billing').bind(support);
```

| 资源 | 前缀 | 变量 |
| --- | --- | --- |
| 内存 | `MEMORY_<spec name>`,或 `MEMORY_<import id>` | `ID`, (中文(简体) ), `ARN` |
| 网关 | `AGENTCORE_GATEWAY_<spec name>`,或 `GATEWAY_<import id>` | `URL`, (中文(简体) ), `ARN`, (中文(简体) ), `AUTH_TYPE` (单位:千美元)`AWS_IAM`, (中文(简体) ), `CUSTOM_JWT`, (中文(简体) ), `NONE`, (中文(简体) ), `CREDENTIAL_PROVIDER` 页:1 `CUSTOM_JWT` |
| 付款管理人 | `AGENTCORE_PAYMENT_<spec name>` | `MANAGER_ARN`, (中文(简体) ), `PROCESS_PAYMENT_ROLE_ARN`, (中文(简体) ), `CONNECTOR_ID` (第一个连接器), `AUTO_PAYMENT`, (中文(简体) ), `TOOL_ALLOWLIST`, (中文(简体) ), `NETWORK_PREFERENCES`, (中文(简体) ), `AUTH_MODE` |
| 运行时间( 作为工具) | `AGENTCORE_RUNTIME_<runtime name>`,或 `RUNTIME_<import id>` | `ARN`,或者装订 `envVarName` 逐字记录 |
| 浏览器,代码解释器(连接) | `BROWSER_<connection id>`, (中文(简体) ), `CODE_INTERPRETER_<connection id>` | `ID` 当给出了 ARN 时, AWS 默认值为无 |
| 证书 | `CREDENTIAL_<credential name>`, (中文(简体) ), `.` 财务报告和审定财务报表 `-` 改为 `_` | `NAME`,提供提供者名称(来自记录的ARN) |

用于项目网关 `protocolType: "MCP"`, (中文(简体) ), `URL` 是服务返回的完整的 MCP 端点。 对于 `protocolType: "None"`, (中文(简体) ), `URL` 是赤网关来源:附件 `/mcp` 来使用其 MCP 接口,或附加路径 用于呼叫 HTTP 目标 。 导入的网关仍然面向MCP,因为ARN不携带协议元数据, 因此,他们的来源 `URL` 结束于 `/mcp`。 。 。 .

导入 ID `connections[]` 条目是 `connectionTokenFor(connection)`: 连接 `id`,或 `<type>-<resource id>` 当没有时,则大写与其它字符替换为 `_`同样 Agent Core CLI烤入生成的代码. 将同样的资源与工作量相接两次,是绝对不行的。 两个资源 共享前缀,并在命名工作量和变量的合成时设置不同值的变量失败.

### 集装箱建在VPC中

当集装箱制造剂(或拉带)安装时 `networkMode: VPC`建造基础设施——指挥家Lambda 和共享代码构建项目 — 与运行时间相同, 使用 `networkConfig.subnets` 财务报告和审定财务报表 `networkConfig.securityGroups`。代码构建 `networkConfig.vpcId` (其API不能推断VPC来自 (b) 仅要求以VPC模式建造集装箱.

在一个单一项目中,所有集装箱代理人和装置必须建在同一VPC中——每件共用编码建造项目 堆栈和合成在不匹配时快速失败。 最多5个安全小组可以按VPC模式建造集装箱(编码建造) 限制),对运行时间为16.

**网络先决条件.** 私人子网必须能够到达 服务建设使用,或者建设将挂起 直到超时 :

-   Lambda 的建筑呼叫代码构建(`StartBuild`编号 :`BatchGetBuilds`),并且必须到达 CloudFormation 响应终点 (第3节).
-   代码构建必须达到 ECR( api + dkr), S3( 源资产), Cloud Watch Logs, STS, 以及 Dockerfile 的任何注册 基础图像从.

提供NAT网关或 VPC 端点,用于: ECR( api, dkr), S3( gateway), Cloud Watch Logs, CodeBuild, 和 STS — + 换取公共基座图.

## 网关目标IAM认证

MCP 服务器和 OpenAPI 目标可以通过设置来认证 Gateway 的执行角色 `outboundAuth.type` 改为 `GATEWAY_IAM_ROLE`设置 `service` 改为目标SigV4服务名称,例如 `bedrock-agentcore` 用于代理Core 运行时间或 `execute-api` 一个API网关的终点. `region` 可选; 省略时, 签名使用 Gateway 的 区域。 不需要名为 OAuth 或 API 密钥证书 .

```json
{
  "name": "runtime-tools",
  "targetType": "mcpServer",
  "endpoint": "<IAM-protected MCP endpoint URL>",
  "outboundAuth": {
    "type": "GATEWAY_IAM_ROLE",
    "service": "bedrock-agentcore",
    "region": "us-west-2"
  }
}
```

OpenAPI 目标使用相同的 `outboundAuth` 组合与它们的 `schemaSource`. 对于外部目标,赠款 用于Gateway执行任务所需的目标服务权限。 例如, Core 代理运行时需要 `bedrock-agentcore:InvokeAgentRuntime`; API 网关端点需要 `execute-api:Invoke`编辑 `service` 财务报告和审定财务报表 `region` 字段只对 `GATEWAY_IAM_ROLE`。 。 。 .

## 独立使用

这些构造可以在没有CLI的情况下独立使用. 从项目目录中构建道具 :

```typescript
import { AgentCoreApplication, readAgentCoreProject, transformAgentCoreJson } from '@aws/agentcore-cdk';

const project = readAgentCoreProject('/path/to/my-project');
new AgentCoreApplication(
  this,
  'App',
  transformAgentCoreJson(project.agentCoreJson, { projectRoot: project.projectRoot })
);
```

或直接通过一个光谱,并直接通过所需的项目根,使光谱的相对路径能够针对:

```typescript
import { AgentCoreApplication } from '@aws/agentcore-cdk';

new AgentCoreApplication(this, 'App', {
  spec: {
    name: 'myProject',
    version: 2,
    runtimes: [
      {
        name: 'myAgent',
        build: 'CodeZip',
        entrypoint: 'main.py',
        codeLocation: 'app/myAgent/',
        runtimeVersion: 'PYTHON_3_12',
      },
    ],
  },
  projectRoot: '/path/to/my-project',
});
```

## 相关软件包

-   `@aws/agentcore` - 通过CDK模板项目使用这些构造的CLI工具

## 警卫

见 [捐款](https://npmcn.com/package/%40aws/agentcore-cdk/CONTRIBUTING.md#security-issue-notifications) 更多信息.

## 许可证

这个项目根据Apache-2.0许可证获得许可证.

## 常见问题

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

Amazon Bedrock Agent Core 的 L3 CDK 构造

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

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

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

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

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

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

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

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

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

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

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

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

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

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