@jus1730(ジャス)Team Coffee

Kiro x Amplify Gen 2 - AG-UIに対応した新しいテンプレートを作成してみた

Posted at 2026-06-14

はじめに

まずは結論から

Kiroで使うためのAmplify Gen 2 テンプレートを刷新。変更点は主にAIエージェント周り
通信プロトコルをAG-UIに変更し、フロントUIをCopilotKitで標準化
エージェント管理を AgentCore CLI（@aws/agentcore） に統一
認証は IAM（SigV4） 方式を採用し、Amplify Hosting の Lambda がサーバーサイドで署名
テンプレートは GitHub に公開

想定される読者

前回のテンプレート記事を読んでくださった方
Kiro x Amplify Gen 2 でAIエージェント付きWebアプリを構築してみたい方
AG-UIプロトコルや Agent Toolkit for AWS に興味のある方

なぜテンプレートを改定したのか

前回作成したテンプレートでも開発体験自体は全然悪くありませんでした。

ただAIエージェント周りのアップデートが多くてAG-UIとかCopilotKitとかが気になっていたのと、AWS MCPサーバーもGAしたのでそれらに対応した形にバージョンアップしようと思いました。

また、Agentcore Runtimeのデプロイ手順は正直微妙だったので、見直しのために最近推奨になったAgentCore CLIに変更してみました。

変更点の詳細

1. AIエージェントプロトコル: AG-UI + CopilotKit

今回最大の変更点です。

AG-UI とは

AG-UI（Agent-User Interaction Protocol）は CopilotKit が開発したオープンプロトコルで、AIエージェントとフロントエンドの間のリアルタイム通信を標準化するものです。

実態の通信プロトコルとしてはHTTP、WebSocketなど複数対応しています。

MCPがエージェント↔ツール間の接続を標準化するのに対して、AG-UIはエージェント↔ユーザーUI間の接続を標準化する位置づけです。

最近 AWS も FAST (Fullstack AgentCore Solution Template) で CopilotKit を採用するなど、結びつきが強くなっているようでしたので、今回は CopilotKit も使ってみることにしました。

AG-UI + CopilotKit のメリット

CopilotKit を入れることで、ブラウザ → API Route（Lambda）→ AgentCore Runtime という中間層が必要になります。旧テンプレートのようにブラウザから直接呼ぶ構成に比べてシステム構成は複雑になりますが、それを補う利点があります。

チャットUIが数行で完成 — CopilotChat コンポーネントを置くだけ。SSEパースやメッセージ管理のコードが不要に
SigV4 署名の置き場が自然にできる — API Route（Lambda）がプロキシとして署名するため、ブラウザにAWSクレデンシャルを渡す必要がない
HttpAgent のカスタム fetch で、認証やヘッダー付与のロジックを1箇所に集約できる

前回は SSE のパース処理やチャット UI を自前で書いており、認証周りのコードもフロントエンドに散らばっていました。中間層が増えた分、責務の分離がきれいになっています。

実際は Kiro がコーディングすることになるので、利用者が直接的な恩恵が得られるかは微妙ですが、独自実装が減る分システム品質が上がったりアプリごとのバラツキが減ったりすれば良いかなぁと思ってます。実際に何か作ってみないことにはちゃんと評価できないですね。

フロントエンド側は以下の2パッケージを追加しています。

"@copilotkit/react-core": "^1.59.5",
"@copilotkit/react-ui": "^1.59.5"

エージェント側は ag-ui-strands で Strands Agent をラップします。なお ag-ui-strands は Python 3.12〜3.13 を要求するため（3.14 は非対応）、前回の Python 3.10+ から要件が上がっています。

# agents/pyproject.toml の主要依存
dependencies = [
    "strands-agents>=0.1.0",
    "strands-agents-tools>=0.1.0",
    "ag-ui-strands>=0.1.0",
    "fastapi>=0.115.0",
    "uvicorn>=0.34.0",
]

接続の全体像

最終的な構成は以下のようになります。

ポイントは、ブラウザから AgentCore Runtime を直接呼ぶのではなく、Amplify Hosting の SSR Lambda（API Route）がプロキシとして SigV4 署名を行う点です。CopilotKit の公式テンプレートでも同じ構成が推奨されています。

2. AWS MCPサーバー: Agent Toolkit for AWS（GA）

2026年5月、AWS MCPサーバーがAgent Toolkit for AWSの一部としてGAになりました。

主な改善点

任意のAWS API呼び出しが可能に（ファイルアップロードや長時間実行も対応）
40以上のAgent Skillsを搭載（IaC、サーバーレス、コンテナ、AI等）
IAMベースのガードレールで、エージェントが実行できるアクションを制御
CloudWatch / CloudTrail連携による可観測性

Skills搭載でPowersの必要性が減った

個人的に一番大きいのはここです。Agent Skills がMCPサーバー内にビルトインされたことで、Kiro側にAWS関連のPowers（aws-amplify等）を入れなくても、MCPサーバー経由でAWSの最新ドキュメントやベストプラクティスを参照できるようになりました。

Skillsはローカルインストール不要で、必要時にオンデマンドで検索・実行されます。

ただし「必要な時にちゃんとSkillsを見に行ってくれるか」は正直まだ不安が残ります。明示的に「AWS MCPでSkillsを確認して」と指示した方が確実な場面もありそうです。この辺りは実際にアプリ開発を進めながらの調整になりますね。

3. AgentCore CLI の正式化

エージェントのライフサイクル管理が AgentCore CLI（@aws/agentcore） に統一されました。

Starter Toolkit → AgentCore CLI で何が良くなったか

旧版の Starter Toolkit（bedrock-agentcore-starter-toolkit）は pip パッケージで提供される最小限のデプロイツールでした。新しい AgentCore CLI は Node.js パッケージとして再設計され、エージェント開発の体験が大きく変わっています。

項目	旧 Starter Toolkit	新 AgentCore CLI
インストール	`pip install`	`npm install -g @aws/agentcore`
プロジェクト生成	なし（手動作成）	`agentcore create`（対話UIでフレームワーク・プロトコル選択）
ローカル開発	自作スクリプト	`agentcore dev`（ホットリロード + Agent Inspector）
プロトコル	HTTP のみ	HTTP / AG-UI / MCP / A2A
ビルド	Container のみ（Docker必須）	CodeZip（Docker不要）/ Container
デプロイ	`agentcore launch`（設定更新が面倒）	`agentcore deploy`（CDKベース、`--plan` でドライラン可）

特に特徴的なのは以下の3点です。

agentcore create の対話UI — フレームワーク（Strands / LangGraph / Google ADK / OpenAI Agents）とプロトコル（AG-UI 等）を選ぶだけでプロジェクト一式が生成される
agentcore dev — ホットリロード付きのローカル開発サーバーが立ち上がり、ブラウザで Agent Inspector も開く。コード変更 → 即反映で試行錯誤が楽に
CodeZip デプロイ — ローカルに Docker がなくてもデプロイ可能。ARM64 ビルドは AWS 側（CodeBuild）で実行される

旧版 starter toolkit との競合に注意

前回のテンプレートで使っていた旧版（bedrock-agentcore-starter-toolkit）は pip でインストールする Python パッケージですが、新版の AgentCore CLI（@aws/agentcore）は npm でインストールする Node.js パッケージです。どちらも agentcore コマンドを登録するため、旧版が残っているとコマンドが衝突します。

新しい CLI を入れる前に、旧版をアンインストールしてください。

# 旧版の削除
pip uninstall bedrock-agentcore-starter-toolkit

# 新版のインストール
npm install -g @aws/agentcore

starter toolkit の公式ドキュメントにも「AgentCore CLI（@aws/agentcore）が推奨」と記載されており、Migration Guide も用意されています。前回のテンプレートを使っていた方は移行をおすすめします。

コマンド体系の変更

操作	旧テンプレート	今回
初期化	`agentcore configure`	`agentcore create`
ローカル開発	`python scripts/run_agentcore_local.py`	`agentcore dev`
デプロイ	`agentcore launch`	`agentcore deploy`
削除	`agentcore destroy`	`agentcore remove all` → `agentcore deploy`
エージェント追加	手動作成	`agentcore add agent`

agentcore destroy というコマンドは存在しません。リソースを削除するには agentcore remove all --yes でスキーマをリセットしてから agentcore deploy で空のスタックをデプロイします。

段階的な検証フロー

新しいテンプレートでは、エージェントの動作確認を3段階に分けています。

Step 1: エージェントプロジェクトを作成する

リポジトリルートで AgentCore CLI を使ってエージェントプロジェクトを生成します。

# AgentCore CLI インストール（未インストールの場合）
npm install -g @aws/agentcore

# リポジトリルートで実行
agentcore create

対話 UI で以下を選択します。

項目	選択
Project name	`agents`
Add agent	Yes
Agent name	任意（例: `my_agent`）
Type	Create new agent
Language	Python
Build	Container
Protocol	AG-UI
Framework	Strands Agents SDK
Model	Amazon Bedrock
Memory	None
Advanced	スキップ（JWT 認証は不要 — SigV4 を使用）

agentcore create は既存ディレクトリ名と衝突すると拒否します。テンプレートに agents/ を含めていないのはこのためです。

生成されるディレクトリ構成は以下の通りです。

agents/
├── agentcore/       # AgentCore CLI 設定（agentcore.json, CDK等）
└── app/             # エージェントコード
    └── <name>/      # create 時に指定した名前
        ├── main.py
        └── pyproject.toml

Step 2: エージェントをローカルで試す

生成されたエージェントの動作を確認します。agentcore dev はローカルで AgentCore Runtime をシミュレートし、ホットリロードと Agent Inspector も提供してくれます。

cd agents
agentcore dev

別ターミナルで AG-UI 形式のリクエストを送信し、正しいイベントが返ってくるか確認します。

curl -N -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "test-1",
    "runId": "run-1",
    "messages": [{"id": "m1", "role": "user", "content": "1+2は？"}],
    "tools": [], "context": [], "state": {}, "forwardedProps": {}
  }'

RUN_STARTED, TEXT_MESSAGE_CONTENT, RUN_FINISHED のイベントがストリームで返れば、CopilotKit と接続する準備が整っています。

Step 3: Webアプリと結合（要デプロイ）

ローカルでの結合テストはできません（SigV4 署名に Amplify Hosting のコンピューティングロールが必要）。接続には以下の手順が必要です。

Amplify Hosting にリポジトリ接続 → Web アプリ + Cognito をデプロイ
cd agents && agentcore deploy で AgentCore Runtime にデプロイ
コンピューティングロールに bedrock-agentcore:InvokeAgentRuntime 権限を追加
Amplify コンソールで NEXT_PUBLIC_AGENTCORE_RUNTIME_ARN を環境変数に設定
再デプロイで環境変数を反映

sandbox の Cognito と Amplify Hosting の Cognito は別物です。エージェント結合テストはデプロイ後の環境で行ってください。

テンプレートの全体像

アーキテクチャ概要

レイヤー	技術
フロントエンド	Next.js + TypeScript
バックエンド	AWS Amplify Gen 2
エージェント UI（任意）	CopilotKit（`@copilotkit/react-core/v2`）+ AG-UI プロトコル
エージェント（任意）	Python 3.12〜3.13 / Strands Agents SDK + ag-ui-strands
エージェント実行基盤（任意）	Amazon Bedrock AgentCore Runtime
エージェント管理（任意）	AgentCore CLI（`@aws/agentcore`）
ホスティング	Amplify Hosting
IDE 支援	Kiro + Agent Toolkit for AWS

ディレクトリ構成

kiro-amplify-template-v2/
├── src/                        # フロントエンド（Next.js App Router）
│   ├── app/                    # ページ・レイアウト
│   │   └── api/copilotkit/     # CopilotKit Runtime API Route（SigV4 → AgentCore プロキシ）
│   ├── components/             # UIコンポーネント（agent/ 含む）
│   ├── hooks/                  # カスタムReact hooks
│   ├── lib/                    # ロジック・ユーティリティ（agent/ 含む）
│   └── types/                  # 型定義
├── amplify/                    # Amplify Gen 2 バックエンド定義
│   ├── auth/                   # 認証設定
│   └── data/                   # データモデル定義
├── docs/                       # 詳細ドキュメント
├── .kiro/                      # Kiro設定
│   ├── steering/               # Steeringファイル（10）
│   ├── skills/                 # Skills（4）
│   └── settings/               # MCP設定
├── .github/                    # CI/CD・PRテンプレート
├── AGENTS.md                   # エージェント向けガイドライン
└── package.json

agents/ ディレクトリはテンプレートに含まれていません。エージェント機能を使う場合は agentcore create で生成します（後述）。agentcore create は既存ディレクトリ名と衝突すると拒否するため、あえてテンプレートには含めない構成にしています。

Kiro設定（Steering / Skills）

Steeringファイルは前回と同じ10ファイル構成（常時有効6 + 条件付き4）ですが、エージェント関連の刷新に伴い5ファイルを書き換えています。

変更があったSteeringファイル

ファイル	主な変更内容
`tech.md`	CopilotKit・AG-UI・SigV4接続構成図を追加。Python 3.12〜3.13 を明記
`strands-agent.md`	全面書き換え。`create_strands_app()` / AG-UI / IAM認証 / 削除手順
`amplify-frontend.md`	SSE直接通信 → CopilotKit + API Route + SigV4 構成に変更
`structure.md`	`src/app/api/copilotkit/`、`src/lib/agent/` 等を構成に追加
`testing.md`	ローカルテスト手段を `uvicorn` / `agentcore dev` / curl に更新

変更なしのSteeringファイル

amplify-backend.md、github-actions.md、product.md、repo-workflow.md、security.md — これら5ファイルは前回から変更なし。

変更のポイント

特に大きいのは tech.md と strands-agent.md の2つです。

tech.md には、CopilotKit + AgentCore の接続構成図をそのまま記載しています。

ブラウザ (@copilotkit/react-core/v2 + CopilotChat)
  → /api/copilotkit (Next.js API Route, Amplify Hosting SSR Lambda)
    → CopilotRuntime + ExperimentalEmptyAdapter
      → HttpAgent (fetch: sigv4Fetch)
        → AgentCore Runtime (IAM 認証, AG-UI プロトコル)

これをSteeringに含めておくことで、Kiroが接続構成を理解した上でコードを書いてくれます。ハマりポイントで紹介した ExperimentalEmptyAdapter 必須や /v2 import も明記してあるので、Kiroが同じミスを踏むことを防げます。

strands-agent.md は、前回では BedrockAgentCoreApp + @app.entrypoint 前提でしたが、今回は create_strands_app() + AG-UI + IAM 認証に全面変更。「JWT は CopilotKit 経由では動作しない」という知見も直接書いてあります。

Skills（変更なし）

Skills は同じ4つを維持。

Skill	用途
amplify-feature	Amplifyベースの機能実装
pr-deploy-readiness	PRサマリー・デプロイ準備確認
strands-agent-implementation	エージェント開発手順
mcp-tool-onboarding	MCPツールの導入評価

使い方（クイックスタート）

基本的な流れは前回と同じです。READMEの手順に従えばサンプルプログラムを起動できます。

GitHubテンプレートからリポジトリ作成 → Use this template
ローカルにクローン → Kiroで開く
Webアプリ起動 → npm ci → npx ampx sandbox + npm run dev
npx ampx sandbox

npm run dev

http://localhost:3000/ でCognitoログイン画面が開きます。

http://localhost:3000/sample でサンプルページが開きます。（AIエージェントは動いてないのでチャットは無効化されてます）
AIエージェント起動 → 段階的に確認（Step 1 → 2 → 3）
Step 1: agentcore create

Step 2: agentcore dev
Docker を動かしておく必要があります。

Step 3: docs/deployment.md に従いAmplifyを立ち上げ

Web画面でもエージェントチャットが動きました！

お片付け（リソース削除）

エージェント機能を試した後、不要になったリソースは以下の手順で削除できます。

# 1. AgentCore Runtime の削除
cd agents
agentcore remove all --yes
agentcore deploy

# 2. Amplify Hosting の削除（コンソールから）
# AWS コンソール → Amplify → アプリの設定 → アプリを削除

# 3. sandbox の停止（残っている場合）
npx ampx sandbox delete

agentcore destroy というコマンドは存在しません。agentcore remove all でスキーマをリセットしてから agentcore deploy で空のスタックをデプロイする、という流れです。

構築時のハマりポイント

テンプレートを作るのにも Kiro を最大限活用しています。
今回の変更でもすんなりいかずかなり苦戦しながら最終形にたどり着いたので、特に手こずったポイントをまとめておきます。

認証方式: JWT → IAM（SigV4）への移行

当初は AgentCore の Custom JWT authorizer で Cognito トークンを検証する構成を試しました。

試行	結果
Access token を Python スクリプトで直接送信	✅ 成功
同じ Access token を CopilotKit HttpAgent 経由で送信	❌ "Failed to parse token"
`agentcore invoke` で Bearer トークン指定	❌ "Bearer token auth is not yet supported for AGUI"

Python で直接呼ぶと動くのに CopilotKit 経由だと動かない。調査した結果、CopilotKit Runtime の HttpAgent が Authorization ヘッダーを AgentCore に正しく転送していないことが原因でした。

これは CopilotKit 側の実装制限なので、JWT を諦めて IAM（SigV4）認証 に切り替えました。SigV4 であればサーバーサイド（API Route）で署名するため、HttpAgent のヘッダー転送問題を回避できます。

AgentCore Runtime 自体は JWT（Bearer）をサポートしています。今後 CopilotKit 側の対応が進めば JWT に戻すことも可能です。

CopilotKit の設定で必須だったもの 2 つ

最も時間を使ったのがここです。公式ドキュメントの例を「省略可能だろう」と（Kiroが勝手に）判断してスキップした結果、数日ハマりました。

1. `ExperimentalEmptyAdapter` の指定

import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";

const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
  runtime,
  serviceAdapter: new ExperimentalEmptyAdapter(), // ← これが必須
  endpoint: "/api/copilotkit",
});

serviceAdapter は TypeScript 上は必須引数ではないため、省略してもエラーになりません。しかし省略すると AG-UI エージェントのレスポンスをクライアントに正しく変換できません。

2. フロントエンドの `/v2` import

// ❌ これだと動かない
import { CopilotKit } from "@copilotkit/react-core";

// ✅ こっちが正しい
import { CopilotKit } from "@copilotkit/react-core/v2";

@copilotkit/react-core と @copilotkit/react-core/v2 は異なるプロトコルで CopilotKit Runtime と通信します。v2 を使わないと AG-UI エージェントの応答が描画されません。npm install しただけだと v1 の API を使ってしまうので注意が必要です。

Amplify Hosting のコンピューティングロール

API Route から AgentCore Runtime を SigV4 で呼ぶには、Amplify Hosting の SSR Lambda に AWS サービスへのアクセス権限が必要です。Amplify コンソールでコンピューティングロールを設定し、以下のポリシーをアタッチします。

{
  "Effect": "Allow",
  "Action": "bedrock-agentcore:InvokeAgentRuntime",
  "Resource": "arn:aws:bedrock-agentcore:*:*:runtime/*"
}

まとめ

前回からの主要な変更をまとめると、以下の3点に集約されます。

AG-UI + CopilotKit でエージェントUIを標準化し、実装コストを削減
Agent Toolkit for AWS（GA） でAWS連携が安定・高機能に
AgentCore CLI でエージェントのライフサイクル管理が一本化

構築過程では認証方式やCopilotKitの設定周りでかなり苦戦しましたが、最終的にスッキリとした構成に落ち着いたと思います。
引き続きこのテンプレートをベースに色々なアプリケーションを作っていきたいと思います。

前回のテンプレート紹介記事

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up