簡単なAIエージェントの作成

まずは、Runtimeにデプロイして呼び出せる「動くベース」を作ります。メール署名を作成するツール(create_signature)を1つ持ったシンプルなエージェントを、agentcore create でスケルトンを起こし、ローカル動作確認→Runtimeへのデプロイまで通します。

1. Strands Agents SDKとは

Strands Agents SDKは、AWSが公開しているPython向けのエージェントフレームワークです。ツール定義とエージェントの初期化を簡潔に書けるため、Converseのツール呼び出しループを自前で回すコードよりも少ない行数でエージェントを構築できます。Strands自体はAgentCoreに閉じたものではなく、ローカルでも動かせます。

なお、フレームワークとSDKの最新の使い方は AWS Docs — Bedrock AgentCore(AWS公式ドキュメント) と Strands Agents(GitHub) に記載があります。

2. Runtimeプロジェクトの作成

この節では VSCode でフォルダを開き、AgentCore CLI(内部で Node.js を利用)で agentcore create を実行します。まず、それぞれがインストール済みかをターミナルから確認します。

code --version

以下のように 1.x.x のバージョン番号を含む3行が表示されれば、Visual Studio Code のインストールは確認できています。

1.x.x
xxxxxxxxxxxxxxxx
arm64
node --version

以下のように v20.x.x 以降のバージョン番号が表示されれば、Node.js のインストールは確認できています。

v20.x.x
agentcore --version

以下のように @aws/agentcore/x.x.x の形式でバージョン番号が表示されれば、AgentCore CLI のインストールは確認できています。

@aws/agentcore/x.x.x

表示されないツールがあれば、事前準備の Visual Studio Codeのインストール / Node.jsのインストール / AgentCore CLIのインストール から準備してください。

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

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

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

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

agentcore create

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

質問 選択・入力する値 設定の基準
Project name MyAgent ハンズオン用に分かりやすい名前を付ける
What would you like to build? Agent Runtimeにコードベースのエージェントをデプロイする(Harness はコード不要のマネージド構成、Skip は後からリソースを追加する用途)
Agent name MyAgent プロジェクトと同じ名前で識別しやすくする
Select agent type Create new agent 雛形からエージェントを新規作成する(既存コードの持ち込みや Bedrock Agents からの取り込みではない)
Language Python Strands Agents SDK を使って Python で実装する
Build Direct Code Deploy Docker不要でzipをそのままデプロイできる方式を使う
Protocol HTTP 標準のHTTPエージェントとして動かす(MCP・A2A・AG-UI は特定プロトコル向け)
Framework Strands Agents SDK 短いコードでツール呼び出しループを書ける推奨フレームワーク
Model Amazon Bedrock Bedrockで提供されるAnthropic Claudeを使う
Memory None 今回は会話履歴のマネージド保存は使わない
Customize advanced settings 何も選択せずEnter VPC接続やカスタム認証など高度な設定は今回は使わない
Review Configuration Y または Enter 表示された内容で確定する

確定すると、以下のようなフォルダ構造でプロジェクトが生成されます。

agentcore-runtime-handson/
└── MyAgent/
    ├── agentcore/
    │   ├── agentcore.json    # プロジェクトとリソースの設定
    │   ├── aws-targets.json  # デプロイ先のAWSアカウント・リージョン
    │   └── cdk/              # CDKインフラ(自動管理)
    └── app/
        └── MyAgent/
            ├── main.py       # エージェントのエントリポイント
            ├── pyproject.toml # Python依存関係
            └── ...

MyAgent/フォルダが生成されていれば、プロジェクトの作成は完了です。

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

生成されたapp/MyAgent/main.pyを、メール署名生成ツールを1つ持った Strands ベースの実装に差し替えます。LambdaによるBedrockの応用操作を身につけよう の create_signature で作ったものと同じ内容を、Strands で書き直す形になります。

3.1 完成イメージ

できあがるのは、ユーザから氏名・部署・役職・メールアドレスを受け取り、会社名と代表電話番号を付けた署名テキストを返すエージェントです。たとえば以下のプロンプトを受け取ると、

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

次のような署名を返します。

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

3.2 main.py の書き換え

Visual Studio Codeのエクスプローラーでapp/MyAgent/main.pyを開き、以下の内容で置き換えて保存します。

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()

3.3 各部の解説

コードを解説します。

COMPANY_NAME = "DevOps株式会社"
COMPANY_TEL = "03-1234-5678"

会社名と代表電話番号は、ユーザからの入力ではなく Runtime 側で持っている固定値として宣言しています。応答にこれらの値が含まれていれば「ツールが実際に呼ばれた証拠」として判断できます。

MODEL_ID = "<モデルID>"  # ap-northeast-1で利用可能なClaude Sonnetの推論プロファイルID(例: jp.anthropic.claude-sonnet-4-6)に変更してください

後述の Agent に渡すClaude モデルの推論プロファイルIDです。プレースホルダの <モデルID> を、実際に Bedrock で有効化しているモデルIDに書き換えてから保存します。

app = BedrockAgentCoreApp()

BedrockAgentCoreApp() は、Runtime が要求する /invocations と /ping の HTTP エンドポイントを自動で提供する SDK のクラスで、app として初期化しておきます。

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

@tool デコレータで関数をツールとして登録します。関数の docstring がモデルに提示される description になるため、モデルがツールをいつ使うかの判断材料になります。

    return (
        "━━━━━━━━━━━━━━━━━━━━━━\n"
        f"【{name}】{COMPANY_NAME} {department} {position}\n"
        f"Email: {email}\n"
        f"Tel:   {COMPANY_TEL}\n"
        "━━━━━━━━━━━━━━━━━━━━━━"
    )

ツール本体は、受け取った引数と、冒頭で定義した COMPANY_NAME・COMPANY_TEL を組み合わせて、装飾線付きの署名テキストを返します。

agent = Agent(
    model=BedrockModel(model_id=MODEL_ID, region_name="ap-northeast-1"),
    tools=[create_signature],
    system_prompt="あなたはメール署名を作成するアシスタントです。...",
)

Agent クラスにモデル・ツール一覧・システムプロンプトを渡すだけで、エージェントが組み立てられます。

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

@app.entrypoint デコレータで Runtime から呼び出されるエントリポイントを宣言しています。payload の prompt を agent(prompt) に渡すと、Strands が内部でモデル呼び出しとツール呼び出しのループを回してくれます。

4. ローカルでの動作確認

agentcore devは、ローカル用のPython仮想環境を自動作成し、pyproject.tomlで宣言された依存パッケージをインストールし、ローカルサーバを起動して、ブラウザでAgent Inspectorを開きます。

ローカルサーバ上のエージェントは Bedrock のモデルを呼び出すため、事前に AWS 認証情報がどの AWS アカウントと紐付いているかを設定しておく必要があります。事前準備の AWS CLIのインストール で aws configure を済ませておき、~/.aws/credentials に対象アカウントの認証情報が保存されている状態にしておきます。この認証情報は続く agentcore deploy でも同じものが使われます。

念のため、Python(agentcore dev が仮想環境作成に使用)と AWS CLI がインストール済みかを確認します。

Windowsの場合:

python --version

以下のように Python 3.x.x のバージョン番号が表示されれば、Python のインストールは確認できています。

Python 3.x.x
aws --version

以下のように aws-cli/2.x.x から始まるバージョン情報が表示されれば、AWS CLI のインストールは確認できています。

aws-cli/2.x.x Python/3.x.x Windows/xx source/exe/AMD64

Macの場合:

python3 --version

以下のように Python 3.x.x のバージョン番号が表示されれば、Python のインストールは確認できています。

Python 3.x.x
aws --version

以下のように aws-cli/2.x.x から始まるバージョン情報が表示されれば、AWS CLI のインストールは確認できています。

aws-cli/2.x.x Python/3.x.x Darwin/xx.x.x source/arm64

プロジェクトフォルダ内で実行する必要があるため、MyAgentフォルダに移動してから起動します。

cd MyAgent
agentcore dev

初回はPython venv作成と依存インストールで数十秒〜数分かかります。完了するとブラウザで Agent Inspector が開き、以下のような画面が表示されます。

チャット欄に以下の質問を入力して、右側の紙飛行機アイコンで送信します。

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

エージェントが create_signature ツールを呼び出し、応答に署名が含まれて返ってくれば、ローカルで動く状態です。

create_signature ツール自体は、装飾線と改行で整形された以下のような文字列を返しています。

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

一方、Agent Inspector のチャット表示は本文をマークダウンとしてレンダリングするため、行末のシングル \n が改行として反映されず、署名部分が1行に流れて見えます。またモデル側が「田中太郎さんのメール署名が完成しました!」の前置きや「ご確認ください!」の後書きを付けているため、ツールの戻り値がそのままの形で表示されているわけではありません。前置き・後書きの問題は、この後のシステムプロンプトのセクションで整えていきます。

会社名(DevOps株式会社)と代表電話番号(03-1234-5678)はユーザから入力していないのに応答に含まれているため、これが「モデルが自力で生成した文字列ではなく、Runtime 上の create_signature ツールを実際に呼び出して結果を受け取っている」証拠になります。応答下の「1 tool used」バッジからも、ツールが1回呼ばれたことが確認できます。Agent InspectorのTracesタブを開くと、モデル呼び出しとツール呼び出しの流れがタイムライン形式で確認できます。

このあとの各セクションでも agentcore dev は起動したままにしておきます。コードを書き換えて保存するたびに、Agent Inspectorから同じセッションで動作確認できます。

⚠️ ブラウザが自動で開かない場合
agentcore devの出力に表示されるURL(既定はhttp://localhost:8080)を手動でブラウザで開いてください。ポートが既に使用中の場合は、agentcore dev --port 8090のように別ポートを指定できます。
⚠️ 「The provided model identifier is invalid」エラーが出る場合
MODEL_ID に指定した値が、Bedrock で有効なモデル識別子として認識されていない状態です。マネジメントコンソールで ap-northeast-1(東京)の Bedrock を開き、「モデルアクセス」で使いたい Claude Sonnet モデルへのアクセスが付与されていること、および「推論プロファイル」に表示される完全形のID(jp. または apac. で始まり、末尾に -YYYYMMDD-v1:0 が付いた形式)を確認します。そのIDを main.py の MODEL_ID に貼り直して保存し、agentcore dev を再起動してください。

5. AgentCore Runtimeへのデプロイ

ローカルで動くことが確認できたら、AgentCore Runtimeへデプロイします。agentcore deployはコードをzipにパッケージング、S3へアップロード、AgentCore Runtimeへ反映、CloudWatchのロギング設定まで、CDK経由でまとめて実行します。Dockerでの手動ビルドやECRの管理は不要です。

agentcore dev は起動したままにしておき、Visual Studio Codeで 別のターミナル を新規に開きます(ターミナルパネル右上の「+」ボタン、または Ctrl+Shift+@)。新しいターミナルで MyAgent フォルダに移動してから、agentcore deploy を実行します。

cd MyAgent
agentcore deploy

初回はCDK bootstrap が走るため数分かかります。全ステップに [done] が付き、以下のように ✓ Deploy to AWS Complete が表示されればデプロイ成功です。

マネジメントコンソールのAgentCore画面を東京リージョンで開き、左メニューの「ランタイム」を選択すると、MyAgent_MyAgent が「準備完了」ステータスで表示されています。

ランタイム名(MyAgent_MyAgent)をクリックすると詳細画面が開き、ランタイム ARN(arn:aws:bedrock-agentcore:ap-northeast-1:<AWSアカウントID>:runtime/MyAgent_MyAgent-<ランダム文字列> の形式)と DEFAULT エンドポイントが確認できます。次のセクションでマネジメントコンソールや AgentCore CLI からエージェントを呼び出すときは、内部でこの ARN + エンドポイントへリクエストが届く形になります。

💡 ポイント
Direct Code Deployment(CodeZip)のパッケージには250MB(zip後)/750MB(展開後)の上限があります。上限を超える場合や、独自のシステム依存が必要な場合は、agentcore createのBuild typeでContainerを選ぶか、次章のコンテナデプロイを検討してください。上限は Direct code deployment for Python(AWS公式ドキュメント) に「The maximum size for a .zip deployment package for AgentCore Runtime is 250 MB (zipped) and 750 MB (unzipped).」と記載があります。
⚠️ 「Bootstrap AWS environment failed」エラーが出る場合
この AWS アカウントで過去に CDK を使ったことがあり、CDKToolkit スタックの状態が不整合になっている場合に発生します(詳細エラーは MyAgent/agentcore/.cli/logs/deploy/deploy-*.log に出力されます)。新しいターミナルで、標準の CDK CLI から手動で bootstrap を実行すると解消できるケースが多いです。agentcore deploy の出力に表示される Target: ap-northeast-1:<AWSアカウントID> の数字を控えたうえで、npx cdk bootstrap aws://<AWSアカウントID>/ap-northeast-1 を実行してください。✅ Environment aws://... bootstrapped. と表示されたら、元のターミナルに戻って agentcore deploy を再実行します。

6. デプロイしたエージェントの動作確認

デプロイしたエージェントは、マネジメントコンソールのテストUIからも、AgentCore CLI からも呼び出せます。両方を試して、動作確認のパターンを押さえます。

6.1 AWSマネジメントコンソールからの確認

先ほどのランタイム詳細画面の 右上「テスト」ボタン をクリックすると、コンソール上のテストUIが開きます。

テスト画面で ランタイムエージェント に MyAgent_MyAgent、エンドポイント に DEFAULT が選択されていることを確認し、入力 欄に以下のJSONを貼り付けて「実行」をクリックします。

{"prompt": "田中太郎(開発部 エンジニア、tanaka@example.com)のメール署名を作って"}

出力 欄に {"result": "..."} の形式で、装飾線付きの署名テキストを含む JSON が返れば、AgentCore Runtime 上でエージェントが動作している状態です。

6.2 CLIからの確認

同じエージェントを AgentCore CLI からも呼び出してみます。agentcore deploy を実行したターミナル(MyAgent フォルダにいる状態)で、以下を実行します。

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

以下のような実行結果が表示されます。

田中太郎さんのメール署名が完成しました!以下をご利用ください。

---

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

---

会社名(DevOps株式会社)と代表電話番号(03-1234-5678)は自動で付与されています。何かご不明な点があればお気軽にどうぞ!


Session: 42560264-c9db-45c5-9237-e3fd45c1e4c7
To resume: agentcore invoke --session-id 42560264-c9db-45c5-9237-e3fd45c1e4c7
Log: <MyAgentプロジェクトのパス>/agentcore/.cli/logs/invoke/invoke-MyAgent-<YYYYMMDD-HHMMSS>.log

会社名と代表電話番号が入った署名が返れば、AgentCore Runtime 上でエージェントが動作している状態です。マネジメントコンソールで対象のエージェントの Observability 画面を開くと、ツール呼び出し・レイテンシ・トークン数などのトレース情報が確認できます。

ここまでで「動くベース」の作成は完了です。ここからは、実務で AI エージェントを設計・実装する際に必ず押さえておきたい SDK の基本文法を、これまでの main.py を土台にしながら6つのセクションで「概要 → コードを書き換え → コードの解説 → 動作確認」の4ステップで1つずつ体感します。1つ目のターミナルでは引き続き agentcore dev が起動しているため、コードを書き換えて保存するたびに Agent Inspector から動作確認できます。