AgentCore Runtimeにコンテナデプロイしよう

この章では、AgentCore Runtimeへのコンテナデプロイの流れをハンズオン形式で学習します。これにより、Dockerfileを自分で書いて依存関係やベースイメージまで管理できるデプロイ方式が扱えるようになります。

1. 本章の概要

1.1 本章の目的

AgentCore Runtime には Direct Code Deployment（CodeZip）とコンテナデプロイの2方式があり、Direct Code Deployment は手軽ではありますが、パッケージサイズが上限を超える大規模なエージェントを作る場合や、独自のシステムライブラリを含めたい場合には扱いが難しくなります。コンテナデプロイに切り替えると、Dockerfileでビルド環境から依存関係の細部までコントロールでき、既存のコンテナ運用の知見も活かせます。本章では、コンテナデプロイ向けのプロジェクトを新規に作成し、AgentCore Runtime にデプロイするまでの流れを扱います。

1.2 ハンズオンの流れ

agentcore create コマンドの Build type に Container を指定して、コンテナデプロイ向けのプロジェクトを新規作成します。生成されたスケルトンの main.py にエージェントの実装を書き、AgentCore Runtime 向けの Dockerfile の中身を確認したうえで、agentcore deploy コマンドで ARM64 ビルド・ECR push・Runtime 反映をまとめて実行します。最後に agentcore invoke コマンドで応答が返ることを確認します。

1.3 事前準備

前提となる講座

この章では、以下の知識を前提としています。自信がない場合は先に関連講座を実施してみましょう。

必要なツール

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

必要なアカウント

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

本章では東京リージョン（ap-northeast-1）で作業します。AWS CLIの認証情報がap-northeast-1向けに設定できていることを確認してください。

2. プロジェクトの準備

agentcore create コマンドで、コンテナデプロイ用のプロジェクトのフォルダ構造と雛形のコードを対話ウィザードから作成します。まず作業用の親フォルダを準備します。

任意の場所に agentcore-container-handson フォルダを作成し、Visual Studio Codeの「ファイル」→「フォルダーを開く」から、作成した agentcore-container-handson フォルダを開きます。以降の操作は、Visual Studio Codeのターミナルから行います。

agentcore-container-handson  ← このフォルダを作成

ターミナルから対話ウィザードを起動します。

agentcore create

ウィザードが順に質問してくるので、以下のように選択・入力します。Project name と What would you like to build? を答えると、続けて Add Agent の対話が始まり、Agent name 以降を順に選んでいきます。Build で Container を選ぶのが、コンテナデプロイのポイントです。

確定すると、以下のような完了画面が表示されます。[done] が5つ並び（プロジェクトディレクトリ作成・エージェント追加・Python 環境準備・agentcore/ ディレクトリ準備・Git リポジトリ初期化）、Created: の下に生成された上位構造（app/MyContainerAgent/ と agentcore/）と使用モデル（us.anthropic.claude-sonnet-4-5-20250514-v1:0 via Bedrock）が表示されます。末尾の Next: に、この後のステップ（agentcore dev コマンドでローカル動作確認、または agentcore deploy コマンドでデプロイ）が案内されます。

生成されるプロジェクトの詳細は以下のような構成です。Container を選んだので、app/MyContainerAgent/ 配下に Dockerfile が含まれます。

agentcore-container-handson/
└── MyContainerAgent/
    ├── agentcore/
    │   ├── agentcore.json
    │   ├── aws-targets.json
    │   └── cdk/
    └── app/
        └── MyContainerAgent/
            ├── main.py       # エージェントのエントリポイント
            ├── Dockerfile    # ← Build type: Container を選んだ場合に生成される
            ├── requirements.txt
            └── ...

MyContainerAgent/ フォルダが生成され、その中に Dockerfile が入っていれば、プロジェクトの作成は完了です。

3. Dockerfileの中身の確認

agentcore create コマンドが生成した Dockerfile の中身を確認します。本章ではこの Dockerfile は基本的に書き換えず、生成されたものをそのまま使います。中身は「Python ベースイメージを取得 → 高速なパッケージマネージャ uv を導入 → 非 root ユーザを作成 → uv.lock で依存関係を固定インストール → OpenTelemetry で自動計装しつつ HTTP サーバを起動」という流れで、AgentCore Runtime 向けコンテナの要件（ポート 8080 の /invocations と /ping）を満たしたうえで、本番運用に耐える構成になっています。

MyContainerAgent/app/MyContainerAgent/Dockerfile を開くと、以下のような構成になっているはずです（agentcore のバージョンによって差分はあります）。

FROM public.ecr.aws/docker/library/python:3.12-slim-trixie

RUN pip install --no-cache-dir uv

ARG UV_DEFAULT_INDEX
ARG UV_INDEX

WORKDIR /app

ENV UV_SYSTEM_PYTHON=1 \
    UV_COMPILE_BYTECODE=1 \
    UV_NO_PROGRESS=1 \
    PYTHONUNBUFFERED=1 \
    DOCKER_CONTAINER=1 \
    UV_DEFAULT_INDEX=${UV_DEFAULT_INDEX} \
    UV_INDEX=${UV_INDEX} \
    PATH="/app/.venv/bin:$PATH"

RUN useradd -m -u 1000 bedrock_agentcore

COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-install-project

COPY --chown=bedrock_agentcore:bedrock_agentcore . .
RUN uv sync --frozen --no-dev

USER bedrock_agentcore

EXPOSE 8080 8000 9000

CMD ["opentelemetry-instrument", "python", "-m", "main"]

コードを解説します。

FROM public.ecr.aws/docker/library/python:3.12-slim-trixie

Public ECR から Python ベースイメージを取得します。Public ECR は AWS が運営するパブリックコンテナレジストリで、Docker Hub の pull 制限を気にせず利用できます。--platform=linux/arm64 の指定はここでは行わず、後段の agentcore コマンド（agentcore dev や agentcore deploy）が docker buildx build --platform linux/arm64 で ARM64 向けにビルドします。

RUN pip install --no-cache-dir uv

ARG UV_DEFAULT_INDEX
ARG UV_INDEX

Python パッケージマネージャの uv をインストールします。uv は Rust で書かれた pip の後継で、依存関係の解決とインストールが大幅に高速化されます。ARG UV_DEFAULT_INDEX / UV_INDEX は、社内プライベート PyPI などを利用する場合に docker build --build-arg で外部から注入するためのビルド引数です。

WORKDIR /app

ENV UV_SYSTEM_PYTHON=1 \
    UV_COMPILE_BYTECODE=1 \
    UV_NO_PROGRESS=1 \
    PYTHONUNBUFFERED=1 \
    DOCKER_CONTAINER=1 \
    UV_DEFAULT_INDEX=${UV_DEFAULT_INDEX} \
    UV_INDEX=${UV_INDEX} \
    PATH="/app/.venv/bin:$PATH"

作業ディレクトリを /app に固定し、uv と Python の環境変数をまとめて設定します。主要なものは以下です。

RUN useradd -m -u 1000 bedrock_agentcore

bedrock_agentcore という非 root ユーザを作成します。後段で USER bedrock_agentcore に切り替えることで、コンテナ内のプロセスを非 root 権限で実行し、AWS のセキュリティベストプラクティスに準拠します。

COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-install-project

COPY --chown=bedrock_agentcore:bedrock_agentcore . .
RUN uv sync --frozen --no-dev

依存関係のインストールとアプリケーションコードのコピーを2段階に分けます。先に pyproject.toml と uv.lock だけをコピーして uv sync --no-install-project で依存パッケージを入れておくことで、コードだけを変更した場合はこのレイヤをキャッシュから再利用でき、イメージビルドが速くなります。その後にアプリケーション本体を非 root ユーザ所有でコピーし、2回目の uv sync でプロジェクト本体を仮想環境にインストールします。--frozen は uv.lock のバージョンを厳密に守るオプションで、CI/CD 実行時に予期しないバージョン変動が起きるのを防ぎます。

USER bedrock_agentcore

EXPOSE 8080 8000 9000

CMD ["opentelemetry-instrument", "python", "-m", "main"]

実行ユーザを非 root に切り替え、AgentCore Runtime が扱う3つのポート（HTTP モード 8080／MCP モード 8000／A2A モード 9000）を公開します。本章のエージェントは HTTP モードのみ使うため、実際に受け付けるのは 8080 だけです。CMD は Python プロセスを opentelemetry-instrument 経由で起動することで、AgentCore Observability に必要なテレメトリを自動で計装します。BedrockAgentCoreApp の app.run() が /invocations と /ping の両エンドポイントを自動で提供するため、CMD 側は Python プロセスの起動を指示するだけで要件を満たせます。

独自のシステム依存を追加したい場合（apt パッケージなど）は、RUN apt-get update && apt-get install -y ... を差し込むだけで拡張できます。ここが Direct Code Deployment との大きな差です。

4. エージェントコードの記述

Dockerfile の中身が把握できたら、その COPY main.py . でコンテナに取り込む Python コードを準備します。Visual Studio Code のエクスプローラーで app/MyContainerAgent/main.py を開き、以下の内容で置き換えて保存します。今回は、前章 AgentCore Runtime SDKを理解しよう と同じメール署名エージェント（最初に書いたシンプルな版）をそのままコンテナに載せます。

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent, tool
from strands.models import BedrockModel

COMPANY_NAME = "DevOps株式会社"
COMPANY_TEL = "03-1234-5678"
MODEL_ID = "<モデルID>"  # ap-northeast-1で利用可能なClaude Sonnetの推論プロファイルID（例: jp.anthropic.claude-sonnet-4-6）に変更してください

app = BedrockAgentCoreApp()


@tool
def create_signature(name: str, department: str, position: str, email: str) -> str:
    """氏名・部署名・役職・メールアドレスを受け取り、所定のフォーマットのメール署名を返します。会社名と代表電話番号は自動で付与されます。"""
    return (
        "━━━━━━━━━━━━━━━━━━━━━━\n"
        f"【{name}】{COMPANY_NAME} {department} {position}\n"
        f"Email: {email}\n"
        f"Tel:   {COMPANY_TEL}\n"
        "━━━━━━━━━━━━━━━━━━━━━━"
    )


agent = Agent(
    model=BedrockModel(model_id=MODEL_ID, region_name="ap-northeast-1"),
    tools=[create_signature],
    system_prompt="あなたはメール署名を作成するアシスタントです。ユーザから受け取った情報をもとに create_signature ツールを呼び出し、結果をそのまま提示してください。",
)


@app.entrypoint
def invoke(payload):
    prompt = payload.get("prompt", "田中太郎（開発部 エンジニア、tanaka@example.com）のメール署名を作って")
    result = agent(prompt)
    return {"result": str(result)}


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

5. 動作確認

作ったエージェントの動作を、以下2つの方法で段階的に確認していきます。

1. agentcore dev による動作確認 — agentcore dev コマンドがローカル Docker でコンテナを起動し、ブラウザの Agent Inspector（対話 UI）から呼び出して検証する
2. AgentCoreへの反映 — agentcore deploy コマンドでクラウドの AgentCore Runtime にデプロイし、CLI から呼び出して動作を確認する

いずれの方法でも、以下の2つが事前に整っている必要があります。

• AWS 認証情報の設定 — Bedrock のモデルを呼び出すため、aws configure で対象の AWS アカウントの認証情報を ~/.aws/credentials に保存しておきます。設定手順は事前準備の AWS CLIのインストール を参照
• Docker Desktop の起動 — 両方法とも内部で Docker を利用します（agentcore dev コマンドは Container ビルドのプロジェクトでは内部で docker build を走らせるため、agentcore deploy と同様に Docker が必要）

5.1 agentcore dev による動作確認

agentcore dev コマンドは、Container ビルドのプロジェクトの場合、内部で Docker イメージをビルドしてローカルでコンテナを起動し、ブラウザで Agent Inspector（HTTP エンドポイントを対話 UI から叩けるツール）を開きます。Agent Inspector 経由で対話的にプロンプトを投げてクラウドデプロイ前に動作を確認できるので、main.py を書き換えた直後の検証にちょうど良い流れです。

まず、Docker Desktop が起動していない場合は、アプリケーション一覧から Docker.app を起動します。起動が完了すると、Mac ではメニューバーに Docker のクジラアイコンが表示され、Docker Desktop 画面上のインジケーターが Docker Desktop is running になります。

起動を確認したら、ターミナルから疎通確認します。

docker ps

以下のようにヘッダ行が返れば、Docker との通信は確立できています（起動中のコンテナがない場合はヘッダ行だけが返ります）。

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Docker との疎通が確認できたら、MyContainerAgent フォルダに移動してから agentcore dev コマンドを起動します。

cd MyContainerAgent

agentcore dev

初回は Docker イメージのビルド（ARM64 向けのベースイメージ pull と依存関係のインストール）で数分かかります。完了するとブラウザで Agent Inspector が開くので、チャット欄に以下のプロンプトを送信します。

田中太郎（開発部 エンジニア、tanaka@example.com）のメール署名を作って

装飾線付きの署名（【田中太郎】DevOps株式会社 開発部 エンジニア を含む形式）が応答に含まれて返れば、コード自体は正しく動く状態です。

5.2 AgentCoreへの反映

ローカルで動作が確認できたら、agentcore deploy コマンドでコンテナをビルドしてクラウドの AgentCore Runtime にデプロイします。実行するコマンド自体は前章の Direct Code Deployment のときと同じで、Container ビルドを選んだプロジェクトでは Docker ビルドと ECR push が自動的に走ります。

MyContainerAgent プロジェクトフォルダに移動してから実行します。

cd MyContainerAgent

agentcore deploy

agentcore deploy コマンドは、docker buildx による ARM64 向けのイメージビルド、ECR リポジトリの自動作成、イメージの push、AgentCore Runtime への反映、CloudWatch のロギング設定までを、CDK 経由でまとめて実行します。初回は CDK bootstrap と ARM64 ビルドで数分〜十数分かかります。

完了すると、以下のように CDK パイプラインの各ステップが [done] に切り替わり、✓ Deploy to AWS Complete が表示されます。

マネジメントコンソールで Amazon Bedrock AgentCore の「ランタイム」画面を開くと、MyContainerAgent_MyContainerAgent（プロジェクト名 + _ + エージェント名）というランタイムがステータス「準備完了」で登録されていることが確認できます。

デプロイが完了したら、AgentCore CLI から MyContainerAgent を呼び出して、クラウド側でも同じ応答が返ることを確認します。

agentcore invoke --prompt "田中太郎（開発部 エンジニア、tanaka@example.com）のメール署名を作って"

以下のように、エージェントからの自然文の中に装飾線付きの署名テキストが含まれた形で返ります。応答の下には、AgentCore が発行したセッション ID と、同じセッションを継続するためのコマンド、ログの保存先が表示されます。

田中太郎さんのメール署名が完成しました！こちらをご利用ください：

━━━━━━━━━━━━━━━━━━━━━━
【田中太郎】DevOps株式会社 開発部 エンジニア
Email: tanaka@example.com
Tel:   03-1234-5678
━━━━━━━━━━━━━━━━━━━━━━

会社名（DevOps株式会社）と代表電話番号（03-1234-5678）は自動で付与されています。何か修正が必要な場合はお知らせください！


Session: 34d66f2a-789d-4382-a6f4-38cc7501fd45
To resume: agentcore invoke --session-id 34d66f2a-789d-4382-a6f4-38cc7501fd45
Log: agentcore/.cli/logs/invoke/invoke-MyContainerAgent-20260726-211955.log

会社名（DevOps株式会社）と代表電話番号（03-1234-5678）はユーザから入力していないのに応答に含まれているため、これが「コンテナ内で create_signature ツールが実際に呼ばれた証拠」になります。マネジメントコンソールで対象のエージェントの Observability 画面を開くと、ツール呼び出し・レイテンシ・トークン数などのトレース情報が確認できます。デプロイの中身が zip でもコンテナでも、呼び出し側から見た振る舞いは同じというのが、AgentCore Runtime が提供する抽象化のメリットです。

6. Direct Code Deploymentとの使い分けの整理

AgentCore Runtime が提供する Direct Code Deployment とコンテナデプロイの2方式について、実務でどちらを選ぶかの判断材料として、両者の違いを整理しておきます。

判断の目安は Get started with Amazon Bedrock AgentCore Runtime direct code deployment（AWS公式ドキュメント） に以下のように記載されています（英語表示時の引用。日本語表示は画面右上のセレクタで切替可能）。

If the size of the deployment package exceeds 250MB, and you have existing container CI/CD pipelines, and you need highly specialized dependencies and packaging, then container based deployments is a good option to choose. If the size of the deployment package is small, the code and package is not complex to build and uses common frameworks and languages, and you need rapid prototyping and iteration, then direct code deployment would be the option.

ここの「container CI/CD pipelines」「highly specialized dependencies」「rapid prototyping and iteration」という記述から、既存のコンテナ運用に載せたい・独自依存が必要な場合はコンテナデプロイ、素早い試作・共通フレームワークで済む場合はDirect Code Deployment、と読み取れます。試作はDirect Code Deploymentで始め、本番運用に近づいたタイミングでコンテナデプロイに切り替えるハイブリッド運用も、同ドキュメントで推奨されています。

7. 不要リソースの削除

AgentCore Runtime は稼働時間ベースで課金されるコンポーネントを含み、加えて ECR のイメージ保管にも課金が発生するため、ハンズオン後は忘れずに削除します。AgentCore CLI では、agentcore remove all コマンドと agentcore deploy コマンドを組み合わせて片付ける手順が用意されています。

MyContainerAgent フォルダで、まず agentcore.json のリソース定義を空の状態にします。

agentcore remove all

続いてデプロイを実行すると、AgentCore CLI が「空になった config と AWS 上の実リソース」を比較し、Runtime 本体・ECR リポジトリ・CloudWatch ロググループ・IAM ロールなどをまとめて破棄します。

agentcore deploy

完了メッセージが表示されれば AWS 側の片付けは完了です。ローカルの agentcore-container-handson/ フォルダは、必要に応じて手動で削除します。

8. まとめ

この章では、agentcore create の Build type: Container で新規プロジェクトを作成し、Dockerfile 経由で ECR に push して AgentCore Runtime にデプロイする流れを体験しました。

• AgentCore Runtime向けのコンテナは、ARM64・ポート 8080・/invocations と /ping のエンドポイントが要件になる
• BedrockAgentCoreApp の app.run() が要件を満たす HTTP サーバを自動で提供するため、Dockerfile の CMD は Python プロセスを起動するだけで、AgentCore Runtime の HTTP エンドポイント要件（/invocations と /ping）を満たせる
• agentcore create が生成する Dockerfile は uv による依存解決・非 root ユーザ・OpenTelemetry 自動計装まで含んだ本番相当のスケルトンとして提供される
• agentcore create の Build type を Container に切り替えるだけで、Dockerfile込みのスケルトンを生成できる
• agentcore deploy により、ARM64ビルド・ECR push・Runtimeへの反映をまとめて実行できる
• Direct Code Deployment とコンテナデプロイは、パッケージサイズ・依存の自由度・反復速度でトレードオフがある
• 素早い試作は Direct Code Deployment、独自依存や既存のコンテナCI/CDと組む場合はコンテナデプロイ、という使い分けができる
• ECRのイメージ保管にも課金が発生するため、不要になったら agentcore remove all コマンドと agentcore deploy コマンドで片付ける

次の章では、AgentCore Runtimeへデプロイしたエージェントに AgentCore Memory を組み合わせて会話履歴を任せる流れをハンズオン形式で体験します。