AgentCore Harness

Amazon Bedrock AgentCore Harnessプロジェクトを生成します。Harnessは、Strands Agentsによって駆動されるマネージドエージェントループです。モデル、システムプロンプト、ツール、メモリ、スキル、環境、トランケーション、認証、実行制限のデプロイメントデフォルトを所有し、サービスはサポートされているフィールドに対する呼び出しごとのオーバーライドを受け入れます。同じRuntime Session IDを再利用すると、同じHarnessセッションが継続されます。

使用方法

AgentCore Harnessを生成する

このジェネレーターを実行@aws/nx-plugin:agentcore-harness

CLI
VSCode

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

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

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

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

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - agentcore-harness
必須パラメータを入力
クリック Generate

コマンドを組み立てる6

name必須

オプション

ジェネレーターオプション6 オプション

name必須string: AgentCore Harnessプロジェクトの名前。少なくとも1つの空白以外の文字を含む必要があり、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がエージェントループを実行するため、プロジェクトにはそれを形成するプロンプトと、それと対話するためのスクリプトのみが含まれます。

Directorypackages/<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を呼び出すにはHARNESS_ARNを設定し、後でinfra: agentcoreでジェネレーターを再実行してインフラストラクチャを追加できます。既存のプロジェクトファイル（編集内容を含む）は保持されます。

このジェネレーターは、選択した iac に基づいてインフラストラクチャをコードとして提供するため、関連する CDK コンストラクトまたは Terraform モジュールを含む packages/common にプロジェクトを作成します。

共通のインフラストラクチャコードプロジェクトは、次のように構成されています：

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用のコンストラクト
    …
  - Directorycore/ app 内のコンストラクトによって再利用される汎用コンストラクト
    …
  - index.ts app からコンストラクトをエクスポートするエントリーポイント
- project.json プロジェクトのビルドターゲットと設定

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用の Terraform モジュール
    …
  - Directorycore/ app 内のモジュールによって再利用される汎用モジュール
    …
- project.json プロジェクトのビルドターゲットと設定

CDK
Terraform

Directorypackages/common/constructs/src/app/harnesses/<name>/
- <name>.ts Harnessと実行ロールを含むCDKコンストラクト

生成されたインフラストラクチャは、ネイティブリソース（CDK aws_bedrockagentcore.CfnHarness、Terraform aws_bedrockagentcore_harness）を通じて生成されたデフォルトでHarnessを管理し、以下で説明するベースライン権限を持つIAM実行ロールを作成し、IAMインバウンド認証を使用します（デフォルトではカスタムJWT認証は構成されません）。

Harness ARNはランタイム構成のagentcore.harnesses.<ClassName>に登録され、既存のエントリは保持されます。

AgentCore Harnessをデプロイする

ジェネレーターは、選択したiacプロバイダーに基づいてCDKまたはTerraformのインフラストラクチャコードを作成します。これを使用して、通常のインフラストラクチャワークフローを通じてHarnessをデプロイできます。

CDK
Terraform

HarnessをデプロイするためのCDKコンストラクトはcommon/constructsフォルダにあります。CDKアプリケーションからインスタンス化します。

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 — HarnessをVPC内で実行し、プライベートリソースに到達できるようにします。VPCでの実行を参照してください。

パブリックメンバーは、harness（CfnHarness）、executionRole、grantPrincipal、harnessArnゲッター、connections（VPC内）、実行ロール拡張用のaddToRolePolicy(statement)、呼び出し元を認証するためのgrantInvokeAccess(grantee)です。

通常どおりインフラストラクチャプロジェクトでスタックをデプロイします。CDKインフラストラクチャガイドを参照してください。

HarnessをデプロイするためのTerraformモジュールはcommon/terraformフォルダにあります。Terraform構成から参照します。

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 — HarnessをVPC内で実行し、プライベートリソースに到達できるようにします。VPCでの実行を参照してください。
tags — モジュールが作成するリソースに適用されるタグ。

その他のプロバイダーネイティブフィールドは、モジュール自体の生成されたaws_bedrockagentcore_harnessリソースを編集することで構成されます。Harnessのカスタマイズを参照してください。

モジュールはharness_id、harness_arn、execution_role_arn、security_group_idを出力します。

通常どおりTerraformプロジェクトのplan/applyワークフローでデプロイします。Terraformプロジェクトガイドを参照してください。

harnessを呼び出すためのアクセスを許可する

次のように、呼び出し元にharnessを呼び出す権限を付与できます。

CDK
Terraform

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

harness.grantInvokeAccess(caller);

# 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 nx run <project>:chat

yarn nx run <project>:chat

npx nx run <project>:chat

bunx nx run <project>:chat

実行の各ターンは1つのセッションを共有するため、Harnessは終了するまで会話コンテキストを保持します。認証情報は標準のAWS SDK認証情報プロバイダーチェーンから取得され、AWSリージョンはHarness ARNから派生します。

Harness ARNは次の順序で解決されます。

HARNESS_ARN（空でない場合）：ランタイム構成を読み取らずに直接使用されます。

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

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

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

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

RUNTIME_CONFIG_APP_ID：デプロイされたインフラストラクチャによって公開されたagentcore.harnesses.<ClassName>エントリからARNを解決します。

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

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

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

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

どちらも設定されていない場合、スクリプトは両方のオプションを示すエラーで失敗します。

Harnessをカスタマイズする

src/PROMPT.mdはHarnessシステムプロンプトです。編集して再デプロイすると、Harnessの動作が変更されます。その他すべては、インフラストラクチャをインスタンス化する場所、または生成されたコンストラクトまたはモジュールを直接編集することで構成されます。ジェネレーターを再実行しても既存のファイルは上書きされません（不足しているファイルの追加とプロジェクトメタデータのマージのみ）。そのため、プロンプトと生成されたインフラストラクチャへの編集は保持されます。

CDK
Terraform

固定されたaws-cdk-lib/aws-bedrockagentcoreモジュールのすべてのネイティブHarnessプロパティは、コンストラクトのpropsを通じて利用可能です。代替モデルプロバイダー、ツール定義、メモリ、スキル、環境構成、トランケーション、カスタムJWT認証、実行制限などがあり、明示的なpropsは生成されたデフォルトよりも優先されます。または、packages/common/constructs/src/app/harnesses/<name>/<name>.tsで生成されたコンストラクトを編集します。

モジュールの変数は、ほとんどのデプロイメントが構成するフィールド（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
Terraform

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

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

@builtinを@builtin/file_operationsなどの特定のパターンに絞り込んで、エージェントループができることを制限します。追加できる組み込みツールについては、Harnessツールを参照してください。

メモリの構成

サービスはデフォルトでHarness用のマネージドメモリをプロビジョニングし、生成された実行ロールにはそれへのアクセスが許可されます。サービスが割り当てるメモリARNにスコープされ、インフラストラクチャが作成したマネージドメモリをHarnessが使用している間のみ許可されます。メモリを明示的に構成して、そのマネージドメモリを調整したり、所有するメモリリソースにHarnessを向けたり、メモリをオフにしたりできます。

CDK
Terraform

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

memoryを指定すると、デフォルトのマネージドメモリが置き換えられるため、コンストラクトは実行ロールからメモリ許可を除外します。構成に必要なものをaddToRolePolicyで追加してください。

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（メモリなし）のいずれか1つを正確に設定します。agentcore_memory_configurationまたはdisabledを選択すると、実行ロールからマネージドメモリ許可が削除されます。独自のメモリリソースの場合は、additional_execution_role_policy_statementsを通じてアクセスを許可します。

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内で実行されている場合にのみ利用可能です。

enable_vpcをvpc_idおよびsubnet_idsと一緒に設定して、HarnessをVPC内で実行し、データベースなどのプライベートリソースに到達できるようにします。

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"
}

security_group_idは、enable_vpcがtrueでない限りnullであり、vpc_idとsubnet_idsはtrueの場合に両方とも必要です。

呼び出しごとのオーバーライド

インフラストラクチャで構成された値はデプロイメントデフォルトです。サービスは、InvokeHarnessリクエストでサポートされているHarnessフィールド（モデル、ツール、スキルなど）に対する呼び出しごとのオーバーライドも受け入れます。フィールドがオーバーライドされていない場合は、デプロイメントデフォルトが適用されます。