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

Managed Harnessは、モデル・システムプロンプト・ツールを指定するだけで、オーケストレーションコードをゼロで書かずにAIエージェントを動かせる仕組みで、必要なAPIは CreateHarness / InvokeHarness / DeleteHarness の3つだけです。

2026年4月22日にプレビューとして公開されたAmazon Bedrock AgentCore CLIとManaged Harnessは、AIエージェント開発の立ち上げにかかる時間を大幅に短縮するAWSの新機能です。従来は複雑なオーケストレーションコードが必要だったエージェントループを自動管理するManaged Harnessと、スキャフォールド〜デプロイを一貫して行うAgentCore CLIが組み合わさり、数分でエージェントを動かせるようになりました。

この記事では、AgentCore CLIのインストールから実際のデプロイ方法、Managed Harnessの3 API callsの詳細パラメータ、CDK・Terraformによるインフラ管理、IAMセキュリティ設定、料金試算まで、導入判断と実装に必要な情報を整理します。

この記事でわかること:

• AgentCore CLI（@aws/agentcore）のインストールとプロジェクト作成〜デプロイの流れ
• Managed Harnessの3 API calls（CreateHarness・InvokeHarness・DeleteHarness）の全パラメータ
• CDKデプロイ（@aws-cdk/aws-bedrock-agentcore-alpha）の使い方と注意点
• Terraformの現在の対応状況（CLIは未対応・AWSプロバイダーでのリソース管理は可能）
• リージョン制限（東京非対応）・料金・IAMロール設定・トラブルシューティング

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

出典: Amazon Bedrock AgentCore 公式サイト

AgentCoreとManaged Harnessとは

Amazon Bedrock AgentCoreは、AIエージェントを構築・デプロイ・運用するためのAWSマネージドプラットフォームです。Runtime / Gateway / Memory / Identity / Code Interpreter / Browser / Observability / Evaluations / Policy / Registry の10サービスで構成され、2025年10月にGAしました。

その中で2026年4月22日に追加されたのが、AgentCore CLIとManaged Harness（マネージドエージェントハーネス）です。

AgentCore CLI（@aws/agentcore）

npmパッケージ @aws/agentcore として公開されているCLIツールで、GitHubリポジトリは aws/agentcore-cli です。旧ツール bedrock-agentcore-starter-toolkit（Python製）の後継で、現時点ではLegacy扱いになっています。

主な特徴:

• エージェントのスキャフォールド（agentcore create）からローカルテスト（agentcore dev）・AWSデプロイ（agentcore deploy）まで一貫したワークフロー
• フレームワーク非依存（Strands Agents / LangChain / LangGraph / Google ADK / OpenAI Agents SDK / CrewAI等に対応）
• マルチモデル対応（Amazon Bedrock / Anthropic / OpenAI / Google Gemini）
• 現時点で14リージョン対応

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

Managed Harnessは「コードをほぼ書かずにエージェントを動かすための実行環境」です。モデル・システムプロンプト・ツールを設定ファイルで指定するだけで、推論→ツール選択→アクション実行→応答ストリーミングのループを自動管理します。

各セッションはFirecracker microVMで分離実行され、セッション完了後にメモリが消去されます。2026年5月時点でプレビュー段階のため、APIや動作は変更される可能性があります。

Managed Harness対応リージョン（2026年5月現在）:

⚠️ 東京リージョン（ap-northeast-1）は現時点で非対応。 AgentCore CLIとRuntime自体は14リージョンで使用可能ですが、Managed Harnessを使う場合は上記4リージョンのいずれかを選択する必要があります。

3 API callsの仕組みと全パラメータ

Managed Harnessを動かすためのAPIは3つだけです。

① CreateHarness — Harnessの作成

Harnessを定義・作成します。

AWS CLIでの実行例:

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

必須パラメータ:

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

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

② InvokeHarness — Harnessの実行

作成したHarnessにメッセージを送り、エージェントを実行します。ストリーミング応答に対応しています。

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)

boto3の最低バージョン: 公式情報として 1.42.94 以上が必要と報告されています（最新のドキュメントで確認を推奨）。

runtimeSessionId の注意: 最小長が33文字以上という制約があります。UUID（import uuid; str(uuid.uuid4())）を使うのが確実です。

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

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を計算して"

③ DeleteHarness — Harnessの削除

不要になったHarnessを削除します。

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

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

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

前提条件

• Node.js 24以上（nvm等でバージョン管理推奨）
• 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 によるHarness設定の例:

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

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

ローカル開発（agentcore dev）

cd my-agent
agentcore dev

ホットリロード対応のローカル開発サーバーが起動します。ローカルでエージェントの動作確認が可能です。

ツール追加（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

# トレース確認（Observabilityと連携）
agentcore traces

# デプロイ状況確認
agentcore status

# リソース削除
agentcore remove

# CLI自体のアップデート
agentcore update

CDK でのデプロイ詳細

出典: Amazon Bedrock AgentCore 公式サイト

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つのアーティファクト指定方法

CDK hotswap によるデプロイ高速化

# 通常デプロイ（CloudFormationスタック全体）
cdk deploy

# hotswapデプロイ（AgentCore Runtime対応、AWS SDKを直接呼び出すため高速）
cdk deploy --hotswap

2026年からCDKの hotswap デプロイがAgentCore Runtimeに対応しました。コード変更のみのデプロイにはhotswapを使うと時間を大幅に短縮できます。

Terraform での対応状況

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

AgentCore CLI の Terraform 対応

現時点（2026年5月）では未対応です。 agentcore deploy コマンドはCDKのみに対応しており、Terraform出力は「近日対応予定」となっています。Terraformによるインフラ管理を前提とする場合は注意が必要です。

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ワークアラウンドが必要

現時点のTerraformプロバイダーには制限があり、GatewayターゲットのregistrationとPolicyエンジン管理は null_resource ブロック + AWS CLIスクリプトでのワークアラウンドが必要なケースがあります。

resource "null_resource" "register_gateway_target" {
  provisioner "local-exec" {
    command = "aws bedrock-agentcore-control register-gateway-target --gateway-id ${aws_bedrockagentcore_gateway.main.id} ..."
  }
  depends_on = [aws_bedrockagentcore_gateway_target.main]
}

② ARM64向けコンパイル

Gravitonアーキテクチャ向けに依存ライブラリを事前コンパイルが必要です。uv を使って --target-platform linux/arm64 を指定するのが有効です。

③ コード変更時の再デプロイ管理

コード変更のたびにRuntimeを再デプロイするには、ソースコードのハッシュを環境変数として注入するパターンが有効です。

resource "aws_bedrockagentcore_agent_runtime" "my_agent" {
  # ...
  environment {
    name  = "CODE_HASH"
    value = filemd5("${path.module}/agent-code.zip")
  }
}

料金の全体像と試算

Managed HarnessとAgentCore CLI自体には追加料金はかかりません。消費した実際のリソースのみに課金されます。前払いなし、最小利用料なし。I/O待機時間は非課金です。

主要サービスの料金一覧

月額試算（参考）

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

• 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等）は上記に含まれません。実際のコストはエージェントのループ回数・使用ツールによって大幅に変動します。

IAMセキュリティ設定

Managed Harnessを動かすには、適切なIAMロール設定が必要です。

Trust Policy（信頼ポリシー）の設定

AgentCoreサービスがIAMロールを引き受けられるよう、Trust Policyで 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の設定が必要です。

制約・注意点まとめ

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

トラブルシューティング

よくあるエラーと対処

ConflictException: 同名のHarnessが存在する

harnessName が既存のHarnessと重複しています。別名を指定するか、既存のHarnessを削除してから再実行してください。

# 既存Harness一覧確認
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: リクエスト数超過

エクスポネンシャルバックオフを実装してリトライしてください。本番環境ではリクエスト数の上限をAWSサポートに緩和申請することも検討してください。

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

Containerビルドでx86用バイナリを使っている可能性があります。以下のコマンドでARM64向けにビルドし直してください。

# uvを使ったARM64向けビルド
uv pip install -r requirements.txt \
  --python-platform linux_aarch64 \
  --target ./package

cdk bootstrap が必要なエラー

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

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

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

AgentCore CLI + Managed Harnessが向いているケース

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

おすすめしない・注意すべき状況

• 東京リージョン必須の案件: Managed Harnessは東京非対応（2026年5月現在）。AgentCore Runtime単体なら東京でも利用可能
• TerraformのみでIaC管理している組織: AgentCore CLIのTerraform出力は未対応。CDK受け入れかAWSプロバイダーでの低レベル管理が必要
• CDKの破壊的変更を許容できない本番環境: @aws-cdk/aws-bedrock-agentcore-alpha はエクスペリメンタルで後方互換性の保証なし
• レイテンシが極めてシビアな用途: Firecracker microVMのコールドスタートに最大30秒かかる場合がある
• 既存エージェントフレームワークに深く依存している: 既存のLangGraphグラフ等を大きく変更したくない場合は、CDK L2コンストラクトで直接Runtimeを管理する方が柔軟

よくある質問（FAQ）

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

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

Q. Managed Harnessはプレビュー段階ですが、本番利用できますか？

A. プレビュー段階はAPIや動作仕様が変更される可能性があります。重要な本番システムへの適用は、GA（一般提供）を待つか、変更に対応できる体制を整えた上で進めることを推奨します。

Q. AgentCore CLIとボトムアップでCDKを書く場合、どちらが良いですか？

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

Q. AgentCore Skillsとは何ですか？

A. Kiro・Claude Code・OpenAI Codex・Cursor等のコーディングアシスタントがAgentCore Managed Harnessを使えるようにする事前定義スキルのバンドルです。2026年4月22日にKiroが即日対応し、Claude Code・OpenAI Codex・Cursorは翌週以降の対応予定として発表されました。

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

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

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

A. ISO / SOC / HIPAA に対応済みです。FedRAMPは準備中、C5・CISPE・PCI等の規格に準拠しています。ただし個別の要件については、AWS公式のコンプライアンスドキュメントを確認してください。

関連リソース

• Amazon Bedrock AgentCoreの全体像については、AIエージェントとは？仕組み・種類・導入事例を整理で詳しく解説しています。
• AIエージェントのフレームワーク選択についてはAIエージェント フレームワーク比較も参考にしてください。
• AIエージェントのセキュリティ設計についてはAIエージェント セキュリティ対策ガイドで整理しています。
• MCPとAgentCore Gatewayの関係についてはMCPとは（Model Context Protocol）をご覧ください。

まとめ

Managed HarnessとAgentCore CLIは、AIエージェント開発の立ち上げコストを大きく下げるAWSの取り組みです。Managed Harnessのプレビュー段階、東京リージョン非対応、CDKのエクスペリメンタル段階、AgentCore CLIのTerraform未対応という現時点の制約を理解した上で、プロジェクトの要件と照らし合わせて導入を判断してください。