AWS Bedrock AgentCore CLI / Managed Harness 使い方｜CDK・Terraform・3 API call徹底ガイド

AgentCore Managed Harnessは、モデル・システムプロンプト・ツールを「設定」として宣言するだけで、オーケストレーションコードを一切書かずにAIエージェントを動かせる仕組みです。SDKやAWS CLIから最小で動かすなら、覚えるのは CreateHarness（作成）→ GetHarness（READY確認）→ InvokeHarness（実行）の3 API callだけです。

AgentCore CLI（@aws/agentcore）を使えば、同じことが agentcore create → agentcore deploy → agentcore invoke の3コマンドで完結します。従来は各チームが自前で組んでいたエージェントループ（推論→ツール選択→実行→応答のストリーミング）を、AWSがフルマネージドで肩代わりするのがハーネスの価値です。

この記事では、AgentCore CLIのインストールからデプロイ、Managed Harnessの「3 API call」と全パラメータ、CDK・Terraformによるインフラ管理、IAMセキュリティ、料金試算、そして対応リージョンとプレビュー/GAの最新ステータスまで、導入判断と実装に必要な情報を整理します。

この記事でわかること

• 「3 API call」の最小フロー（CreateHarness → GetHarness → InvokeHarness）と全パラメータ
• AgentCore CLI（@aws/agentcore）のインストール〜プロジェクト作成〜デプロイの流れ
• CDK（@aws-cdk/aws-bedrock-agentcore-alpha）と Terraform を横並びで比較した使い方と注意点
• 料金の全体像（ハーネス自体は無料・下回りリソース従量）と月額試算
• 対応リージョン・プレビュー/GAステータス・IAM設定・トラブルシューティング

対象読者: AWS上でAIエージェントを構築・デプロイしたいエンジニア、AgentCore CLI / Managed Harnessを評価・検討している方。

出典: Unsplash

AgentCore CLI と Managed Harness とは

Amazon Bedrock AgentCoreは、AIエージェントを構築・デプロイ・運用するためのAWSマネージドプラットフォームです。Runtime / Gateway / Memory / Identity / Code Interpreter / Browser / Observability / Evaluations / Policy / Registry といったコンポーネントで構成され、2025年に一般提供（GA）が始まりました。

その上に2026年4月22日に追加されたのが、AgentCore CLI と Managed Harness（マネージドエージェントハーネス） です。これらは「エージェントを動かすための土台一式（ハーネス）」をAWSが肩代わりすることで、立ち上げにかかる時間を大幅に短縮します。

AgentCore CLI（@aws/agentcore）

npmパッケージ @aws/agentcore として公開されているCLIツールで、GitHubリポジトリは aws/agentcore-cli です。Python製の旧ツール bedrock-agentcore-starter-toolkit の後継にあたり、新規プロジェクトでは新CLIの利用が推奨されています。

主な特徴:

• スキャフォールド（agentcore create）→ ローカルテスト（agentcore dev）→ AWSデプロイ（agentcore deploy）→ 実行（agentcore invoke）まで一貫したワークフロー
• フレームワーク非依存（Strands Agents / LangChain / LangGraph / Google ADK / OpenAI Agents SDK / CrewAI など）
• マルチモデル対応（Amazon Bedrock / Anthropic / OpenAI / Google Gemini / LiteLLM互換プロバイダ）
• CLI 本体は GA。発表時点で14リージョンに対応

Managed Harness（マネージドエージェントハーネス）

Managed Harnessは「コードをほぼ書かずにエージェントを動かすための実行環境」です。モデル・システムプロンプト・ツール・スキルを設定として指定するだけで、推論 → ツール選択 → アクション実行 → 応答ストリーミングのループを自動管理します。「モデルを変える」「ツールを足す」がコードの書き換えではなく設定変更で済むのが最大の価値です。

• ハーネスはAWSのオープンソースエージェントフレームワーク Strands Agents 上で動作します。
• 各セッションは独立した Firecracker microVM で分離実行され、専用のファイルシステムとシェルを持ちます。
• 短期・長期メモリとファイルは、microVMセッションが入れ替わってもセッション横断で保持できます。
• モデル未指定時の既定は Anthropic Claude Sonnet 4.6（on Amazon Bedrock） です（公式ドキュメント記載値。バージョンは更新される可能性があるため公開時点の公式表記を確認してください）。

プレビュー/GAと対応リージョン（最新ステータス）

Managed Harnessのステータスは公開時期によって表記が異なるため、整理しておきます。

発表当初はPreview・4リージョン限定でしたが、2026年6月時点の公式ハーネスドキュメントでは「GA・全リージョン対応」と記載されており、PreviewからGAへ移行した可能性が高い状況です。東京リージョン（ap-northeast-1）も、発表当初は非対応でしたが、GA・全リージョン化により対応している可能性があります。 リージョン対応とGAステータスは更新が速いため、実装前に必ずAWS公式のリージョン対応ページとAgentCore harnessドキュメントで最新表記を確認してください。

「3 API call」の仕組みと全パラメータ

Managed HarnessをSDK / AWS CLIから動かす最小フローは、次の3つのAPIで完結します。これが記事タイトルにある「3 API call」の正体です。

出典: Unsplash

不要になったら DeleteHarness で削除します（後片付け）。各APIを具体的に見ていきます。

① CreateHarness — ハーネスの作成

ハーネスを定義・作成します。最小では名前と実行ロールARNを渡すだけです。

aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole"

必須パラメータ:

主なオプションパラメータ:

テスト時の推奨設定（コスト暴走防止）: 開発・テスト段階では maxIterations と timeoutSeconds を小さめに設定することを強く推奨します。ループするエージェントが無制限に実行されると、従量課金が膨らむリスクがあります。

② GetHarness — READY確認とARN取得

作成したハーネスは即座に呼び出せるわけではなく、status が READY になるまで待つ必要があります。GetHarness でステータスをポーリングし、READY になったら arn を取得して次の InvokeHarness に渡します。

aws bedrock-agentcore-control get-harness \
  --harness-id "MyHarness-XyZ123"
# status が "READY" になるまで数十秒〜ポーリング

CLIを使う場合、この「作成→READY確認」は agentcore deploy がまとめて面倒を見てくれます。agentcore status でも状態を確認できます。

③ InvokeHarness — ハーネスの実行

READY になったハーネスにメッセージを送り、エージェントを実行します。応答はストリーミングで返ります。

Python（boto3）での実行例:

import boto3

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = client.invoke_harness(
    harnessArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:harness/MyHarness-XyZ123",
    runtimeSessionId="1234abcd-12ab-34cd-56ef-1234567890ab",  # UUID推奨（33文字以上必須）
    messages=[{
        "role": "user",
        "content": [{"text": "東京の明日の天気を調べて教えてください。"}]
    }],
)

# ストリーミングレスポンス処理
for event in response["stream"]:
    if "contentBlockDelta" in event:
        delta = event["contentBlockDelta"].get("delta", {})
        if "text" in delta:
            print(delta["text"], end="", flush=True)

runtimeSessionId は最小長33文字以上という制約があります。同じ会話・同じ環境を継続したい場合は同一のセッションIDを再利用します。UUID（import uuid; str(uuid.uuid4())）を使うのが確実です。

ストリーミングイベントの種類:

stopReason には end_turn / tool_use / max_tokens / max_iterations_exceeded / timeout_exceeded / max_output_tokens_exceeded などがあります。

CLI経由での実行（モデルの一時オーバーライドも可能）:

# 通常実行
agentcore invoke --harness MyHarness \
  --session-id "$(uuidgen)" \
  "Code Interpreterで121 + 23133を計算して"

# 実行時にモデルを一時的に切り替え（再デプロイ不要）
agentcore invoke --harness MyHarness \
  --model-id us.anthropic.claude-haiku-4-5-20251001-v1:0 \
  "Code Interpreterで121 + 23133を計算して"

create時に指定した設定は、invoke時に上書き（per-invocationオーバーライド）できます。価格性能比のテストやモデル切り替えを、再デプロイなしで試せるのが便利な点です。

④ DeleteHarness — ハーネスの削除（後片付け）

不要になったハーネスを削除します。

aws bedrock-agentcore-control delete-harness \
  --harness-id "MyHarness-XyZ123"

⚠️ 自動生成IAMロールの後始末: ハーネス作成時に自動生成される AmazonBedrockAgentCoreHarnessDefaultServiceRole は、ハーネス削除後もAWSアカウントに残る場合があります。不要になったら手動でIAMコンソールから確認・削除してください。

このほか、ライフサイクル管理用に UpdateHarness / ListHarnesses / ListHarnessVersions、エンドポイント管理用に CreateHarnessEndpoint / UpdateHarnessEndpoint / DeleteHarnessEndpoint などのAPIが用意されています。イミュータブルなバージョンと名前付きエンドポイントを組み合わせることで、エンドポイントを過去バージョンに向けるだけで即時ロールバックできます。

AgentCore CLI 実践ガイド（インストール〜デプロイ）

出典: aws/agentcore-cli（GitHub）

CLI経由なら、3 API callに相当する流れを対話形式で進められます。大半の開発者にとって最速の経路です。

前提条件

• Node.js 20以上（CLI本体の要件。CDKデプロイ部分は18以上で動作する構成もあるため、20以上にしておくと安全）
• AWSアカウント・AWSクレデンシャル設定済み（aws configure）
• 初回デプロイには cdk bootstrap が必要（数分かかる）

インストール

npm install -g @aws/agentcore
agentcore --version  # バージョン確認

プロジェクト作成（agentcore create）

agentcore create my-agent

対話型ウィザードが起動し、以下を選択できます。

• エージェントフレームワーク（Strands Agents 推奨）
• モデルプロバイダー（--model-provider: Amazon Bedrock / Anthropic / OpenAI / Google Gemini）
• プロトコル（--protocol: HTTP / MCP / A2A）
• ビルドタイプ（--build: CodeZip / Container）
• --with-invoke-script を付けると invoke.py が自動生成される

harness.json によるハーネス設定の例:

{
  "harnessName": "MyAgent",
  "systemPrompt": "あなたは役に立つアシスタントです。",
  "modelId": "us.anthropic.claude-sonnet-4-6",
  "tools": [
    { "type": "agentcore_code_interpreter" }
  ],
  "maxIterations": 10,
  "timeoutSeconds": 300
}

modelId を変更するだけでモデルの切り替えが可能で、再デプロイは不要です（設定の変更が動的に適用されます）。

ローカル開発（agentcore dev）

cd my-agent
agentcore dev

ホットリロード対応のローカル開発サーバーが起動し、AWSにデプロイする前にローカルで動作確認できます。

ツール追加（agentcore add）

# ブラウザツールの追加
agentcore add tool --type agentcore_browser

# メモリの追加
agentcore add memory

# Gateway（外部API連携）の追加
agentcore add gateway

AWSデプロイ（agentcore deploy）

agentcore deploy

内部的にCDK（@aws-cdk/aws-bedrock-agentcore-alpha）を使用してデプロイします。初回は cdk bootstrap が自動的に実行されます。

ビルドタイプの選択基準:

ARM64（Graviton）の注意: AgentCore Runtimeは内部でGravitonアーキテクチャを使用します。Containerビルドを使う場合は Platform.LINUX_ARM64 を指定し、依存ライブラリをARM64向けにコンパイルする必要があります。x86用バイナリをそのまま使うとサイレントに失敗するケースがあるため、uv などを使ったターゲットビルドが有効です。

デプロイ済みエージェントの管理

agentcore logs      # ログ確認
agentcore traces    # トレース確認（Observabilityと連携）
agentcore status    # デプロイ状況確認
agentcore remove    # リソース削除
agentcore update    # CLI自体のアップデート

CDK と Terraform を横並び比較

AgentCoreのインフラをコードで管理する選択肢は、現状CDKとTerraformで成熟度が異なります。導入前に両者の前提・対応状況を把握しておきましょう。

両者ともに「公式の最新提供範囲」を実装前に確認することを推奨します。CDKは公式が即日対応した一方、Terraformは提供拡大の途上にあります。

CDK でのデプロイ詳細

出典: Unsplash

agentcore deploy の内部で使われるCDKパッケージ @aws-cdk/aws-bedrock-agentcore-alpha を直接使い、より細かい制御を行うこともできます。

⚠️ エクスペリメンタル段階: このパッケージはAPIが後方互換性なしに変更される可能性があります。本番環境への適用は慎重に判断してください。

CDK L2コンストラクトの例（TypeScript）:

import * as agentcore from '@aws-cdk/aws-bedrock-agentcore-alpha';
import { App, Stack } from 'aws-cdk-lib';
import * as ecr from 'aws-cdk-lib/aws-ecr';

const app = new App();
const stack = new Stack(app, 'MyAgentCoreStack');

const repository = ecr.Repository.fromRepositoryName(
  stack,
  'AgentRepo',
  'my-agent-repo'
);

// ECRリポジトリからArtifactを指定
const artifact = agentcore.AgentRuntimeArtifact.fromEcrRepository(
  repository,
  'v1.0.0'
);

// AgentCore Runtimeを作成
const runtime = new agentcore.Runtime(stack, 'MyAgentRuntime', {
  artifact,
  // 認証設定（IAM、Cognito、JWT、OAuthから選択）
  authorizationConfig: {
    type: agentcore.AuthorizationType.IAM,
  },
});

app.synth();

Runtime作成の4つのアーティファクト指定方法:

hotswapによるデプロイ高速化: コード変更のみのデプロイには cdk deploy --hotswap を使うと、CloudFormationスタック全体を更新せずAWS SDKを直接呼び出すため時間を大幅に短縮できます。

Terraform での対応状況

出典: Unsplash

TerraformとAgentCoreの関係は2段階に分けて理解する必要があります。

(A) AgentCore CLI の Terraform 出力: 現時点では未対応です。agentcore deploy はCDKのみに対応しており、Terraform出力は「近日対応予定」となっています。

(B) AWSプロバイダーによる低レベルリソース管理: hashicorp/aws プロバイダー v6.32以上で、AgentCoreのリソースを直接Terraformで管理できます。

対応リソース一覧（provider ~> 6.32）:

Terraform実装例（Runtime）:

resource "aws_bedrockagentcore_agent_runtime" "my_agent" {
  agent_runtime_name = "my-terraform-agent"
  description        = "Terraformで管理するAgentCore Runtime"

  agent_runtime_artifact {
    s3_location {
      uri = "s3://my-bucket/agent-code.zip"
    }
    runtime      = "python3.12"
    entry_point  = "main.handler"
  }

  network_configuration {
    network_mode = "PUBLIC"
  }

  execution_role_arn = aws_iam_role.agentcore_execution.arn
}

Terraform実装の注意点:

• GatewayターゲットのregistrationはAWS CLIワークアラウンドが必要: 現時点のプロバイダーには制限があり、GatewayターゲットのregistrationとPolicyエンジン管理は null_resource + local-exec でAWS CLIを呼ぶワークアラウンドが必要なケースがあります。
• ARM64向けコンパイル: Graviton向けに依存ライブラリを事前コンパイルが必要です（uv で --python-platform linux_aarch64 を指定）。
• コード変更時の再デプロイ管理: ソースコードのハッシュ（filemd5(...)）を環境変数として注入し、変更検知で再デプロイを起こすパターンが有効です。

料金の全体像と試算

Managed HarnessとAgentCore CLI自体には追加料金はかかりません。 消費した下回りのAgentCoreリソースのみに課金されます（前払いなし・最小利用料なし・I/O待機時間は非課金）。これは「ハーネスを使うこと自体は無料、実行に使ったRuntimeやMemoryに従量課金」という構造です。

出典: Unsplash

主要サービスの料金一覧（2026年6月時点・公式pricing参照）

単価は変動する可能性があるため、最新はAgentCore pricing公式ページで確認してください。

Runtime等は秒単位課金・セッションあたり最低128MBです。Identityは Runtime / Gateway 経由なら無料です。新規AWS顧客には最大 $200のFree Tierクレジット、Agent Registryには月次無料枠（5,000レコード / 100万Searchコール / 200万 Get+Listコール）があります。

月額試算（参考）

ライトユーザー（評価・プロトタイプ目的）:

• Runtime: 1 vCPU × 10時間/月 = $0.895
• Code Interpreter: 1 vCPU × 2時間/月 = $0.179
• Gateway: 1,000呼び出し/月 = $0.005
• 合計: 約$1.1/月

本番運用（1日あたり100セッション程度）:

• Runtime: 4 vCPU × 100時間/月 = $35.8
• Memory短期: 100,000イベント/月 = $25
• Gateway: 50,000呼び出し/月 = $0.25
• Evaluations: 10,000,000トークン/月 = $24
• 合計: 約$85/月（モデル呼び出し費用は別途）

注意: モデル呼び出し料金（Bedrock等のトークン課金）は、この試算には含まれません。実際のコストはエージェントのループ回数・使用ツール・セッション時間で大きく変動します。長時間セッションや大きいメモリ確保はコスト増に直結するため、maxIterations / timeoutSeconds の設定でガードを掛けるのが基本です。

IAMセキュリティ設定

Managed Harnessを動かすには、ハーネスがassumeする適切なIAM実行ロールが必要です。最小権限で構成するのが原則です。

Trust Policy（信頼ポリシー）

AgentCoreサービスがIAMロールを引き受けられるよう、bedrock-agentcore.amazonaws.com を許可します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

アクセスポリシー（Bedrock呼び出し + CloudWatchログ）

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:*"
    }
  ]
}

IAM APIアクション対応表

機能別の追加権限

SigV4（IAM）vs Inbound OAuth の使い分け

エンドユーザーごとに異なる権限でエージェントを実行させたい場合は、IAM認証ではなくInbound OAuthの設定が必要です。microVMによるセッション単位の分離により、マルチテナントでも安全性が担保されます。

制約・注意点まとめ

実装前に把握しておくべき制約を整理します。

トラブルシューティング

ConflictException: 同名のハーネスが存在する

harnessName が既存のハーネスと重複しています。別名を指定するか、既存を削除してから再実行します。

aws bedrock-agentcore-control list-harnesses
aws bedrock-agentcore-control delete-harness --harness-id "HarnessId"

ValidationException: runtimeSessionIdが短すぎる

runtimeSessionId は33文字以上必要です。UUIDに変更してください。

import uuid
session_id = str(uuid.uuid4())  # 36文字のUUID

ThrottlingException: リクエスト数超過

エクスポネンシャルバックオフを実装してリトライします。本番ではリクエスト上限の緩和申請も検討してください。

ARM64ライブラリが読み込めない

Containerビルドでx86用バイナリを使っている可能性があります。ARM64向けにビルドし直します。

uv pip install -r requirements.txt \
  --python-platform linux_aarch64 \
  --target ./package

cdk bootstrap が必要なエラー

初回デプロイ時にbootstrapが必要です。

cdk bootstrap aws://123456789012/us-west-2

こんな用途に向いています / 向いていません

向いているケース

• プロトタイプを素早く作りたい: オーケストレーションコードを書かずに動作確認でき、要件検証に最適
• フレームワークを後から決めたい: フレームワーク非依存で始められる
• マルチモデルで試したい: modelId を変えるだけ、あるいはinvoke時のオーバーライドでモデルを切り替えられる
• セッション分離が必要な本番環境: Firecracker microVMによる強力な分離が標準で提供される
• IaC（CDK）でインフラ管理したい: TypeScriptでインフラをコード化し、既存CDKスタックに統合できる

おすすめしない・注意すべきケース

• TerraformのみでIaC管理している組織: AgentCore CLIのTerraform出力は未対応。CDK受け入れか、AWSプロバイダーでの低レベル管理が必要
• CDKの破壊的変更を許容できない本番環境: @aws-cdk/aws-bedrock-agentcore-alpha はエクスペリメンタルで後方互換性の保証なし
• レイテンシが極めてシビアな用途: コールドスタートに最大30秒かかる場合がある
• 完全にカスタムなオーケストレーションが必須: 設定だけでは表現できない制御は、StrandsコードへエクスポートしてRuntime上で動かす設計が必要
• 特定リージョン・GA要件が厳格な案件: Managed Harnessのステータスとリージョン対応は更新が速いため、稟議前に公式の最新表記を必ず確認すること

よくある質問（FAQ）

Q. 旧ツール bedrock-agentcore-starter-toolkit からの移行は必要ですか？

A. 既存プロジェクトで動いていれば即時移行は必須ではありませんが、新規では @aws/agentcore（AgentCore CLI）の利用が推奨されます。旧ツールはLegacy扱いとなり、今後のアップデートは新CLIが主体になると見込まれます。

Q. Managed Harnessは本番利用できますか？

A. 発表当初はPreviewでしたが、2026年6月時点の公式ドキュメントではGA表記となっています。ステータスとリージョン対応は更新が速いため、本番投入前に公式ハーネスドキュメントとリージョンページで最新状況を確認してください。

Q. AgentCore CLIと、CDKを自分で書くのはどちらが良いですか？

A. 素早く始めるならCLIが便利です。認証・ネットワークを細かく制御したい、既存CDKスタックに統合したい場合は、CDK L2コンストラクト（@aws-cdk/aws-bedrock-agentcore-alpha）を直接使うほうが柔軟です。

Q. AgentCore Skillsとは何ですか？

A. Git・S3・キュレーション済みカタログなどのスキルをトグルで付与できる機能、およびKiro・Claude Code・OpenAI Codex・Cursor等のコーディングアシスタントからAgentCore Managed Harnessを使えるようにする事前定義スキルのバンドルです。2026年4月22日にKiroが即日対応し、他のアシスタントは順次対応が進められています。

Q. PrivateLinkでの接続はサポートされていますか？

A. 公式ではPrivateLinkのサポートが記載されています。VPC内のプライベートリソースへのアクセスは environment パラメータのVPC設定で対応できます。

Q. コンプライアンス要件がある場合に使えますか？

A. ISO / SOC / HIPAA に対応済みとされ、その他の規格にも準拠が進んでいます。個別要件については、AWS公式のコンプライアンスドキュメントで最新の対応状況を確認してください。

関連リソース

• Amazon Bedrock AgentCoreの土台となるAIエージェントの全体像は、AIエージェントとは？仕組み・種類・導入事例を整理で解説しています。
• AIエージェントのフレームワーク選択はAIエージェント フレームワーク比較も参考にしてください。
• AIエージェントのセキュリティ設計はAIエージェント セキュリティ対策ガイドで整理しています。
• AgentCore Gatewayが採用するMCPについてはMCPとは（Model Context Protocol）をご覧ください。
• AWSとAIインフラの提携動向はOpenAI × AWS パートナーシップでまとめています。

まとめ

Managed HarnessとAgentCore CLIは、AIエージェント開発の立ち上げコストを大きく下げるAWSの取り組みです。覚えるべき最小フローは「Create → Get → Invoke」の3 API call。プレビュー/GAステータス、対応リージョン、CDKのエクスペリメンタル段階、Terraform未対応という現時点の制約を公式で確認したうえで、プロジェクトの要件と照らし合わせて導入を判断してください。