AgentCore Harness

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

用法

生成 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

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

pnpm

pnpm nx g @aws/nx-plugin:agentcore-harness --dry-run

yarn

yarn nx g @aws/nx-plugin:agentcore-harness --dry-run

npm

npx nx g @aws/nx-plugin:agentcore-harness --dry-run

bun

bunx nx g @aws/nx-plugin:agentcore-harness --dry-run

VSCode

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

选项

参数	类型	默认值	描述
name 必需	string	-	AgentCore Harness 项目的名称。必须包含至少一个非空白字符，可以规范化为 kebab-case 项目名称（例如 my-harness）。
directory	string	-	放置 harness 项目的父目录。默认为 packages。必须是不包含父目录（..）段的相对路径。
subDirectory	string	-	项目放置的子目录。默认为 kebab-case 的 harness 名称。必须是不包含父目录（..）段的相对路径。
infra	agentcore | none	agentcore	为托管 harness 生成的基础设施类型。默认为 agentcore。选择 none 表示不托管。
iac	inherit | cdk | terraform	inherit	生成的 harness 基础设施首选的 IaC 提供商。默认为 inherit，使用为工作区配置的提供商。
preferInstallDependencies	boolean	-	是否在生成器运行后优先安装依赖项。默认为 true。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

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

• 文件夹packages/<name>/

  • src/PROMPT.md Harness 系统提示
  • scripts/chat.ts 已部署 Harness 的多轮对话客户端
  • project.json 添加 chat 目标
  • 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 可以使用的工具。除非您提供工具，否则 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 模型或推理配置文件。
• model_resource_arns — 执行角色可以调用的 Bedrock 模型和推理配置文件 ARN，替换默认列表。
• additional_execution_role_policy_statements — 附加到执行角色策略的 IAM 语句对象列表（Effect、Action、Resource、可选的 Sid 和 Condition）。

其他所有内容都在模块本身生成的 aws_bedrockagentcore_harness 资源上配置。

该模块输出 harness_id、harness_arn 和 execution_role_arn。

像往常一样使用 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

生成的模块保持原生 aws_bedrockagentcore_harness 资源直接可编辑，因此提供程序原生字段 — 备用模型提供程序（gemini_model_config、openai_model_config）、tool 块、memory、skill 块、环境（environment、environment_variables、environment_artifact）、truncation 和带有 custom_jwt_authorizer 的 authorizer_configuration — 通过编辑 packages/common/terraform/src/app/harnesses/<name>/<name>.tf 进行配置。

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

配置工具

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

CDK

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

Terraform

packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf

resource "aws_bedrockagentcore_harness" "this" {
  # ...
  allowed_tools = ["@builtin"]
}

如果您希望在引用模块的位置将其设置为模块参数，请向模块添加 allowed_tools 变量。

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

在 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

将 network_configuration 块添加到生成的 aws_bedrockagentcore_harness 资源的 environment.agent_core_runtime_environment，然后从其他资源的规则中引用您放置它的安全组：

packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf

resource "aws_security_group" "harness" {
  vpc_id = var.vpc_id
}

resource "aws_bedrockagentcore_harness" "this" {
  # ...
  environment {
    agent_core_runtime_environment {
      network_configuration {
        network_mode = "VPC"
        network_mode_config {
          security_groups = [aws_security_group.harness.id]
          subnets         = var.subnet_ids
        }
      }
    }
  }
}

每次调用覆盖

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

验证调用覆盖

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