@aws/ agentcore-cdk (英语)

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

安装

npm install @aws/agentcore-cdk

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

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数字 :

// 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);
}

// 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);
  }
}

三个切入点:

光谱中的每个相对路径都会与 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>),是他们目标背后的计算结果(aLambdaToolTarget<name>, (中文(简体) ), RuntimeToolTarget<name>独立 工具运行时间ToolRuntime<name>)是申请的直接子女。 创建付款管理器和连接器 下划线 Payments cid 位于堆栈范围, 构造代号为 Agent Core CLI 使用的原始模板 (单位:千美元)Payment<manager> 财务报告和审定财务报表 Payment<manager><connector>,下划线已删除),因此,一个部署模板的堆栈将保持其 资源。 这些标识绝不能改变.

一旦每种资源都存在,应用程序就将每个资源与使用资源的工作量联系在一起(见 约束代理 核心资源: 每一个运行时间的内存和网关,支付 管理器到 Python HTTP 运行时间, 每一个带的引用内存 和每一个带的网关, 每个 connections[] 输入和工具运行时间与命名它的工作量绑定.

运行时环境

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

扩展应用程序

获取资源

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

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数字 :

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。当呼叫者已经知道如何找到资源时使用这些 :

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 导入的额外关系或资源:

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);

用于项目网关 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 密钥证书 .

{
  "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的情况下独立使用. 从项目目录中构建道具 :

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 })
);

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

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工具

警卫

见 捐款 更多信息.

许可证

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