7
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@yakumo_09(やくも)

【AWS】CDK初心者がAgentCoreをデプロイするまで

7
Posted at

はじめに

とある事情でCDKをやることになり、勉強も兼ねています。
今回はCDKを利用してAgentCore Runtimeを作成してみました。

AgentCoreはAWSが2025年に発表したAIエージェントを動かすためのマネージドサービスです。詳しくは以下をご覧ください。

本記事では実際にCDKで作成してデプロイするまでをコードと一緒に解説していきます。

また、今回作成したテンプレートはこちらで公開しています。

開始時点のCDKの経験値

0です。使ったことすらないです。

事前にこちらのTypeScript の基礎から始める AWS CDK 開発入門を実施することでかなり理解を深めることができました。

ハンズオンなのでコードを書きながら学べます。「CDKってそもそも何？」という状態からスタートするなら先にやっておくことをおすすめします。

加えて以下のワークショップも実施しました。

これら二つのワークショップを実施し、ある程度CDKに対する理解を得た上で実施することにしました。

実装していく

準備編

CDKプロジェクトの初期化

まずCDKのプロジェクトを作成します。

mkdir agentcore-cdk && cd agentcore-cdk
npx cdk init app --language typescript

cdk init を実行することで必要なファイルが自動生成されます。

AgentCore用パッケージのインストール

cdk init で作成されたプロジェクトにはAgentCore用のパッケージが含まれていないので、別途追加する必要があります。

npm install @aws-cdk/aws-bedrock-agentcore-alpha

このコマンドを実行すると package.json の dependencies に自動で追加されます。

package.json
"dependencies": {
  "@aws-cdk/aws-bedrock-agentcore-alpha": "^2.250.0-alpha.0",
  "aws-cdk-lib": "^2.248.0",
  "constructs": "^10.5.0"
}

AgentCore用のCDKパッケージはアルファ版となっており、以下にまとまっています。

アルファ版（実験的）パッケージとは

-alpha がついたパッケージはAWSが実験的に提供しているものです。公式ドキュメントには以下のように記載されています。

新しいサービス (またはコアモジュール) のためにL2コンストラクトが初めて作成されたときに、新しいアルファモジュールを作成します。
アルファモジュールは、aws-cdk-lib/名前空間の下にある安定したモジュールと明確に区別するために、@aws-cdk/名前空間の下に-alphaの修飾子を付けてリリースされていることがわかります。v2のAPIリファレンスには、これらの名前空間も含まれています。

Experimental construct librariesがAWS CDK v2で利用可能になりました

最終的なディレクトリ構成

最終的なディレクトリ構成は以下になります。主に手を加えるのはagent配下とlib配下のファイルになります。
cdk init で作成される初期プロジェクトにagentフォルダは含まれていないため、自分で作成・追加する必要があります。

agentcore-cdk/
├── agent/                      # エージェント本体（Pythonで書く）
│   ├── app.py
│   ├── Dockerfile
│   └── requirements.txt
├── bin/
│   └── agentcore-cdk.ts        
└── lib/
    └── agentcore-cdk-stack.ts  # メインのCDKコード(TypeScriptで書く)

ここからが本編

実装の全体の流れは以下のようになっています。

① Pythonでエージェントを書く（app.py）
       ↓
② Dockerイメージに固める（Dockerfile）
       ↓
③ CDKでECRにプッシュ＆AgentCore Runtimeを作成（agentcore-cdk-stack.ts）
       ↓
④ cdk deploy でAWSにデプロイ

① エージェント本体を書く（agent/app.py）

app.py
from strands import Agent
from bedrock_agentcore.runtime import BedrockAgentCoreApp

agent = Agent()

app = BedrockAgentCoreApp()

@app.entrypoint
def invoke(payload):
    user_message = payload.get("prompt", "")
    response = agent(user_message)
    return str(response)

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

このエージェントのコードは以下のStrandsやAgentCoreの公式ドキュメントを参考に作成しました。後のDocerfileも同様です。

② Dockerイメージの設定

requirements.txt
strands-agents[otel]
bedrock-agentcore

FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim

WORKDIR /app
COPY requirements.txt .
RUN uv pip install --system -r requirements.txt
COPY app.py .

EXPOSE 8080
CMD ["python", "app.py"]

③ CDKスタックを書く

コード全体を先に示してから、ブロックごとに解説します。

agentcore-cdk-stack.ts
import * as cdk from 'aws-cdk-lib/core';
import { Construct } from 'constructs';
import * as ecr_assets from 'aws-cdk-lib/aws-ecr-assets'; // Dockerイメージ → ECR
import * as agentcore from '@aws-cdk/aws-bedrock-agentcore-alpha'; // AgentCore Runtime
import * as iam from 'aws-cdk-lib/aws-iam'; // IAM権限管理

export class AgentcoreCdkStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ① Dockerイメージのビルド & ECRへのプッシュ
    const agentImage = new ecr_assets.DockerImageAsset(this, 'AgentImage', {
      directory: 'agent',
      platform: ecr_assets.Platform.LINUX_ARM64,
    });

    // ② AgentCore Runtime の作成
    const runtime = new agentcore.Runtime(this, 'AgentRuntime', {
      runtimeName: 'agentcore_cdk',
      agentRuntimeArtifact: agentcore.AgentRuntimeArtifact.fromEcrRepository(
        agentImage.repository,
        agentImage.imageTag,
      ),
      networkConfiguration: agentcore.RuntimeNetworkConfiguration.usingPublicNetwork(),
    });

    // ③ RuntimeにBedrockの呼び出し権限を付与
    runtime.addToRolePolicy(new iam.PolicyStatement({
      actions: [
        'bedrock:InvokeModel',
        'bedrock:InvokeModelWithResponseStream',
      ],
      resources: [
        'arn:aws:bedrock:*::foundation-model/*',
        'arn:aws:bedrock:*:*:inference-profile/*',
      ],
    }));

    // ④ デプロイ後にARNをターミナルに表示
    new cdk.CfnOutput(this, 'AgentRuntimeArn', {
      value: runtime.agentRuntimeArn,
    });
  }
}

① DockerImageAsset：Dockerイメージのビルド、ECRへプッシュ

const agentImage = new ecr_assets.DockerImageAsset(this, 'AgentImage', {
  directory: 'agent',                        // agent/Dockerfile を使う
  platform: ecr_assets.Platform.LINUX_ARM64, // AgentCoreはARM64が必要
});

参照：aws-cdk-lib.aws_ecr_assets

② agentcore.Runtime：Runtimeの作成

const runtime = new agentcore.Runtime(this, 'AgentRuntime', {
  runtimeName: 'agentcore_cdk',
  agentRuntimeArtifact: agentcore.AgentRuntimeArtifact.fromEcrRepository(
    agentImage.repository,
    agentImage.imageTag,
  ),
  networkConfiguration: agentcore.RuntimeNetworkConfiguration.usingPublicNetwork(),
});

fromEcrRepository() に①で作ったECRリポジトリとタグを渡すだけで、AgentCore Runtimeがそのイメージを使ってくれます。CDKがリポジトリとタグを自動的に連携してくれるので、URIをコピペする必要もありません。

参照：@aws-cdk/aws-bedrock-agentcore-alpha

③ IAMポリシー：Bedrockの呼び出し権限

runtime.addToRolePolicy(new iam.PolicyStatement({
  actions: [
    'bedrock:InvokeModel',
    'bedrock:InvokeModelWithResponseStream',
  ],
  resources: [
    'arn:aws:bedrock:*::foundation-model/*',
    'arn:aws:bedrock:*:*:inference-profile/*',
  ],
}));

RuntimeがBedrockを呼び出せるよう、明示的に権限を追加する必要があります。

inference-profile/* はクロスリージョン推論プロファイル用です。us.anthropic.claude-* のように us. プレフィックスがついたモデルIDを使う場合はこちらも必要になります。これを入れ忘れると権限エラーで詰まります。

参照：aws-cdk-lib.aws_iam

④ エントリポイント（bin/agentcore-cdk.ts）

import * as cdk from 'aws-cdk-lib/core';
import { AgentcoreCdkStack } from '../lib/agentcore-cdk-stack';

const app = new cdk.App();
new AgentcoreCdkStack(app, 'AgentcoreCdkStack', {
  env: { region: 'us-west-2' }, // デプロイ先リージョン
});

CDKアプリのエントリポイントです。env.region でデプロイ先のAWSリージョンを指定します。今回私はus-west-2（オレゴン）を指定しています。

デプロイ

コードを実装したら、以下のコマンドでデプロイします。

# CDKブートストラップ（初回のみ・AWSアカウントとCDKを紐付ける作業）
npx cdk bootstrap

# デプロイ
npx cdk deploy

動作確認

最後に動作確認をしたところ、確認できました。

image.png

さいごに

CDKを使うことで、DockerビルドからECRへのプッシュ、AgentCore Runtimeの作成まで完了できました。
最初はそもそも何を調べればいいんじゃ（涙）といった感じでした笑
全くの初心者が触るにはかなりの難易度でしたが、その分サービスそのものに対する理解度はかなり高まりました。今までマネコンに甘やかされていました。
CDKに関しては今後も学び続けていきたいと思います。

参考

7
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
7
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?