AgentCore Harness

生成一个 Amazon Bedrock AgentCore Harness 项目。Harness 是由 Strands Agents 提供支持的托管代理循环：它拥有模型、系统提示、工具、内存、技能、环境、截断、授权和执行限制的部署默认值，而服务接受支持字段的每次调用覆盖。重用相同的 Runtime Session ID 会继续相同的 Harness 会话。

用法

生成 AgentCore Harness

运行此生成器@aws/nx-plugin:agentcore-harness

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:agentcore-harness

yarn

$ yarn nx g @aws/nx-plugin:agentcore-harness

npm

$ npx nx g @aws/nx-plugin:agentcore-harness

bun

$ bunx nx g @aws/nx-plugin:agentcore-harness

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - agentcore-harness
5. 填写必需参数
6. 点击 Generate

构建你的命令6

name必需

directory

subDirectory

infra

agentcorenone

iac

inheritcdkterraform

preferInstallDependencies

false

--dry-run您还可以执行试运行以查看哪些文件会被更改

选项

生成器选项6 个选项

name必需string

AgentCore Harness 项目的名称。必须包含至少一个非空白字符，可以规范化为 kebab-case 项目名称（例如 my-harness）。

directorystring

放置 harness 项目的父目录。默认为 packages。必须是不包含父目录（..）段的相对路径。

subDirectorystring

项目放置的子目录。默认为 kebab-case 的 harness 名称。必须是不包含父目录（..）段的相对路径。

infraenum默认值: agentcore

为托管 harness 生成的基础设施类型。默认为 agentcore。选择 none 表示不托管。

agentcorenone

iacenum默认值: inherit

生成的 harness 基础设施首选的 IaC 提供商。默认为 inherit，使用为工作区配置的提供商。

inheritcdkterraform

preferInstallDependenciesboolean

是否在生成器运行后优先安装依赖项。默认为 true。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器在 packages/<name>/ 创建一个独立项目。因为 AWS 为您运行代理循环，所以该项目仅包含塑造它的提示和与之交互的脚本：

• 文件夹packages/<name>/

  • src/PROMPT.md Harness 系统提示
  • scripts/chat.ts 已部署 Harness 的多轮对话客户端
  • tsconfig.json typecheck 目标使用的 TypeScript 配置
  • project.json 添加 chat、build、lint、format 和 typecheck 目标
  • README.md 对话和自定义说明

基础设施

当 infra 为 agentcore（默认值）时生成基础设施。使用 infra: none 时不生成基础设施 — 设置 HARNESS_ARN 以调用在其他地方管理的 Harness，稍后使用 infra: agentcore 重新运行生成器以添加基础设施；现有项目文件（包括您的编辑）将被保留。

由于此生成器根据您选择的 iac 提供基础设施即代码，它将在 packages/common 中创建一个项目，其中包含相关的 CDK 构造或 Terraform 模块。

通用基础设施即代码项目的结构如下：

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ Constructs for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

此项目使用 ts#project 生成器生成，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ Terraform modules for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

此项目使用 terraform#project 生成器生成，因此配置了相同的构建目标。

CDK

• 文件夹packages/common/constructs/src/app/harnesses/<name>/

  • <name>.ts 包含 Harness 和执行角色的 CDK 构造

Terraform

• 文件夹packages/common/terraform/src/app/harnesses/<name>/

  • <name>.tf 包含 Harness 和执行角色的 Terraform 模块

生成的基础设施通过原生资源（CDK aws_bedrockagentcore.CfnHarness、Terraform aws_bedrockagentcore_harness）使用您生成的默认值管理 Harness，创建具有下述基线权限的 IAM 执行角色，并使用 IAM 入站授权（默认情况下未配置自定义 JWT 授权器）。

Harness ARN 在 运行时配置 中注册为 agentcore.harnesses.<ClassName>，保留任何现有条目。

部署您的 AgentCore Harness

生成器根据您选择的 iac 提供程序创建 CDK 或 Terraform 基础设施即代码。您可以使用它通过常规基础设施工作流部署您的 Harness。

CDK

用于部署 Harness 的 CDK 构造位于 common/constructs 文件夹中。从 CDK 应用程序实例化它：

packages/infra/src/stacks/application-stack.ts

import { MyHarness } from '@my-scope/common-constructs';
import { Stack, type StackProps } from 'aws-cdk-lib';
import type { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new MyHarness(this, 'MyHarness');
  }
}

构造的 props 接口（MyHarnessProps）扩展了 Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>，因此可以提供任何原生 Harness 属性，并优先于生成的默认值：

const harness = new MyHarness(this, 'MyHarness', {
  maxIterations: 20,
  timeoutSeconds: 600,
});

构造还接受：

• allowedTools — Harness 可以使用的工具。默认为无，请参阅配置工具。
• executionRole — 要使用的现有 IAM 角色，而不是生成的角色。提供的角色按原样使用：不会向其添加基线权限，其 ARN 始终提供给 Harness（原始 executionRoleArn 字符串无法被覆盖）。
• modelResourceArns — 生成的执行角色可以调用的 Bedrock 模型和推理配置文件 ARN，替换默认列表。
• vpc、vpcSubnets 和 securityGroups — 在 VPC 中运行 Harness，以便它可以访问私有资源，请参阅在 VPC 中运行。

其公共成员包括 harness（CfnHarness）、executionRole、grantPrincipal、harnessArn getter、connections（在 VPC 中）、用于执行角色扩展的 addToRolePolicy(statement) 以及用于授权调用者的 grantInvokeAccess(grantee)。

像往常一样使用您的基础设施项目部署堆栈 — 请参阅 CDK 基础设施指南。

Terraform

用于部署 Harness 的 Terraform 模块位于 common/terraform 文件夹中。从 Terraform 配置引用它：

packages/infra/src/main.tf

module "my_harness" {
  source = "../../common/terraform/src/app/harnesses/my-harness"
}

该模块公开以下变量：

• model_id — Harness 默认使用的 Bedrock 模型或推理配置文件。
• allowed_tools — Harness 可以使用的工具。默认为无，请参阅配置工具。
• memory — Harness 内存配置，请参阅配置内存。
• environment_variables、max_iterations、timeout_seconds — 相应的原生 Harness 字段。
• execution_role_arn — 要使用的现有 IAM 角色，而不是生成的角色。提供的角色按原样使用：既不创建角色也不创建其基线策略，因此 model_resource_arns 和 additional_execution_role_policy_statements 不能与其组合使用。
• model_resource_arns — 生成的执行角色可以调用的 Bedrock 模型和推理配置文件 ARN，替换默认列表。
• additional_execution_role_policy_statements — 附加到生成的执行角色策略的 IAM 语句对象列表（Effect、Action、Resource、可选的 Sid 和 Condition）。
• enable_vpc、vpc_id、subnet_ids — 在 VPC 中运行 Harness，以便它可以访问私有资源，请参阅在 VPC 中运行。
• tags — 应用于模块创建的资源的标签。

其他提供程序原生字段通过编辑模块本身生成的 aws_bedrockagentcore_harness 资源进行配置，请参阅自定义您的 Harness。

该模块输出 harness_id、harness_arn、execution_role_arn 和 security_group_id。

像往常一样使用 Terraform 项目的 plan/apply 工作流进行部署 — 请参阅 Terraform 项目指南。

系统提示可见性

您的基础设施在合成（CDK）或计划（Terraform）时读取 packages/<name>/src/PROMPT.md，因此提示是部署配置而不是秘密存储：其内容出现在合成的 CloudFormation 模板或 Terraform 状态中。

授予调用 harness 的访问权限

您可以按如下方式授予调用者调用 harness 的权限：

CDK

const harness = new MyHarness(this, 'MyHarness');

harness.grantInvokeAccess(caller);

Terraform

# Attach to the calling principal's role
resource "aws_iam_role_policy" "invoke_my_harness" {
  name = "InvokeMyHarness"
  role = aws_iam_role.caller.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeHarness",
        "bedrock-agentcore:InvokeAgentRuntime",
      ]
      Resource = [module.my_harness.harness_arn]
    }]
  })
}

调用者需要在 Harness ARN 上同时拥有 bedrock-agentcore:InvokeHarness 和 bedrock-agentcore:InvokeAgentRuntime，这正是 grantInvokeAccess 授予的内容。

与您的 Harness 对话

生成的 chat 目标运行 scripts/chat.ts，让您进入与已部署 Harness 的交互式终端对话：

pnpm

pnpm nx run <project>:chat

yarn

yarn nx run <project>:chat

npm

npx nx run <project>:chat

bun

bunx nx run <project>:chat

一次运行的每一轮共享一个会话，因此 Harness 会保留对话上下文直到您退出。凭证来自标准 AWS SDK 凭证提供程序链，AWS 区域从 Harness ARN 派生。

Harness ARN 按以下顺序解析：

1. HARNESS_ARN（非空）：直接使用，无需读取运行时配置：

   pnpm

   HARNESS_ARN=<harness-arn> pnpm nx run <project>:chat

   yarn

   HARNESS_ARN=<harness-arn> yarn nx run <project>:chat

   npm

   HARNESS_ARN=<harness-arn> npx nx run <project>:chat

   bun

   HARNESS_ARN=<harness-arn> bunx nx run <project>:chat

2. RUNTIME_CONFIG_APP_ID：从已部署基础设施发布的 agentcore.harnesses.<ClassName> 条目解析 ARN：

   pnpm

   RUNTIME_CONFIG_APP_ID=<application-id> pnpm nx run <project>:chat

   yarn

   RUNTIME_CONFIG_APP_ID=<application-id> yarn nx run <project>:chat

   npm

   RUNTIME_CONFIG_APP_ID=<application-id> npx nx run <project>:chat

   bun

   RUNTIME_CONFIG_APP_ID=<application-id> bunx nx run <project>:chat

如果两者都未设置，脚本将失败并显示命名两个选项的错误。

自定义您的 Harness

src/PROMPT.md 是 Harness 系统提示：编辑它并重新部署以更改 Harness 的行为。其他所有内容都在您实例化基础设施的位置配置，或通过直接编辑生成的构造或模块进行配置。重新运行生成器永远不会覆盖现有文件（它只添加缺失的文件并合并项目元数据），因此您对提示和生成的基础设施的编辑将被保留。

CDK

固定的 aws-cdk-lib/aws-bedrockagentcore 模块的每个原生 Harness 属性都可以通过构造的 props 使用 — 备用模型提供程序、工具定义、内存、技能、环境配置、截断、自定义 JWT 授权和执行限制 — 显式 props 优先于生成的默认值。或者，编辑 packages/common/constructs/src/app/harnesses/<name>/<name>.ts 中生成的构造。

Terraform

该模块的变量涵盖了大多数部署配置的字段 — model_id、allowed_tools、memory、environment_variables、max_iterations、timeout_seconds — 以及执行角色和 VPC 放置。Terraform 没有与 CDK 构造的 prop 展开等效的功能，因此其余提供程序原生字段通过编辑 packages/common/terraform/src/app/harnesses/<name>/<name>.tf 中的 aws_bedrockagentcore_harness 资源进行配置：备用模型提供程序（gemini_model_config、openai_model_config）、tool 块、skill 块、environment_artifact、environment 下的文件系统和生命周期配置、truncation 以及带有 custom_jwt_authorizer 的 authorizer_configuration。

省略授权器配置（默认）意味着 IAM 入站授权；通过原生字段配置自定义 JWT 授权器以更改该设置。

配置工具

Harness 部署时不带任何工具，因此它以最少的功能开始。选择加入它可以使用的工具：

CDK

new MyHarness(this, 'Harness', { allowedTools: ['@builtin'] });

Terraform

packages/infra/src/main.tf

module "my_harness" {
  source        = "../../common/terraform/src/app/harnesses/my-harness"
  allowed_tools = ["@builtin"]
}

将 @builtin 缩小到特定模式（如 @builtin/file_operations）以限制代理循环可以执行的操作。有关可以添加的内置工具，请参阅 Harness 工具。

配置内存

默认情况下，该服务为 Harness 提供托管内存，并且生成的执行角色被授予访问权限 — 范围限定为服务分配的内存 ARN，并且仅在 Harness 使用基础设施创建的托管内存时授予。显式配置内存以调整该托管内存、将 Harness 指向您拥有的内存资源或关闭内存：

CDK

new MyHarness(this, 'MyHarness', {
  memory: { managedMemoryConfiguration: { strategies: ['SUMMARIZATION'] } },
});

提供 memory 会完全替换默认的托管内存，因此构造会从执行角色中省略内存授权：使用 addToRolePolicy 添加配置所需的任何内容。

Terraform

module "my_harness" {
  source = "../../common/terraform/src/app/harnesses/my-harness"
  memory = {
    managed_memory_configuration = {
      strategies = ["SUMMARIZATION"]
    }
  }
}

设置 managed_memory_configuration（调整服务的托管内存）、agentcore_memory_configuration（使用您拥有的内存资源，通过 ARN）或 disabled（无内存）中的一个。选择 agentcore_memory_configuration 或 disabled 会从执行角色中删除托管内存授权；对于您自己的内存资源，通过 additional_execution_role_policy_statements 授予访问权限。

在 VPC 中运行

CDK

提供 vpc 以在其中运行 Harness，以便它可以访问私有资源（如数据库）。该构造实现了 IConnectable，因此这些资源以与其他资源相同的方式授予它访问权限：

const harness = new MyHarness(this, 'MyHarness', { vpc });

database.connections.allowDefaultPortFrom(harness, 'Harness to database');

Harness 被放置在 VPC 的具有出口的私有子网中，位于为其创建的安全组中。使用 vpcSubnets 和 securityGroups 覆盖任一项。两者都需要 vpc，并且 connections 仅在 Harness 在 VPC 中运行时可用。

Terraform

将 enable_vpc 与 vpc_id 和 subnet_ids 一起设置，以在 VPC 内运行 Harness，以便它可以访问私有资源（如数据库）：

module "my_harness" {
  source     = "../../common/terraform/src/app/harnesses/my-harness"
  enable_vpc = true
  vpc_id     = var.vpc_id
  subnet_ids = var.private_subnet_ids
}

该模块为 Harness 创建一个安全组，仅允许出站 HTTPS。其 security_group_id 输出是 Harness 必须访问的资源在其自己的入站规则中引用的内容：

resource "aws_vpc_security_group_ingress_rule" "harness_to_database" {
  security_group_id            = aws_security_group.database.id
  referenced_security_group_id = module.my_harness.security_group_id
  from_port                    = 5432
  to_port                      = 5432
  ip_protocol                  = "tcp"
  description                  = "Harness to database"
}

除非 enable_vpc 为 true，否则 security_group_id 为 null，并且当它为 true 时，vpc_id 和 subnet_ids 都是必需的。

每次调用覆盖

在基础设施中配置的值是部署默认值。该服务还接受 InvokeHarness 请求中支持的 Harness 字段（如模型、工具和技能）的每次调用覆盖；部署默认值适用于未覆盖字段的任何位置。

验证调用覆盖

每次调用覆盖是服务边界处的受信任输入：任何授权的调用者都可以覆盖支持的字段。如果不受信任的用户可以访问将覆盖转发到 InvokeHarness 的应用程序，请在应用程序层验证和授权它们（例如，允许列表模型和工具），将执行角色限定为所需资源，并且除非您特别需要，否则不要授予 bedrock-agentcore:InvokeAgentRuntimeCommand。