はじめに
みなさんは agentcore create を実行したことはあるだろうか。
以前の記事で、AgentCoreのCLIにはpip版（Legacy）とnpm版（現行）の2種類があることを書いた。
(以前の記事はこちら)
https://qiita.com/toshi-arch/items/5a791548dc4ccadc9ab0
npm install -g @aws/agentcore
これが現在の正しいインストール方法。
で、インストールしたあと agentcore create を実行すると...いくつかの質問に答えただけで、見たことないファイルたちがわーっと生成される。
「動いてるからまあいいか」って思いながらも、内心は「このファイル、何？？」だった...。
この記事では、その生成されたテンプレートファイルが何者なのかを一つずつ整理する。
agentcore create を実行すると何が聞かれるか
対話モードで実行するとウィザード形式で質問が来る。
agentcore create
まず「プロジェクト名」を聞かれ、次に「今すぐエージェントを追加するか？」と聞かれる。Yes を選ぶと以下の順に質問が続く。
| ステップ | 選択肢 |
|---|---|
| エージェント名 | 英数字・最大36文字 |
| エージェントのタイプ | Create new agent / Bring my own code / Import from Bedrock Agents |
| 言語 | Python（TypeScript は coming soon） |
| ビルド方式 | Direct Code Deploy / Container |
| プロトコル | HTTP（デフォルト）/ MCP / A2A / AG-UI |
| フレームワーク | Strands Agents SDK / LangChain + LangGraph / Google ADK / OpenAI Agents |
| モデルプロバイダー | Amazon Bedrock / Anthropic / OpenAI / Google Gemini |
| メモリ | None / Short-term memory / Long-term and short-term |
全部答えると確認画面が出て、Enterで生成が始まる。
全部デフォルト（Python / Strands / Bedrock / メモリなし / Direct Code Deploy / HTTP）でよければ --defaults フラグでウィザードをスキップできる。
agentcore create --name MyAgent --defaults
生成されるファイル構成
実際に生成されるのはこんな構成だった。
MyAgent/
├── AGENTS.md # AIコーディングアシスタント向けの説明ファイル
├── README.md
├── agentcore/ # 設定・インフラ系（触るのはJSONだけ）
│ ├── agentcore.json # プロジェクト全体の設計図
│ ├── aws-targets.json # デプロイ先のAWSアカウント・リージョン
│ ├── .env.local # APIキーなど（gitignore済み）
│ ├── .llm-context/ # AI向けのTypeScript型定義（触らない）
│ └── cdk/ # CDKプロジェクト（触らない）
└── app/
└── MyAgent/ # エージェントの実装本体（ここを育てる）
├── main.py
├── pyproject.toml
├── model/
│ └── load.py # モデルの設定
└── mcp_client/
└── client.py # MCPクライアントの設定
ドキュメントには載っていないファイルもいくつかある。一つひとつ見ていこうと思う。
各ファイルの正体
agentcore/agentcore.json ── このプロジェクトの"設計図"
一番重要なファイル。エージェントの構成がすべてここに書かれている。
{
"$schema": "https://schema.agentcore.aws.dev/v1/agentcore.json",
"name": "MyAgent",
"version": 1,
"managedBy": "CDK",
"tags": {
"agentcore:created-by": "agentcore-cli",
"agentcore:project-name": "MyAgent"
},
"runtimes": [
{
"name": "MyAgent",
"build": "CodeZip",
"entrypoint": "main.py",
"codeLocation": "app/MyAgent/",
"runtimeVersion": "PYTHON_3_14",
"networkMode": "PUBLIC",
"protocol": "HTTP"
}
],
"memories": [],
"credentials": [],
"evaluators": [],
"onlineEvalConfigs": [],
"agentCoreGateways": [],
"policyEngines": [],
"configBundles": [],
"abTests": [],
"httpGateways": []
}
agentcore add memory とか agentcore add gateway を実行すると、memories や agentCoreGateways の配列に記述が追加されていく仕組みになっている。つまり CLIで操作した内容の結果がすべて反映される設計図 だと思う。
agentcore deploy を実行したとき、CLIはまずこのファイルを読んで「何をAWSに作ればいいか」を判断している。
agentcore/aws-targets.json ── どのAWSアカウント・どのリージョンにデプロイするか
[]
生成直後はこれだけ...。空の配列だった。
agentcore deploy を初めて実行したときに、AWSアカウントIDとリージョンが自動で書き込まれるようになっているようだ。
agentcore/.env.local ── APIキーの置き場所
BedrockではなくAnthropic・OpenAI・Geminiをモデルプロバイダーに選んだ場合、APIキーをここに書く。
gitignoreされているのでリポジトリには含まれない。安心して書ける。
Bedrockを使う場合はAWSの認証情報（~/.aws/credentials など）で動くので、ここは空のままでいい。
app/MyAgent/main.py ── エージェントの実装本体
フレームワーク（今回はStrands）のスターターコードが入った状態で生成される。
from strands import Agent, tool
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from model.load import load_model
from mcp_client.client import get_streamable_http_mcp_client
app = BedrockAgentCoreApp()
# サンプルツールの定義
@tool
def add_numbers(a: int, b: int) -> int:
"""Return the sum of two numbers"""
return a + b
# エントリーポイント
@app.entrypoint
async def invoke(payload, context):
agent = Agent(model=load_model(), tools=[add_numbers])
stream = agent.stream_async(payload.get("prompt"))
async for event in stream:
if "data" in event and isinstance(event["data"], str):
yield event["data"]
if __name__ == "__main__":
app.run()
（実際のコードは少し長いので要点だけ抜粋）
ポイントは2つ。
-
BedrockAgentCoreApp()でAgentCoreのランタイムに乗せるためのラッパーを作る -
@app.entrypointデコレータをつけた関数が、AgentCoreから呼ばれるエントリーポイントになる
ここが唯一、自分でゴリゴリ書き換えていく場所。他のファイルは基本CLIが管理してくれる。
app/MyAgent/model/load.py ── モデルの設定
from strands.models.bedrock import BedrockModel
def load_model() -> BedrockModel:
return BedrockModel(model_id="global.anthropic.claude-sonnet-4-5-20250929-v1:0")
main.py から呼ばれている。使うモデルを変えたいときはここのモデルIDを変更する。
app/MyAgent/pyproject.toml ── Python依存関係の管理
[project]
dependencies = [
"aws-opentelemetry-distro",
"bedrock-agentcore >= 1.0.3",
"strands-agents >= 1.13.0",
"mcp >= 1.19.0",
...
]
agentcore dev を実行したときにこのファイルを読んで、Python仮想環境（venv）が自動でセットアップされる。
AGENTS.md ── AIコーディングアシスタント向けのコンテキストファイル
これが一番「なんだこれ！！」だった。
Claude CodeなどのAIコーディングアシスタントがこのプロジェクトを理解するための説明書になっている。agentcore.json の構造・スキーマ・CLIコマンドの使い方などが書かれていて、AIがこのファイルを読むことで正しいコード補助ができるようになる設計だと思う。
agentcore/.llm-context/ ── AI向けのTypeScript型定義
同じくAIアシスタント向けに用意されたTypeScriptの型定義ファイル群。agentcore.json の各フィールドにどんな値が入るか（型・バリデーション制約など）が書かれている。
AGENTS.md にも「DO NOT EDIT THESE FILES」と書いてあるとおり、自分で触る必要はない。
ファイルたちが実際にどう使われるか
生成されたファイルが各コマンドでどう動くかを整理するとこうなる。
agentcore dev
└─ pyproject.toml を読んで venv をセットアップ
└─ main.py を実行してローカルサーバー起動（ポート8080）
└─ ブラウザで Agent Inspector を開く
agentcore deploy
└─ agentcore.json を読んで「何を作るか」を確認
└─ aws-targets.json を読んで「どこに作るか」を確認
└─ app/ のコードをzip化してS3へ（Direct Code Deployの場合）
└─ CDKでCloudFormationスタックを作成・更新
main.py を育てて → agentcore dev でローカルテスト → agentcore deploy でAWSへ、というのが基本の開発ループ。
おわりに
正直、最初は「なんかファイルがいっぱい生成されたな...」くらいにしか思っていなかった。
でも一つひとつ調べてみると、役割分担がはっきりしていて理にかなった構成だとわかった！！
- 設定は
agentcore.jsonに集約 - コードは
app/の中だけ触ればいい - AIコーディングアシスタントへの配慮まで組み込まれている
この構造を知っているだけで、次に agentcore add を実行したとき「あ、agentcore.json が更新されるんだな」と予測できるようになる。同じように「ファイルの正体がよくわからない」と思っていた人の参考になれば！！