AgentCore Runtimeを作ろう

この章では、Amazon Bedrock AgentCore Runtimeを使ったAIエージェントの実行環境の準備をハンズオン形式で学習します。これにより、コンソールからのRuntime作成とテンプレートコードの中身の把握までができるようになります。

1. 本章の概要

1.1 本章の目的

前章のHarnessはコード無しで動く手軽さがある一方、独自のエージェントロジックを乗せる自由度は限られます。Runtimeは、自分で書いたエージェントコードをサーバレス基盤上で動かすAgentCoreのもう1つの実行基盤で、実務の本格運用ではこちらが中心になります。まずはテンプレートから作成して、Runtimeの構造とテンプレートコードの中身を把握します。

1.2 ハンズオンの流れ

マネジメントコンソールから「テンプレートから始める」でサンプルRuntimeを作成し、コンソール上での動作確認とRuntime詳細画面の各パネル（ARN・エンドポイント・バージョン・オブザーバビリティ）の見方を確認します。あわせて、テンプレートコードをS3からダウンロードして中身を見ておくことで、次章以降で自作エージェントに書き換える出発点を掴みます。

1.3 事前準備

必要なツール

この章では、以下のツールを使用します。まだインストールしていない場合は、リンク先の手順に沿って準備をお願いします。

ツール名	関連箇所	理由
Visual Studio Code	Visual Studio Codeのインストール	S3からダウンロードしたテンプレートコード（`main.py`）の中身をエディタで確認するために使用する

必要なアカウント

この章では、以下のアカウントを使用します。まだ用意していない場合は、リンク先の手順に沿って準備をお願いします。

アカウント名	関連箇所	理由
AWSアカウント	AWSアカウントの作成	AgentCore Runtimeを作成する環境として使用する

2. ハンズオンの概要

2.1 AgentCore Runtimeとは

AgentCore Runtimeは、AIエージェントのコードを動かすためのサーバレス実行基盤です。エージェントごとに独立した実行環境（セッション）が用意され、外部からは共通の呼び出しAPI（InvokeAgentRuntime）で叩けます。Lambdaと違い、セッション単位の状態保持や、長時間の対話にも向いています。

AgentCoreハーネスは、実はこのRuntimeの上に載っている「オーケストレーションループそのものをマネージドで提供する抽象」です。ハーネスはconfigで宣言するだけで済む代わりに、ループの構造はAWSが決めた形に従います。Runtimeを直接扱うと、フレームワーク（Strandsなど）の選択・ループの多段化・独自の分岐など、コードで自由に組める代わりに、書くべきコード量が増えます。両者の機能ごとの違いは AgentCore harness vs. Runtime（AWS公式ドキュメント）に一覧があります。

2.2 AgentCore Runtimeへのデプロイ方式

AgentCore Runtimeには、エージェントコードをデプロイする方式が2種類あります。

デプロイ方式	概要	主な向き先
Direct Code Deployment（CodeZip）	Pythonコードと依存パッケージをzipに固めてS3経由でデプロイする。Docker不要で扱える	試作・素早い反復や、共通のフレームワークで完結する構成に向く
コンテナデプロイ（Container）	Dockerfileでコンテナイメージを組み立て、ECR経由でデプロイする	独自のシステム依存を含む構成や、既存のコンテナCI/CDパイプラインとの統合に向く

本章では Direct Code Deployment（CodeZip）を扱います。CodeZip をローカルCLIで自動化する流れは次章 AgentCore Runtime SDKを理解しようで、コンテナデプロイは AgentCore Runtimeにコンテナデプロイしようで扱います。

2.3 ハンズオン全体の流れ

まずマネジメントコンソールから「テンプレートから始める」でRuntimeを1つ作り、コンソール上で動作確認します。続いて、ランタイムに載っているテンプレートコードを S3 バケットからダウンロードして中身を眺め、Runtime が実行しているコードが「Python コード1ファイル+依存宣言1ファイルを固めた zip」であることを確認します。最後に作成したリソースを削除します。

3. コンソールからのAgentCore Runtime作成

Amazon Bedrock AgentCoreコンソールから、「テンプレートから始める」オプションで最短のRuntimeを作成します。AWSが用意したサンプルコードがS3に自動配置され、そこからRuntimeがデプロイされる仕組みで、コード準備なしにRuntimeの動きを体験できます。

3.1 ランタイムの作成

ランタイム作成画面の表示

マネジメントコンソールで Amazon Bedrock AgentCore コンソールを開き、左メニューの「構築」からランタイムを選択します。「ランタイム」画面の右上にあるランタイムを作成をクリックすると、「ランタイムを作成」画面が開きます。

設定値の入力

以下の値を入力・選択します。

設定項目	値	設定の基準
名前	`MyRuntime`	ハンズオン用に分かりやすい名前をつける
ソースタイプ	`S3ソース`（既定）	今回はS3経由のCodeZipで作成する
S3設定	`テンプレートから始める`（既定）	AWSが用意したサンプルコードで最短スタートするため
テンプレートを選択	`Strands agent`（Python 3.13）	後続のセクションでも Strands Agents SDK を扱うため、コンソール版もStrandsに揃える。`Otel agent` はオブザーバビリティ、`Streaming agent` はストリーミング応答という要素が加わったテンプレートなので、まず基本的な動きを確認するにはシンプルな Strands agent を選ぶ
保存先フォルダ	既定のまま	「テンプレートから始める」を選ぶと、AWSが自動的にサンプルコード配置用のS3バケット（`bedrock-agentcore-runtime-<...>`）を設定する
IAMアクセス許可	`デフォルトロールを作成`（既定）	ランタイム用のIAMロール（`AmazonBedrockAgentCoreRuntimeDefaultServiceRole-XXXX`）をAWS側で自動作成させる

ランタイムの詳細セクションで、名前に MyRuntime を入力します。

エージェントソースセクションで、ソースタイプに S3ソース、S3設定に テンプレートから始める、テンプレートに Strands agent（Python 3.13）を選択します。保存先フォルダは自動で設定される既定値のままにします。

テンプレートを選択すると、その下の Strands agent の詳細 パネルで、選択したテンプレートのエントリーポイント（main.py）と、実際にデプロイされるサンプルコードのプレビューが表示されます。サンプルコードは Agent にモデルIDだけを渡し、prompt を受け取って応答を返すシンプルな Strands エージェントであることが確認できます。

Permissionsセクションでは、IAMアクセス許可を デフォルトロールを作成（既定）のままにします。ランタイム用のIAMロールがAWS側で自動作成されます。

インバウンド認証・ファイルシステムの設定 - オプション・高度な設定はいずれも既定のままにし、右下のランタイムを作成をクリックします。

作成完了の確認

作成が始まると、画面上部に「MyRuntime をプロビジョニングしています。これには最大 1 分かかることがあります。」というバナーが表示されます。ここではページを離れずに待ちます。

プロビジョニングが完了すると、MyRuntime の詳細画面に自動で遷移します。上部に「MyRuntime、バージョン 1 は正常に作成されました。」の緑色バナーが表示され、エージェントとツールの詳細パネルには、名前・ランタイム ARN・ステータス・ソースタイプなどが並びます。この時点ではエンドポイント一覧の DEFAULT のステータスはまだ作成中です。

数十秒ほど待ってページを再読み込みすると、エンドポイント一覧の DEFAULT のステータスが準備完了に変わります。ここまで来れば、コンソールからのランタイム作成は完了です。

3.2 作成されたランタイムの確認

一覧から MyRuntime をクリックして詳細画面を開き、上から順にどのようなランタイムが作成されたのかを見ていきます。

エージェントとツールの詳細

画面上部のエージェントとツールの詳細パネルには、名前・作成日・ソースタイプ・ランタイム ID・ランタイム ARN・ステータスなどが並びます。特に押さえておきたいのは以下です。

ランタイム ARN: arn:aws:bedrock-agentcore:ap-northeast-1:<アカウントID>:runtime/MyRuntime-XXXXXX の形式で払い出される。外部からランタイムを呼び出すときはこのARNを使う
ソースタイプ: S3。作成時に選んだCodeZip方式であることを示す
ステータス: 準備完了 になっていれば、実際に呼び出せる状態になっている

右上には削除・ランタイムを更新・テストのボタンが並んでいます。この後の動作確認ではテストボタンから呼び出しを行います。

呼び出しコードを表示

呼び出しコードを表示パネルには、このランタイムを外部のアプリケーションから呼び出す際に使うサンプルコードが表示されます。Python・TypeScript・JavaScript の3言語から選んで確認できます。Python のサンプルは、boto3 で bedrock-agentcore クライアントを作成し、invoke_agent_runtime に agentRuntimeArn・runtimeSessionId・payload を渡すシンプルな構成になっています。今回はこの後のセクションでコンソールのテスト機能から動作確認するため直接は使いませんが、外部アプリケーションから呼び出す場合はこのコードがそのまま土台になります。

エンドポイント

AgentCore におけるエンドポイントは、クライアントがランタイムを呼び出すときの入口で、それぞれが特定のバージョンに紐づけられます。クライアントはエンドポイント名を指定して呼び出すため、ランタイムの設定を更新したときも、エンドポイントに割り当てるバージョンを差し替えるだけで済み、クライアント側のコードを書き換えずにバージョンを切り替えられる作りになっています。

エンドポイントパネルには、作成時点で DEFAULT エンドポイントが自動作成されています。DEFAULT は常に最新バージョンに追従するエンドポイントです。バージョンを固定して呼び出したい場合や、新しいバージョンを段階的に切り替えたい場合は、右上のエンドポイントを作成から別のエンドポイントを作ってそこに特定バージョンを割り当てます。

バージョン

バージョンパネルには、バージョン 1 が自動で作られています。ランタイムは設定を更新するたびに新しいバージョンのスナップショットが作られ、DEFAULT エンドポイントは常に最新バージョンを指す形になります。ロールバックや過去バージョンとの比較を行うときはこの単位で扱います。

オブザーバビリティ

オブザーバビリティパネルには、ランタイムセッション数・ランタイム呼び出し数・エラー率・スロットリングレート・vCPU消費量・メモリ消費量が並び、時間範囲を5m / 30m / 1h / 3h / 12h / 1d から切り替えられます。作成直後はすべて 0 ですが、この後のテストでランタイムを呼び出すと、ここに値が入ってきます。トレースやログを含む詳細な可視化は AgentCore Observabilityでエージェントを可視化しようで扱います。

ログの配信とトレース

ログの配信とトレース - オプションパネルでは、ランタイムのログとトレースを CloudWatch へ配信する設定を追加できます。ログ配信は初期状態では未設定、Tracingは Not enabled で、有効化するには CloudWatch の Transaction Search を先に設定する必要があります。これらの設定は AgentCore Observabilityでエージェントを可視化しようで扱うため、この章では既定のままにします。

リソースベースのポリシー

リソースベースのポリシーパネルは、他のAWSアカウントやサービスにこのランタイムへのアクセスを許可するためのポリシー設定です。単一アカウント内で使う今回のハンズオンでは設定不要なので、表示するポリシーがありません のままにします。

3.3 ランタイム詳細画面での動作確認

ランタイムの各パネルを確認したら、実際に呼び出して動作を試します。詳細画面右上のテストボタンをクリックすると、コード不要で呼び出しを試せる画面が開きます。

テスト画面では、ランタイムエージェントとエンドポイントにそれぞれ MyRuntime と DEFAULT が自動で選択されています。セッション IDは空欄のままで、実行時に新しいセッションが自動生成されます。入力欄に以下のJSONを入力し、右下の実行をクリックします。

{
  "prompt": "こんにちは、自己紹介をお願いします"
}

出力欄に、モデルからの応答が返ってきます。「テンプレートから始める」で作成したサンプルコードは、受け取った prompt をそのまま Agent に渡して結果を返すシンプルな Strands エージェントとして動作するため、Claude による自己紹介文が箇条書きを交えた形で返ってくれば、コンソールから作成したランタイムが動作している状態です。

コンソールだけで、コードを一切書かずに Runtime が動く状態まで持って行けました。ここまでで「Runtimeという層で何が動くのか」を体感できたので、次のセクションでは、このランタイムに載っているテンプレートコードの実物を S3 から取り出して中身を確認します。

4. テンプレートで生成されたコードの確認

「テンプレートから始める」で作成したランタイムには、AWSが用意したサンプルコード（Strands agent テンプレート）が S3 バケットに zip 形式で配置されています。ここでは、その zip をダウンロードして中身を眺め、Runtime に載っているコードがどのような構成になっているかを確認します。中身を書き換えれば任意の自作エージェントを Runtime で動かせる、という次のステップに繋がる感覚をつかむのが目的です。

4.1 S3バケットからのサンプルコードのダウンロード

MyRuntime の詳細画面で、エージェントとツールの詳細 パネルの エージェントソース に表示されている S3 URI（bedrock-agentcore-runtime-<...> バケット配下）を確認します。

S3コンソールで対象のバケットを開くと、テンプレートから生成された zip ファイルが1つ配置されています（<数字>-<ランダム文字列>-strands_agent.zip の形式）。zip ファイルにチェックを入れてダウンロードをクリックし、ローカルに保存します。

ダウンロードした zip を任意の場所で展開すると、以下のような2ファイル構成になっていることが確認できます。

main.py: エージェントのエントリポイントとなるファイル。Strandsベースのシンプルなエージェントが実装されている
requirements.txt: Runtimeが自動でインストールする Python 依存パッケージ（bedrock-agentcore と strands-agents）を宣言する

4.2 main.pyとrequirements.txtの中身確認

main.py を Visual Studio Code などのエディタで開くと、前のセクションでランタイム作成時に Strands agent の詳細 パネルの コードプレビュー で見たものと同じ内容が入っています。

from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent(model="global.anthropic.claude-haiku-4-5-20251001-v1:0")


@app.entrypoint
def invoke(payload):
    """Your AI agent function"""
    user_message = payload.get("prompt", "Hello! How can I help you today?")
    result = agent(user_message)
    return {"result": result.message}


if __name__ == "__main__":
    app.run()

bedrock-agentcore（AgentCore Runtime SDK）と strands-agents（Strands Agents SDK）の2つを使って、prompt を受け取って応答を返すだけのシンプルなエージェントを表現しているコードです。

requirements.txt の中身は以下の2行だけです。ランタイム側で自動的にインストールされます。

bedrock-agentcore
strands-agents

上記コードの各行の意味、2つのSDKの文法、およびこれを書き換えて自作エージェントを Runtime に載せ替える手順（zip 作成・S3 アップロード・ランタイム更新を agentcore コマンド一発で自動化する流れ）は、次章 AgentCore Runtime SDKを理解しようで解説します。

ここまでで、コンソールで動いていたエージェントの実体が 「Python コード1ファイル + 依存宣言1ファイルを固めた zip」 だったことが確認できました。

💡 ポイント

💡 ポイント
「Runtime に載せる」と聞くと大掛かりに感じるかもしれませんが、実体は S3 に置いた zip ファイル1つです。zip の中身を差し替えて `ランタイムを更新` するだけで、Runtime が実行するコードが切り替わります。この単純さを踏まえて次章の SDK と CLI を学ぶと、`agentcore` コマンドが「zip 作成・S3 アップロード・ランタイム更新をまとめて実行してくれる存在」として理解しやすくなります。

「Runtime に載せる」と聞くと大掛かりに感じるかもしれませんが、実体は S3 に置いた zip ファイル1つです。zip の中身を差し替えて ランタイムを更新 するだけで、Runtime が実行するコードが切り替わります。この単純さを踏まえて次章の SDK と CLI を学ぶと、agentcore コマンドが「zip 作成・S3 アップロード・ランタイム更新をまとめて実行してくれる存在」として理解しやすくなります。

5. 不要リソースの削除

AgentCore Runtimeは稼働時間ベースで課金される要素を含むため、ハンズオン後は忘れずに削除します。

Amazon Bedrock AgentCore コンソールのランタイム画面で、MyRuntime を選択して削除をクリックします。一覧から消えれば、ランタイム本体の削除は完了です。

「テンプレートから始める」で作成した際に自動生成されたS3バケット（bedrock-agentcore-runtime-<...>）とその中の zip ファイル（サンプル・自作とも）も、S3コンソールから中身を削除してからバケットを削除しておくと、ストレージ課金を防げます。

6. まとめ

この章では、AgentCore Runtimeをマネジメントコンソールから作成し、テンプレートコードの中身をS3から取り出して確認するところまでを体験しました。

Runtimeは、AIエージェントのコードを動かすサーバレスな実行基盤で、外部からは共通の呼び出しAPI（InvokeAgentRuntime）で叩ける
マネジメントコンソールの「ランタイムを作成」から「テンプレートから始める」を選ぶだけで、AWSが用意したサンプルコードでRuntimeを1つ動かせる
ランタイム詳細画面から、ARN・エンドポイント・バージョン・オブザーバビリティなどRuntimeの構成要素を一望できる
詳細画面右上の「テスト」から、コード不要で {"prompt": "..."} を送って動作確認ができる
Runtimeの実体はS3上のzipファイル1つで、中身は main.py（Strandsで書かれたエージェント）と requirements.txt（bedrock-agentcore と strands-agents の依存宣言）で構成される
この main.py を書き換えて zip を差し替えれば任意の自作エージェントをRuntimeに載せ替えられる（書き換えには AgentCore Runtime SDK と Strands Agents SDK の理解が前提になる）
稼働時間ベースの課金要素を含むため、コンソールから作ったRuntimeはコンソールから削除し、自動生成されたS3バケットも合わせて削除する

次の章では、AgentCore Runtime SDKを学びつつ、実際にコードでツール定義・システムプロンプト・モデルパラメータ・会話履歴・ストリーミング応答・エラーハンドリングを確かめます。