AgentCore Harness

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

使用方法

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

変更されるファイルを確認するためにドライランを実行することもできます

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

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

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

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

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

オプション

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

Directorypackages/<name>/
- src/PROMPT.md Harnessシステムプロンプト
- scripts/chat.ts デプロイされたHarness用のマルチターンチャットクライアント
- project.json chatターゲットを追加
- 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が使用できるツール。指定しない限り、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"
}

モジュールは3つの変数を公開します。

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プロジェクトガイドを参照してください。

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で生成されたコンストラクトを編集します。

生成されたモジュールは、ネイティブ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
Terraform

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

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

モジュールを参照する場所でモジュール引数として設定したい場合は、allowed_tools変数をモジュールに追加します。

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

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

生成されたaws_bedrockagentcore_harnessリソースのenvironment.agent_core_runtime_environmentにnetwork_configurationブロックを追加し、配置したセキュリティグループを他のリソースのルールから参照します。

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フィールド（モデル、ツール、スキルなど）に対する呼び出しごとのオーバーライドも受け入れます。フィールドがオーバーライドされていない場合は、デプロイメントデフォルトが適用されます。