Serverless Operations, inc

>_cd /blog/id_vhodh-0ah

title

AIエージェント構築の面倒な部分を肩代わりするAmazon Bedrock AgentCore Harnessの始め方

今日は、Public Preview 中である Amazon Bedrock AgentCore Harness を触っていきます。

AgentCore Harness とは

AIエージェントを本番環境で稼働させるためには様々な設定が必要となります。モデルの呼び出しそのものは容易であっても、ツールの選択と呼び出し、コンテキストウィンドウの管理、メモリの永続化、認証・認可、セキュリティの確保、ログ・トレースの収集といった周辺機能を適切に組み上げるには、エージェントのロジック本体よりも多くの工数が必要となります。

Claude Code に代表されるコーディングエージェントの補助を受けるのであれば、ロジック本体のコーディングはそれ単独で完結するため短時間で済むケースも多いですが、その他さまざまな機能との連携を求められる周辺機能には多くの時間が消費されます。

AWSが提供する Amazon Bedrock AgentCore の「Harness」は、こうした実行基盤の構築をフルマネージドサービスとして提供することで、開発者がエージェントの本質的な設計に集中できる環境を実現することを目的として、パブリックプレビューが提供されています。

エージェントにおける「ハーネス」の役割

AIエージェントが実際に機能するためには、モデル自体に加えて、それを取り巻く実行環境——すなわち「ハーネス（装備一式）」が不可欠です。特にAWSの場合、他にはないIAM認証やVPC設定など初期設定は煩雑になりがちです。ハーネスを構成する要素には、以下のようなものが挙げられます。

  • モデルの呼び出し、ツールの選択・実行、結果の受け取りといったオーケストレーション処理
  • コードを安全に実行するためのサンドボックス環境
  • 外部ツールやAPIへのセキュアな接続
  • セッションをまたいだ短期・長期メモリの永続化
  • IAM認証やVPCネットワーキングの設定
  • トレース・ログ・オブザーバビリティの整備

従来、これらはすべて開発チームが独自に構築する必要がありました。フレームワークの選定から始まり、オーケストレーションコードの実装、ツールの接続、認証設定、環境のプロビジョニングまで、エージェントが最初のタスクを処理できる状態になるまでに、相当な準備工数が発生していました。

AgentCore Harness がもたらす変化

AgentCore Harness は、上述の構築作業を「設定の宣言」に置き換えることを目的として設計されています。開発者が行うべき作業は以下の3点に集約されます。

  • 使用するモデルの指定
  • 利用可能なツールの宣言
  • エージェントへの指示（システムプロンプト）の記述

これらを設定として定義すれば、コンピューティング環境の構築、ツール接続、メモリ管理、VPCネットワーキング、および観測基盤の整備はすべてAWSが担ってくれます。モデルの変更や新規ツールの追加が必要になった際にも、コードの改修は不要であり、設定変更のみで対応できます。

主要な機能

セキュアな実行環境 セッションごとに独立したマイクロVM上で動作し、各エージェントは専用のファイルシステムとシェルを保有します。コードの実行も安全なサンドボックス内で行われます。

マルチモデル・マルチプロバイダー対応 Amazon Bedrock・OpenAI・Google Gemini のいずれのモデルも利用可能であり、セッションを維持したままプロバイダーをその場で切り替えることができます。

柔軟なツール連携 AgentCore Gateway や MCPサーバーに加え、ブラウザツールおよびコードインタープリターが標準で組み込まれています。独自のDockerfileやコンテナイメージを用いたカスタム環境への対応も可能です。

自動化されたオブザーバビリティ すべての操作はAgentCore Observabilityによって自動的にトレースされ、別途の計装作業を必要とせずにデバッグや運用監視を行うことができます。

なお、技術的な基盤としては、AWSがオープンソースで公開しているエージェントフレームワーク「Strands Agents」が採用されています。

利用手順の概要

AgentCore CLIを使用した場合、以下の3つのコマンドのみでエージェントの起動までが完結します。

agentcore create --name myagent --model-provider bedrock
agentcore deploy
agentcore invoke --harness myagent --session-id "$(uuidgen)" "タスクの内容をここに記述する"

また、agentcore dev コマンドを実行することで、ブラウザ上のエージェントインスペクターが起動し、チャット形式での動作確認とリアルタイムのトレース参照を同時に行うことができます。

さっそくやってみる

Harnessの起動を対話的に行うウィザードがCLI形式で用意されていますので、そちらを使っていきます。

まずCLIをインストールします。

npm install -g @aws/agentcore@preview

次にウィザードを起動しプロジェクトを作成します。

agentcore create

プロジェクト名を入力します。


  AgentCore Create


  Project: harness

Harness を選択します。


  What would you like to build?

  ❯ Harness (recommended) - Managed config-based agent loop, no code required
    Agent - Start with a template or bring your own code hosted on AgentCore Runtime
    Skip - I'll add resources later

次にステップではモデルプロバイダーを指定します。この手順ではBedrockを選択します。

環境設定を行います。コンテナ形式も指定できるようですが Default のVMで進めます。

過去のこのブログでも取り上げた AgentCore Memory を起動するかどうかの選択です。

https://serverless.co.jp/blog/vty5c3icl/

Memory を備えることでセッションをまたがり AI Agent がコンテキストを引き継ぐことができます。

様々な周辺機能の有無を指定します。

設定が完了するとHarnessの作成が開始されます。

作成が完了したら、プロジェクト名を冠したディレクトリが作成されていますので、移動します。

cd harness

AWS CDK の BootStrap

Harness は AWS CDK で起動されます。

npx cdk bootstrap aws://917561075114/us-west-2

917561075114 は AWS のアカウントIDですので皆さんの環境ごとに置き換えておきます。

Need to install the following packages:
cdk@2.1126.0
Ok to proceed? (y) y

 ⏳  Bootstrapping environment aws://917561075114/us-west-2...
Trusted accounts for deployment: (none)
Trusted accounts for lookup: (none)
Using default execution policy of 'arn:aws:iam::aws:policy/AdministratorAccess'. Pass '--cloudformation-execution-policies' to customize.
CDKToolkit: creating CloudFormation changeset...
 ✅  Environment aws://917561075114/us-west-2 bootstrapped.

次に AgentCore Harness を Deploy します。

agentcore deploy

デプロイが出来たら agentcore status で環境を確認します。

AgentCore Status (target: default, us-west-2)

Harnesses
  MyHarness: Deployed (arn:aws:bedrock-agentcore:us-west-2:917561075114:harness/harness_MyHarness-S7jRBRe0wb)

では起動します。

agentcore dev --no-browser

 Dev

  Project: harness
  Harness: MyHarness
  Target: us-west-2
  Session: ef00c8e6-acf4-470d-a3df-854d0182ff04
  User: default-user
  If you changed the harness config, redeploy to pick up changes: agentcore deploy

  >

話しかけて応答が起動すれば完了です。

マネージメントコンソール上でHarnessが確認できます。

AgentCore の様々な機能が Harness から確認できるようになっています。

CDKにより管理されているCloudFormationスタックは以下の通りです。

{
  "Description": "AgentCore stack for harness deployed to default (us-west-2)",
  "Resources": {
    "ApplicationHarnessMyHarnessRoleExecutionRole153C4B44": {
      "Type": "AWS::IAM::Role",
      "Properties": {
        "AssumeRolePolicyDocument": {
          "Statement": [
            {
              "Action": "sts:AssumeRole",
              "Condition": {
                "StringEquals": {
                  "aws:SourceAccount": "917561075114"
                },
                "ArnLike": {
                  "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:917561075114:*"
                }
              },
              "Effect": "Allow",
              "Principal": {
                "Service": "bedrock-agentcore.amazonaws.com"
              }
            }
          ],
          "Version": "2012-10-17"
        },
        "Description": "AgentCore Harness MyHarness execution role",
        "RoleName": "harness_MyHarness",
        "Tags": [
          {
            "Key": "agentcore:created-by",
            "Value": "agentcore-cli"
          },
          {
            "Key": "agentcore:project-name",
            "Value": "harness"
          }
        ]
      },
      "Metadata": {
        "aws:cdk:path": "AgentCore-harness-default/Application/HarnessMyHarness/Role/ExecutionRole/Resource"
      }
    },
    "ApplicationHarnessMyHarnessRoleExecutionRoleDefaultPolicy4A470439": {
      "Type": "AWS::IAM::Policy",
      "Properties": {
        "PolicyDocument": {
          "Statement": [
            {
              "Action": [
                "bedrock:InvokeModel",
                "bedrock:InvokeModelWithResponseStream"
              ],
              "Effect": "Allow",
              "Resource": [
                "arn:aws:bedrock:*::foundation-model/*",
                "arn:aws:bedrock:us-west-2:917561075114:*"
              ],
              "Sid": "BedrockModelInvocation"
            },
            {
              "Action": "ecr-public:GetAuthorizationToken",
              "Effect": "Allow",
              "Resource": "*",
              "Sid": "EcrPublicTokenAccess"
            },
            {
              "Action": "sts:GetServiceBearerToken",
              "Effect": "Allow",
              "Resource": "*",
              "Sid": "StsForEcrPublicPull"
            },
            {
              "Action": [
                "xray:GetSamplingRules",
                "xray:GetSamplingTargets",
                "xray:PutTelemetryRecords",
                "xray:PutTraceSegments"
              ],
              "Effect": "Allow",
              "Resource": "*",
              "Sid": "XRayTracingAccess"
            },
            {
              "Action": [
                "logs:CreateLogGroup",
                "logs:DescribeLogStreams"
              ],
              "Effect": "Allow",
              "Resource": "arn:aws:logs:us-west-2:917561075114:log-group:/aws/bedrock-agentcore/runtimes/*",
              "Sid": "CloudWatchLogsGroup"
            },
            {
              "Action": "logs:DescribeLogGroups",
              "Effect": "Allow",
              "Resource": "arn:aws:logs:us-west-2:917561075114:log-group:*",
              "Sid": "CloudWatchLogsDescribeGroups"
            },
            {
              "Action": [
                "logs:CreateLogStream",
                "logs:PutLogEvents"
              ],
              "Effect": "Allow",
              "Resource": "arn:aws:logs:us-west-2:917561075114:log-group:/aws/bedrock-agentcore/runtimes/*:log-stream:*",
              "Sid": "CloudWatchLogsStream"
            },
            {
              "Action": "cloudwatch:PutMetricData",
              "Condition": {
                "StringEquals": {
                  "cloudwatch:namespace": "bedrock-agentcore"
                }
              },
              "Effect": "Allow",
              "Resource": "*",
              "Sid": "CloudWatchMetricsPublish"
            },
            {
              "Action": [
                "bedrock-agentcore:GetWorkloadAccessToken",
                "bedrock-agentcore:GetWorkloadAccessTokenForJWT"
              ],
              "Effect": "Allow",
              "Resource": [
                "arn:aws:bedrock-agentcore:us-west-2:917561075114:workload-identity-directory/default",
                "arn:aws:bedrock-agentcore:us-west-2:917561075114:workload-identity-directory/default/workload-identity/harness_harness_MyHarness-*"
              ],
              "Sid": "AgentCoreWorkloadIdentity"
            }
          ],
          "Version": "2012-10-17"
        },
        "PolicyName": "ApplicationHarnessMyHarnessRoleExecutionRoleDefaultPolicy4A470439",
        "Roles": [
          {
            "Ref": "ApplicationHarnessMyHarnessRoleExecutionRole153C4B44"
          }
        ]
      },
      "Metadata": {
        "aws:cdk:path": "AgentCore-harness-default/Application/HarnessMyHarness/Role/ExecutionRole/DefaultPolicy/Resource"
      }
    },
    "CDKMetadata": {
      "Type": "AWS::CDK::Metadata",
      "Properties": {
        "Analytics": "v2:deflate64:H4sIAAAAAAAA/+2ST0sDMRDFP0vnWLLRBgTZW/XkRaXtrRQZk4jT5s+ymVhK2O8u28Vq2YsIHgRPGX5v3gzMi5Lq6lpeTnCfKm12laNnWZaMeidwn54IvSyL6Oy6QBudvUdvoYYpCMCUsrfm5gB1gaaloKlBN9c65sBnPb1/rpliOOJOgLFJt9R8QQXQmFV8jI70Aep16Taf8GP4SGVG/XoXHAV70mAK3xB/sOzf8suWjbh9Cf1nEQPu0zoFuYq9Msp3jI1ZMrL1NnA6W/v38PEgwy26vnzI3GTuRIjGym26eFNKqpmcTbaJqGpzYPJWLob3HTePNO/aAwAA"
      },
      "Metadata": {
        "aws:cdk:path": "AgentCore-harness-default/CDKMetadata/Default"
      }
    }
  },
  "Outputs": {
    "ApplicationHarnessMyHarnessRoleRoleArnOutput112FFAA1": {
      "Value": {
        "Fn::GetAtt": [
          "ApplicationHarnessMyHarnessRoleExecutionRole153C4B44",
          "Arn"
        ]
      },
      "Export": {
        "Name": "AgentCore-harness-default-Harness-MyHarness-RoleArn"
      }
    },
    "StackNameOutput": {
      "Description": "Name of the CloudFormation Stack",
      "Value": "AgentCore-harness-default"
    }
  },
  "Parameters": {
    "BootstrapVersion": {
      "Type": "AWS::SSM::Parameter::Value<String>",
      "Default": "/cdk-bootstrap/hnb659fds/version",
      "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
    }
  },
  "Rules": {
    "CheckBootstrapVersion": {
      "Assertions": [
        {
          "Assert": {
            "Fn::Not": [
              {
                "Fn::Contains": [
                  [
                    "1",
                    "2",
                    "3",
                    "4",
                    "5"
                  ],
                  {
                    "Ref": "BootstrapVersion"
                  }
                ]
              }
            ]
          },
          "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
        }
      ]
    }
  }
}

基本はHarnessの動作に必要なIAMのみを管理しています。

作成されるリソース

① IAMロール harness_MyHarness

AgentCoreサービスが「なりすまして使う」実行ロールです。

bedrock-agentcore.amazonaws.com が AssumeRole できる
└─ ただし 自分のアカウント(917561075114) からのアクセスに限定

② IAMポリシー（上記ロールにアタッチ）

このロールに以下の権限を与えています：

権限

目的

bedrock:InvokeModel

Claude等のモデルを呼び出す

ecr-public:GetAuthorizationToken

ECRからコンテナイメージを取得する

xray:PutTraceSegments 等

X-Rayでトレースを記録する

logs:CreateLogGroup 等

CloudWatchにログを書き出す

cloudwatch:PutMetricData

メトリクスを送信する

bedrock-agentcore:GetWorkloadAccessToken

AgentCore内部の認証トークンを取得する

Written by
編集部

亀田 治伸

Kameda Harunobu

  • Facebook->
  • X->
  • GitHub->

Share

Facebook->X->
Back
to list
<-
SERVERLESS
OPERATIONS