agents-get-started

get-started

開発者がゼロからAWS上で動作するエージェントを作成できるよう案内します。

使用する場面

• 開発者がAWS上でエージェントを構築したいものの、何から始めればよいかわからない場合
• 開発者が新しいAgentCoreプロジェクトを作成したい場合
• 開発者がフレームワーク（Strands、LangGraph、GoogleADK、OpenAI Agents）の選択に迷っている場合
• 開発者が agentcore create を実行した直後で、次に何をすればよいか知りたい場合

次の用途には使用しないでください。

• 環境や前提条件に関する問題（CLIが見つからない、認証情報が壊れているなど）→ agents-debug を使用
• 既存プロジェクトへの機能追加（メモリ、ツール、ポリシーなど）→ agents-build または agents-connect を使用
• 既存のBedrock Agentの移行 → agents-build を使用（references/migrate.md を読み込みます）

入力

$ARGUMENTS には次の内容を指定できます。

• フレームワークの希望：「LangGraphを使用」「Strandsを使用」
• プロトコル：「MCP server」「A2A」
• エージェントに行わせたいことの説明：「カスタマーサポートエージェント」
• 空欄 — このスキルがフレームワークの選択を案内します

プロセス

ステップ0：CLIのバージョンを確認する

agentcore --version

このスキルにはv0.9.0以降が必要です。

バージョンが古い場合：

AgentCore CLIが古くなっています（検出したバージョン：vX.Y.Z、必要なバージョン：v0.9.0以降）。

更新の実行を提案します：agentcore update。更新が完了したら、バージョンを再確認し、続行する前に≥0.9.0であることを確認します。開発者がすでに指定したコンテキスト（フレームワークの希望、プロジェクト名、作成したいもの）を保持し、再度伝える必要がないようにします。

agentcore が見つからない場合：

AgentCore CLIがインストールされていません。npm install -g @aws/agentcore を実行してください（Node.js 20以降が必要です）。 インストールで問題が発生している場合は、agents-debug スキル（references/doctor.md を読み込みます）を実行して環境を診断できます。

ステップ1：意図を確認する — 情報収集か、作成の準備ができているか？

フレームワークの選択に進む前に、開発者の状況を確認します。

開発者に尋ねます：「選択肢を調べているところですか（フレームワークの比較、AgentCoreでできることの理解など）、それともプロジェクトを作成する準備ができていますか？」

• 情報収集 → ステップ2（フレームワークの比較）に進みます。選択肢を提示して質問に答え、返答を待ちます。準備ができたと伝えられるまで、create コマンドを組み立てないでください。
• 作成の準備ができている → ステップ3（プロジェクトの作成）に進みます。すでにフレームワークが指定されている場合は、ステップ2を完全にスキップします。
• すでにプロジェクトがある → 現在のディレクトリで agentcore/agentcore.json を探します。見つかったら読み込み、ステップ5（次に行うこと）に進みます。再度スキャフォールドしないでください。

$ARGUMENTS から開発者の意図が明らかな場合（例：「MyBotという名前のStrandsエージェントを作成」）、そのままステップ3に進みます。

ステップ 2：フレームワークの選択

まず、会話のコンテキストを確認してください。 開発者がこの会話の前の段階で（たとえば、以前にスキルを実行した際に）すでにフレームワークについて話し合っている場合は、表全体を再提示しないでください。話し合った内容を要約して、決定したか、何か変更があったかを尋ねてください。

フレームワークについて話し合うのが初めての場合は、次の選択肢を提示してください。

サポート対象のフレームワーク（CLI でスキャフォールド、Python）：

フレームワーク	CLI の値	最適な用途
Strands	Strands	AWS ネイティブで、最も簡単に始められ、AgentCore との統合が最適
LangGraph	LangChain_LangGraph	複雑なグラフベースのワークフロー、既存の LangChain への投資がある場合
Google ADK	GoogleADK	すでに Google のエージェントツールキットを使用しているチーム
OpenAI Agents	OpenAIAgents	すでに OpenAI のエージェント SDK を使用しているチーム

開発者に選択してもらってください。 選択肢を提示し、選択を待ってください。明示的に「特に希望はない」と言われない限り、デフォルトを決めつけないでください。

名前に関する注意： CLI のフラグ値は、--framework に渡す正確な文字列です。文章では短い名前を使ってください。

デフォルトの推奨（開発者が「特に希望はない」または「選んで」と言った場合のみ）：Strands — AWS ネイティブのフレームワークで、AgentCore との統合が最も緊密であり、サンプルやドキュメントも最も充実しています。

確認すべき主な判断ポイント：

• 「LangGraph または OpenAI Agents で既存のエージェントコードをお持ちですか？」→ そのフレームワークを使用します
• 「条件分岐を含む複雑なグラフベースのワークフローが必要ですか？」→ LangGraph
• 「特に希望はなく、新たに始めますか？」→ Strands

一覧にないフレームワークの場合

開発者が上の表にないフレームワークについて尋ねた場合は、次のように対応してください。

尋ねられたもの	回答内容
CrewAI、AutoGen、Semantic Kernel	CLI ではスキャフォールドされませんが、BYO Container パス（以下を参照）を使って利用できます。AgentCore Runtime はフレームワークに依存しません。HTTP コントラクトを実装するコードであれば、どれでも動作します。
Anthropic SDK / Claude Agent SDK	これはモデル SDK であり、エージェントフレームワークではありません。任意のフレームワーク（Strands、LangGraph など）内で使用するか、単独で使用できます。単独で使用する場合は、Runtime コントラクトを満たすコンテナでラップしてください。
Claude Code / Cursor / Copilot	これらは IDE ツールであり、エージェントフレームワークではありません。エージェントコードをデプロイする対象ではなく、エージェントコードを記述するためのツールです。エージェント自体には、上の表からフレームワークを選択してください。
LangChain（LangGraph なし）	LangChain はライブラリであり、LangGraph はその上に構築されたエージェントフレームワークです。CLI では LangGraph をスキャフォールドします。通常の LangChain チェーンを使用する場合は、BYO Container パスを利用できます。
カスタム／独自のフレームワーク	BYO Container パスを利用してください。以下を参照してください。

BYO Container パス（任意のフレームワーク、任意の言語）：

CLI でスキャフォールドされないフレームワークや言語の場合、AgentCore Runtime は HTTP コントラクト（POST /invocations、GET /ping）を実装する任意のコンテナを受け入れます。手順は次のとおりです。

1. agentcore create --name <ProjectName> --defaults でプロジェクトの構成をスキャフォールドします
2. agentcore add agent --type byo --build Container --language <Language> --code-location <path> でコードを登録します
3. エージェントをビルドして実行する Dockerfile を作成します
4. agentcore deploy で ECR へのプッシュ、CDK インフラストラクチャ、Runtime の作成を行います

言語別の注意事項：

言語	推奨パス
Java（Spring Boot）	AgentCore 用 Spring AI SDK — Runtime コントラクト、SSE ストリーミング、ヘルスチェックに対応します。--language Other --build Container を使用してください。
JavaScript / TypeScript	Express、Fastify などで Runtime コントラクトを実装します。--language TypeScript --build Container を使用してください。
Go、Rust、.NET、その他	Runtime の HTTP コントラクトを実装します。--language Other --build Container を使用してください。

コンテナが正しくビルドできれば、このスキルの残りの手順（デプロイ、ステータス、ログ、呼び出し）を適用できます。

フレームワークとモデルプロバイダー — よくある混同

フレームワークは、エージェントをどのようにオーケストレーションするかを決めるものです（Strands、LangGraph など）。モデルプロバイダーは、呼び出す LLM を決めるものです（Bedrock、Anthropic、OpenAI、Gemini）。これらはそれぞれ独立して選択できます。

• Strands + Bedrock（デフォルト）— すべて AWS ネイティブ
• Strands + Anthropic — Strands によるオーケストレーションと、モデル用の Anthropic API の直接利用
• LangGraph + Bedrock — LangGraph によるオーケストレーションと、モデル用の Bedrock
• OpenAI Agents + OpenAI — すべて OpenAI

開発者が「Claude を使いたい」と言う場合、指しているのはモデルプロバイダー（Bedrock または Anthropic）であり、フレームワークではありません。「LangGraph を使いたい」と言う場合は、フレームワークを指しています。

ステップ 3：プロジェクトを作成する

開発者の選択に基づいて、agentcore create コマンドを作成します。

コマンドを作成する前に、プロジェクト名を検証してください。 CLI はエラーの表示が遅く、名前が無効な場合、プロンプトへの回答やコマンド全体の作成が終わってからエラーが表示されます。やり直しを避けるため、最初に次のルールを確認してください。いずれかに違反する場合は名前を受け付けず、新しい名前を尋ねてください。

• 長さは 23 文字以下（多くの開発者が想定するより短いです。MyCustomerSupportAgent は 22 文字で使用できます。CustomerSupportChatbot も 22 文字で使用できます。MyCustomerSupportBotApp は 23 文字で、ちょうど使用できます。MyCustomerSupportChatBot は 24 文字のため使用できません）
• 英数字のみ — ハイフン、アンダースコア、ピリオド、スペースは使用できません
• 英字で始める必要があります

上限に近い場合は、文字数を声に出して伝えてください。「その名前は 24 文字です。CLI で使えるプロジェクト名は 23 文字までです。<suggestion> に短縮しますか？」CLI のエラーメッセージが分かりやすいだろうと考えて、無効な名前でコマンドを実行してはいけません。エラーメッセージは必ずしも明確ではなく、その後のコマンドに対する開発者の理解も誤ったものになります。

コマンドを作成したら、開発者が実行する前に提示して確認を求めてください。 すべてのフラグを含むコマンド全体を示し、それぞれの選択が意味することを説明してください。続行する前に、開発者の確認または変更を待ってください。

提示例：

これまでに伺った内容に基づいて、次のコマンドをおすすめします。

agentcore create --name MyAgent --framework Strands --model-provider Bedrock --build CodeZip --memory none

Bedrock モデルを使う Strands エージェントを、コード ZIP としてデプロイします（Docker は不要です）。メモリは後から追加できます。

このまま実行しますか？それとも何か変更しますか？

コマンドを自動的に実行してはいけません。コマンドを提示し、返答を待ってください。

最小構成（デフォルト — Strands、Bedrock、CodeZip、メモリなし）：

agentcore create --name <ProjectName> --defaults

特定のオプションを指定する場合：

agentcore create \
  --name <ProjectName> \
  --framework <Framework> \
  --model-provider Bedrock \
  --build CodeZip \
  --memory none

フラグの説明：

フラグ	値	デフォルト
--name	英数字、最大 23 文字	プロンプトで指定
--framework	Strands、LangChain_LangGraph、GoogleADK、OpenAIAgents	プロンプトで指定
--protocol	HTTP、MCP、A2A	HTTP
--build	CodeZip、Container	CodeZip
--model-provider	Bedrock、Anthropic、OpenAI、Gemini	プロンプトで指定
--memory	none、shortTerm、longAndShortTerm	プロンプトで指定
--network-mode	PUBLIC、VPC	PUBLIC
--dry-run	—	作成せずにプレビュー

選択に関するガイダンス：

• プロトコル： 開発者が MCP ツールの提供または A2A によるエージェント間通信を特に必要としていない限り、HTTP を使用してください
• ビルド： 開発者がカスタムのシステム依存関係を必要としていない限り、CodeZip を使用してください（CodeZip はデプロイが速く、ローカルに Docker をインストールする必要もありません）
• モデルプロバイダー： 開発者が別のプロバイダーを使う明確な理由がない限り、Bedrock を使用してください（Bedrock では API キーの管理が不要です）
• メモリ： まずは none にしてください。開発者が必要になった時点で、agents-build からメモリを追加できます（references/memory.md を読み込みます）

ステップ 4：作成したものを説明する

プロジェクトが作成されたら、agentcore/agentcore.json と生成されたコードを読み、プロジェクト構造を説明します。

以下のレイアウトは CLI v0.9.x を反映しています。CLI のバージョンが異なる場合は、tree <ProjectName>/ -L 3 を実行して実際に生成された構造を確認し、それに基づいて説明してください。

<ProjectName>/
├── agentcore/
│   ├── agentcore.json      ← Project config (agents, resources)
│   ├── aws-targets.json    ← AWS account + region
│   ├── .env.local          ← Local environment variables (gitignored)
│   └── cdk/                ← CDK infrastructure (auto-managed, don't edit)
└── app/
    └── <AgentName>/
        ├── main.py          ← Your agent code — this is where you build
        ├── mcp_client/      ← Pre-wired example MCP client (see note below)
        └── pyproject.toml   ← Python dependencies

主なファイル：

• app/<AgentName>/main.py — エージェントのエントリーポイントです。開発者はここにツール、システムプロンプト、ロジックを追加します。
• agentcore/agentcore.json — プロジェクトの設定ファイルです。agentcore add コマンドでリソースを追加します。
• agentcore/.env.local — ローカル環境変数です。デプロイ後、ローカル開発用のリソース ID がここに書き込まれます。

スキャフォールドに含まれる MCP クライアントについての注意点。 main.py は mcp_client/client.py から get_streamable_http_mcp_client() をインポートし、それを tools に追加します。新規プロジェクトでは、このクライアントは公開されているサンプル MCP エンドポイントを参照するため、すぐに agentcore dev を実行できます。注意点は 2 つあります。

1. まだデプロイされていないゲートウェイを参照するよう変更すると、何も起きない状態になります。 よくある方法は、サンプルのエンドポイントを os.getenv("AGENTCORE_GATEWAY_<NAME>_URL") に置き換えることです。この環境変数は agentcore deploy の後にのみ設定されます。開発者が参照先を変更し、デプロイ前に agentcore dev を実行すると、get_streamable_http_mcp_client() は URL が None のクライアントを返し、エージェントは MCP ツールが 0 個の状態で起動します。エラーも警告も表示されません。ガードパターンについては、agents-connect の「ローカル開発のギャップ」セクションを参照してください。if not GATEWAY_URL: tools = [] のようにします。
2. 開発者が MCP ツールをまったく必要としない場合は、 mcp_clients リストと、それを tools に追加するループを削除します。スキャフォールドに含まれているのは利便性のためであり、必須ではありません。

agents-connect のリファレンスクライアントコード（パス A）には、デプロイ後にゲートウェイ経由で MCP クライアントを接続する正しいパターンが示されています。

ステップ 5：ローカル開発

agentcore dev

これによりローカル開発サーバーが起動します。開発者はすぐにエージェントとやり取りできます。

開発サーバーがバインドするポート（curl 呼び出しのスクリプト作成や、別のプロセスからのテストを行う場合に重要です）：

プロトコル	デフォルトのポート
HTTP	8080
MCP	8000
A2A	9000

CLI は起動時にバインドされたポートと URL を出力します。ハードコードせず、必ず CLI の出力から実際の値を確認してください。デフォルトのポートがすでに使用中の場合、 CLI はポート番号を自動的に増やします（例：8080 → 8081 → 8082）。そのため、2 つ目の開発セッションや前回の実行から残っているプロセスによって、警告なしにポートが変わることがあります。agentcore dev --port <N> を使ってポートを固定するか、呼び出しが接続拒否または終了コード 7 のエラーで失敗し始めたら、ps を grep するか、CLI のバナーを確認してください。

必ず伝えるべき重要な制限事項：

• agentcore dev ではメモリを利用できません。利用するにはデプロイが必要です。
• ローカルではゲートウェイ URL を利用できません。利用するにはデプロイが必要です。
• ローカルサーバーは、プロジェクトで設定されたモデルプロバイダーを使用します。

ステップ 6：初回デプロイ

開発者がデプロイする準備ができたら：

agentcore deploy

次の処理が行われます。

1. 作成される AWS リソースのプレビューを表示します
2. 確認を求めます
3. CDK 経由でビルドしてデプロイします

初回のデプロイには 3～5 分かかります。 2 回目以降のデプロイはより速くなります。

デプロイ後、次の方法で呼び出す手順を説明します。

agentcore invoke "Hello, what can you do?"

また、次の方法でステータスを確認する手順も説明します。

agentcore status

ステップ 7：次にすること

開発者が作りたいものに基づいて、次に進むのに適したスキルを提案します。

開発者の意図	次のスキル	コマンドのヒント
「アプリから呼び出すにはどうすればよいですか？」	agents-build	agentcore fetch access
「情報を記憶させたいです」	agents-build	agentcore add memory
「外部 API を呼び出したいです」	agents-connect	agentcore add gateway
「できることを制限したいです」	agents-connect	agentcore add policy-engine
「品質を測定したいです」	agents-optimize	agentcore add evaluator
「本番環境に移行したいです」	agents-harden	本番環境への準備状況チェックリスト
「複数のエージェントを連携させたいです」	agents-build	agentcore create --protocol A2A
「VPC 内で利用したいです」	agents-build	agentcore create --network-mode VPC

提案しすぎないようにします。開発者が実際に尋ねた内容に基づいて、次のステップを 1 つか 2 つ提案します。

ウォークスルーの例

タスクを提示したプロンプト（例：「カスタマーサポートエージェントを作成する」）の場合は、該当するサンプルのリファレンスを読み込みます。

開発者のタスク	リファレンス
カスタマーサポート、チャットボット、ポリシーに関する質問への回答	references/example-support-agent.md

よくあるパターンが見つかったら、このスキルの references ディレクトリにサンプルを追加できます。

出力

• 「エージェントを作りたい」という段階から、実行中のデプロイ済みエージェントに至る明確な道筋
• 開発者の選択に合わせた agentcore create コマンド
• 生成されるプロジェクト構成の説明
• 開発者の意図に基づく具体的な次のステップ

品質基準

• agentcore create コマンドでは、CLI v0.9.1 の有効なフラグのみを使用する
• フレームワークの推奨は、一般的なデフォルトではなく、開発者の状況に基づいている
• 開発者が生成された各ファイルの役割を理解できる
• 次のステップは、すべての機能を並べた一般的なリストではなく、開発者が作りたいものに即した内容である