CopilotKitとMastraのクイックスタートを試してみた

CopilotKitとMastraのクイックスタートを試してみました。AG-UIの今後が楽しみです。
2025.09.18
CopilotKitとMastraを利用したクイックスタートを試してみます。LLM ProviderとしてAmazon Bedrockを用います。
Quickstart
CopilotKit/with-mastra: Starter for building with CopilotKit and Mastra via AG-UI
 データの流れ今回用いるCopilotKit <> Mastra Starterにおけるデータの流れと各コンポーネントを見てみます。
 フロントエンド（ブラウザ）CopilotSidebar
チャットインターフェイスとしてCopilotSidebarを使用
ユーザーとの対話を提供
サイドバーでなく、シンプルなチャットインターフェイスはCopilotChatもあります
CopilotKit Provider
アプリケーションの状態を読み取り、理解し、コンテキスト認識アクションを実行
フロントエンドツール（useCopilotAction）とエージェントとの状態共有（useCoAgent）を管理
CopilotKit Hooks
useCopilotAction: フロントエンド側で実行可能なツールを定義
定義したツールはチャット時にエージェントに渡されます。エージェントがツール呼び出しを行った際にはフロントエンドで指定のツールが実行されます。

useCoAgent: エージェントと共有する状態を管理
useStateのようなインターフェスで、フロントエンド、エージェントともに状態を参照・編集が可能

今回使うもの以外にも色々なUIコンポーネントやフックなどがあります。詳細はドキュメントを参照ください。
API Reference
 API層Next.js API Route（/api/copilotkit）
CopilotKitからのリクエストを受け付けるエンドポイント
GraphQL Yoga Server
CopilotRuntimeNextJSAppRouterEndpointとして動作
GraphQLクエリの処理とルーティングを担当
MastraAgent（AG-UIとMastraの相互変換用ラッパー）
AG-UIとMastraの間のデータ変換を担当
異なるフレームワーク間の互換性を提供
 Mastra層Mastraインスタンス
エージェント、ツール、メモリなどが登録されたMastraインスタンス
インスタンスを介してエージェントを呼び出し
Mastra Tools（weatherTool）
Open-Meteo API（Geocoding + Forecast）を呼び出し、天気情報を取得するツール
Mastraにおけるツールは、MCPをツールとして登録したり、ツール内にRuntimeContextを注入したりも可能です。
参考: Using Tools with Agents
Mastra Memory（LibSQL Store）
エージェントの会話履歴や状態を保存
libSQLベースの永続化ストレージ
PostgreSQLなど他のストレージも利用可能
 試してみる セットアップCopilotKit <> Mastra Starterをクローンします。

					
			gh repo clone CopilotKit/with-mastra

		
		
pnpmでパッケージをインストールします。

					
			pnpm install

		
		
LLMプロバイダはBedrockを用いるため、OpenAI用AI SDKを削除し、Bedrock用をインストールします。執筆時点において、AG-UIのMastra用アダプタがMastraのstreamVNextに対応していないため、@ai-sdk/amazon-bedrockは2系を利用します。

※ 9/23にstreamVNextがstreamに置き換わるようです。 参考: mastra/coreのCHANGELOGで置き換えを9/23に延期するという記載

					
			pnpm rm @ai-sdk/openai && pnpm add @ai-sdk/amazon-bedrock@2

		
		
.envファイルを作成し、BedrockへのアクセスのためにAWSの認証情報を環境変数に設定します。今回はアクセスキーIDとシークレットアクセスキーを利用します。@ai-sdk/amazon-bedrockのバージョンが3以降であれば、APIキーでの利用も可能です。

					
			AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=your-region

		
		
 LLMプロバイダとしてBedrockを使うように変更AI SDKのBedrockプロバイダを利用するように変更します。
src/mastra/agents/weather-agent.ts

					
			@@ -1 +1 @@
-import { openai } from "@ai-sdk/openai";
+import { bedrock } from "@ai-sdk/amazon-bedrock";
@@ -15 +15 @@
-  model: openai("gpt-4o"),
+  model: bedrock("apac.anthropic.claude-sonnet-4-20250514-v1:0"),

		
		
 エージェント(mastra)の動作確認MastraのLocal Dev Playgroundを利用して、Bedrockへのリクエストが可能かなどエージェントの動作を確認してみます。
以下のコマンドでmastraサーバーを起動します。

					
			pnpm dev:agent

		
		
http://localhost:4111/ にアクセスすることで、Local Dev Playgroundを表示できます。
エージェントを選択すると、該当エージェントとやり取りができる画面が開きます。画面下部のメッセージを入力して、Bedrockへリクエストができることを確認してみます。
動作してそうです。
天気を聞いてみて、ツールが動作してることも確認してみます。
動作してそうです。
ツールの呼び出し状況も確認できます。2回同じツールを呼び出してるのは一度目で東京でだめだったので、次はTokyoで試したようです。このように実際のLLMにつなぎこんでツールが意図した通りに動いてることが確認できるのは便利ですね。
その他にもLocal Dev Playgroundでは、Toolsやエージェントの評価、ワークフローの可視化なども可能なようです。フロントエンドとは別でエージェント単体で動作確認できるため、開発時には便利そうです。
Inspecting agents and workflows with mastra dev | Mastra Local Dev Docs
 フロントエンドを含めた動作確認次はNext.jsを動かし、フロントエンドを含めて動作確認してみます。

					
			pnpm dev

		
		
http://localhost:3000/ にアクセスすると、画面が表示されます。
画面左下のボタンを押すと、CopilotKitのInspector画面が表示されます。layout.tsxのCopilotKitにライセンスキーを設定してる場合は、Inspector画面を使えるようになります。
Inspector
このようにaction(tool)の一覧やメッセージなどを確認できます。
チャットを入力してみます。入力したメッセージは表示されますが、AIの回答は表示されません。
調べてみると、エラーログもでていなさそうですが、トレースを有効にしてみたところ、Bedrockへのリクエスト時にエラーになっていることがわかりました。
トレーシング | Mastra 可観測性ドキュメント
エラー内容は次のとおりです。

					
			undefined: 1 validation error detected: Value '' at 'toolConfig.tools.3.member.toolSpec.description' failed to satisfy constraint: Member must have length greater than or equal to 1

		
		
以下のように、フロントエンドツールのdescriptionを記載します。
src/app/page.tsx

					
			@@ -15,25 +15,33 @@
export default function CopilotKitPage() {
   // 🪁 Frontend Actions: https://docs.copilotkit.ai/guides/frontend-actions
   useCopilotAction({
     name: "setThemeColor",
-    parameters: [{
-      name: "themeColor",
-      description: "The theme color to set. Make sure to pick nice colors.",
-      required: true,
-    }],
+    description: "Set the theme color of the application",
+    parameters: [
+      {

		
		
改めて、動作を確認してみます。

テーマの色変更を試してみます。
動いてます! useCopilotActionを用いて、フロントエンド側のテーマの色変更が実行されています。Mastraにおいてワーキングメモリの更新のためにupdateWorkingMemoryツールが使われるようです。フロントエンド側でuseCopilotActionで同名のツールが定義されています。エージェント側のログを見たところ、LLMに渡されているツールは['weatherTool', 'updateWorkingMemory', 'setThemeColor' ]でした。該当ツールが呼び出された場合にフロントエンド側で同じツールが実行されているようです。
続いて、Proverbsの更新を試してみます。
useCoAgentによってエージェント側のstateでproverbsが追加され、フロントエンド側でも表示されています。
天気の取得も試してみます。
動いていそうです。weatherToolもupdateWorkingMemory同様にuseCopilotActionで定義されているため、呼び出されると、カードが表示されるようになっています。
 補足: ハイドレーションエラーCopilotSidebarでハイドレーションエラーが発生することがあります。コンポーネントが大きいことで起きており、dynamic importを利用することで解消できるようです。
※ 試した際、最初はエラーがでていたんですが、ライセンスキーを設定後はエラーがでなくなりました。
Hydration failed because the server rendered HTML didn't match the client. As a result this tree wil - CopilotKit • Threads
 さいごにCopilotKitとMastraを利用したクイックスタートを試してみました。CopilotKitによって、エージェントとフロントエンド双方のデータやり取りや処理などが楽に行えるため、エージェントアプリの開発を楽にできそうです。UIコンポーネントを使わず、フックだけを利用することで、エージェントとのやり取りを楽にするというメリットを得つつ、プロダクトに合わせた柔軟なUIを作成することも可能そうです。
CopilotKitが主導している、エージェントとフロントエンド間のやりとりをプロトコルとして定めたAG-UIにより、エージェントフレームワーク間の相互運用性を高めることにつながります。エージェントごとにフレームワークが異なる場合や利用するフレームワークを変更する場合などに活きてきそうです。フロントエンド側のフレームワークとしても、エージェントフレームワークごとの対応コストが減るため、フロントエンドコミュニティの活性化にも繋がりそうです。AG-UIは仕様改善だけでなく、新たなエージェントフレームワークへの対応も随時行われています。ロードマップで状況を確認できるため、今後の動向にも注目していきたいと思います。
 関連Introduction to CopilotKit
Introduction | Mastra Docs
Introduction - Agent User Interaction Protocol