Microsoft Agent Framework用のフロントエンドをAG-UIとCopilotKitを使って動かしてみた

2025-12-09

はじめに

AutoGenからMicrosoft Agent Framework(MAF)に移行することを考えたときに、 AutoGen Studio(フロントエンド)の部分はどうするのが良いのだろうと思っていたら、公式ドキュメントにAG-UI Agent Framework との統合というページがあるのを見つけました。

これを実際にローカル環境で触ってみたかったので、環境構築の手順を備忘録として残します。

(なお、MAFやAG-UI、CopilotKitの概要については説明しません)

事前準備

以下のものをインストールしておきます。

Node.jsのバージョン20以上
uv (Python用パッケージマネージャ)

※Pythonでなく.NETを選択することも可能です。

セットアップ

以下のページに従ってセットアップを行います。

1. プロジェクトの作成

まず、ターミナル上で新規プロジェクト作成のコマンドを実行します。

npx copilotkit@latest create -f microsoft-agent-framework-py

ぼくはpnpmを使いたいのでnpxをpnpm dlxに置き換えて実行します。

途中でWhat is your project named?と聞かれるので、お好みのプロジェクト名を入力してください。

すると以下のような出力が得られます。

> pnpm dlx copilotkit@latest create -f microsoft-agent-framework-py
Packages: +267
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 267, reused 104, downloaded 163, added 267, done

⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠙⣿⡛⠻⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠋⠀⠀⠈⢿⡄⠀⠀⠀⠈⠉⠙⣻⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀⠈⢿⡄⠀⢀⣠⣴⠾⠋⢸⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡟⠁⢀⣀⣀⣀⣀⣤⣤⡾⢿⡟⠛⠉⠀⠀⠀⠀⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡛⠛⠛⠛⠉⠉⠉⠁⠀⢠⡿⣿⡀⠀⠀⠀⠀⠀⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⣰⡟⠀⠸⣧⠀⠀⠀⠀⢠⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⠀⠀⢀⣼⠏⠀⠀⠀⣿⡀⠀⠀⠀⢸⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠂⣠⡿⠁⠀⠀⠀⠀⢸⡇⠀⠀⠀⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⣡⣾⣿⣄⠀⠀⠀⠀⠀⢸⡇⠀⠀⢰⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⡟⠛⡿⠋⣡⣾⣿⣿⣿⣿⣦⡀⠀⠀⠀⢸⡇⠀⠀⣿⣿⣿⣿
⣿⣿⣿⣿⡿⠿⣿⠷⠂⡀⠘⣿⣿⣿⣿⣿⣿⣿⣷⡀⠀⠀⢸⡇⠀⣼⣿⣿⣿⣿
⣿⣿⠻⢿⡷⠀⠁⠴⣿⣷⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⡄⠀⣾⠇⣴⣿⣿⣿⣿⣿
⡿⠛⠀⠀⢴⣾⣷⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣤⣿⣾⣿⣿⣿⣿⣿⣿
⣷⣾⣿⣤⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿

~ Welcome to CopilotKit! ~

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✔ What is your project named? maf-agui-copilotkit-sample
✔ Project "maf-agui-copilotkit-sample" created successfully!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🪁🤝🟦 All set!

Your project is ready to explore CopilotKit locally.

Next steps:
  • cd maf-agui-copilotkit-sample
  • Follow the setup instructions in the README.md

Documentation:
  • https://docs.copilotkit.ai
  • https://learn.microsoft.com/en-us/agent-framework/

これでプロジェクトのテンプレートが導入できました。

2. 依存関係のインストール

次に、先ほどのコマンド出力のNext stepsに従ってプロジェクトのディレクトリ下に移動し、以下のコマンドを実行します。 (※npmやyarn、bunを使う場合は適宜読み替えてください)

pnpm install

すると以下のような出力が得られます。

> pnpm i

 WARN  deprecated [email protected]: This version has a security vulnerability. Please upgrade to a patched version. See https://nextjs.org/blog/CVE-2025-66478 for more details.
Downloading [email protected]: 27.78 MB/27.78 MB, done
 WARN  Request took 19060ms: https://registry.npmjs.org/@typescript-eslint%2Fparser
 WARN  Request took 23174ms: https://registry.npmjs.org/@typescript-eslint%2Feslint-plugin
 WARN  Request took 19641ms: https://registry.npmjs.org/graphql-yoga
 WARN  Request took 10138ms: https://registry.npmjs.org/@next%2Fswc-linux-x64-musl
 WARN  Request took 11975ms: https://registry.npmjs.org/@next%2Fswc-win32-x64-msvc
 WARN  6 other warnings
Downloading @next/[email protected]: 47.33 MB/47.33 MB, done
Downloading [email protected]: 10.24 MB/10.24 MB, done
 WARN  3 deprecated subdependencies found: [email protected], [email protected], [email protected]
Packages: +924
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 999, reused 353, downloaded 576, added 924, done

> [email protected] postinstall C:\Users\loliver\Projects\tmp\maf-agui-copilotkit-sample
> npm run install:agent


> [email protected] install:agent
> ./scripts/setup-agent.sh || scripts\setup-agent.bat

'.' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。
Using CPython 3.12.12
Creating virtual environment at: .venv
Resolved 63 packages in 14ms
Prepared 62 packages in 16.10s
Installed 62 packages in 2.33s
 + ag-ui-protocol==0.1.9
 + agent-framework-ag-ui==1.0.0b251117
 + agent-framework-core==1.0.0b251114
 + annotated-doc==0.0.4
 + annotated-types==0.7.0
 + anyio==4.11.0
 + attrs==25.4.0
 + azure-core==1.36.0
 + azure-identity==1.25.1
 + certifi==2025.8.3
 + cffi==2.0.0
 + charset-normalizer==3.4.3
 + click==8.3.0
 + colorama==0.4.6
 + cryptography==46.0.3
 + distro==1.9.0
 + fastapi==0.121.2
 + googleapis-common-protos==1.70.0
 + grpcio==1.76.0
 + h11==0.16.0
 + httpcore==1.0.9
 + httpx==0.28.1
 + httpx-sse==0.4.3
 + idna==3.10
 + importlib-metadata==8.7.0
 + jiter==0.11.0
 + jsonschema==4.25.1
 + jsonschema-specifications==2025.9.1
 + mcp==1.21.1
 + msal==1.34.0
 + msal-extensions==1.3.1
 + openai==1.109.1
 + opentelemetry-api==1.37.0
 + opentelemetry-exporter-otlp-proto-common==1.37.0
 + opentelemetry-exporter-otlp-proto-grpc==1.37.0
 + opentelemetry-proto==1.37.0
 + opentelemetry-sdk==1.37.0
 + opentelemetry-semantic-conventions==0.58b0
 + opentelemetry-semantic-conventions-ai==0.4.13
 + packaging==25.0
 + protobuf==6.32.1
 + pycparser==2.23
 + pydantic==2.11.9
 + pydantic-core==2.33.2
 + pydantic-settings==2.12.0
 + pyjwt==2.10.1
 + python-dotenv==1.1.1
 + python-multipart==0.0.20
 + pywin32==311
 + referencing==0.37.0
 + requests==2.32.5
 + rpds-py==0.28.0
 + sniffio==1.3.1
 + sse-starlette==3.0.3
 + starlette==0.48.0
 + tqdm==4.67.1
 + typing-extensions==4.15.0
 + typing-inspection==0.4.1
 + urllib3==2.5.0
 + uvicorn==0.37.0
 + websockets==15.0.1
 + zipp==3.23.0
 WARN  Issues with peer dependencies found
.
└─┬ @ag-ui/langgraph 0.0.20
  ├── ✕ unmet peer @ag-ui/core@>=0.0.42: found 0.0.39
  └── ✕ unmet peer @ag-ui/client@>=0.0.42: found 0.0.40

dependencies:
+ @ag-ui/client 0.0.40 (0.0.42 is available)
+ @copilotkit/react-core 1.10.6
+ @copilotkit/react-ui 1.10.6
+ @copilotkit/runtime 1.10.6
+ next 15.3.2 (16.0.8 is available) deprecated
+ react 19.2.1
+ react-dom 19.2.1
+ zod 3.25.76 (4.1.13 is available)

devDependencies:
+ @eslint/eslintrc 3.3.3
+ @tailwindcss/postcss 4.1.17
+ @types/node 20.19.26 (24.10.2 is available)
+ @types/react 19.2.7
+ @types/react-dom 19.2.3
+ concurrently 9.2.1
+ eslint 9.39.1
+ eslint-config-next 15.3.2 (16.0.8 is available)
+ tailwindcss 4.1.17
+ typescript 5.9.3

╭ Warning ───────────────────────────────────────────────────────────────────────────────────╮
│                                                                                            │
│   Ignored build scripts: @scarf/scarf, protobufjs, sharp, unrs-resolver.                   │
│   Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.   │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

Done in 3m 12s using pnpm v10.24.0

どうも依存しているNext.jsのバージョンが最近確認された激ヤバ脆弱性を含むバージョンのようで、WARNINGが出ています。

同じWARNINGが確認できた場合は、ここで作成したアプリをそのまま公開するのは絶対にやめておきましょう。

また、以下の部分でエラーが出ていますが、これは気にする必要なさそうです。

> ./scripts/setup-agent.sh || scripts\setup-agent.bat

'.' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

私は今回コマンドプロンプトで実行したのですが、環境に応じてsetup-agent.shかsetup-agent.batのいずれか適切な方が実行されるようになっているだけのようです。

更に、このプロジェクトには/agent配下に.python-versionファイルやpyproject.tomlファイルが用意されているため、実行環境にuvさえ導入されていれば、自動でPythonの仮想環境(venv)を作成し、適切なバージョンのPythonごと導入してくれています。嬉しいね

3. 環境変数の設定

次に、/agent配下に.envファイルを作成し、OpenAIのAPIキーと使用モデルIDを入力します。

OPENAI_API_KEY=sk-...your-openai-key-here...
OPENAI_CHAT_MODEL_ID=gpt-5-nano

もしAPIキーを発行していない場合は、このタイミングで発行しましょう。

https://platform.openai.com/settings

※.envファイルの作成は、VS Code上などで実施することをおすすめします。

4. ローカル開発サーバーの起動

これで環境構築は完了したので、最後に実際にアプリを起動してみます。

> pnpm dev  

> [email protected] dev C:\Users\loliver\Projects\tmp\maf-agui-copilotkit-sample
> concurrently "npm run dev:ui" "npm run dev:agent" --names ui,agent --prefix-colors blue,green --kill-others

[agent] 
[agent] > [email protected] dev:agent
[agent] > ./scripts/run-agent.sh || scripts/run-agent.bat
[agent]
[ui]
[ui] > [email protected] dev:ui
[ui] > next dev --turbopack
[ui]
[agent] '.' is not recognized as an internal or external command,
[agent] operable program or batch file.
[agent] 'scripts' is not recognized as an internal or external command,
[agent] operable program or batch file.
[agent] npm run dev:agent exited with code 1
--> Sending SIGTERM to other processes..
[ui] npm run dev:ui exited with code 1
 ELIFECYCLE  Command failed with exit code 1.

なんか失敗しとりますね……

> ./scripts/run-agent.sh || scripts/run-agent.batってコマンドの前半が失敗しているのが無視されずに処理が終了させられていそうです。

package.jsonにこのコマンドの定義があったので修正します。

{
  ...
  "scripts": {
    ...
    // "dev:agent": "./scripts/run-agent.sh || scripts/run-agent.bat",  // ここを以下のように修正
    "dev:agent": "scripts/run-agent.bat",
    ...
  },
  ...
}

再度起動してみます。

> pnpm dev

> [email protected] dev C:\Users\loliver\Projects\tmp\maf-agui-copilotkit-sample
> concurrently "npm run dev:ui" "npm run dev:agent" --names ui,agent --prefix-colors blue,green --kill-others

[ui] 
[ui] > [email protected] dev:ui
[ui] > next dev --turbopack
[ui] 
[agent] 
[agent] > [email protected] dev:agent
[agent] > scripts/run-agent.bat
[agent] 
[ui]    ▲ Next.js 15.3.2 (Turbopack)
[ui]    - Local:        http://localhost:3000
[ui]    - Network:      http://192.168.50.240:3000
[ui] 
[ui]  ✓ Starting...
[agent] INFO:     Will watch for changes in these directories: ['C:\\Users\\loliver\\Projects\\tmp\\maf-agui-copilotkit-sample\\agent']
[agent] INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
[agent] INFO:     Started reloader process [2940] using StatReload
[ui]  ✓ Ready in 1509ms
[agent] INFO:     Started server process [10788]
[agent] INFO:     Waiting for application startup.
[agent] INFO:     Application startup complete.

起動できた！

早速ブラウザでlocalhost:3000にアクセスしてみます

No agent found with graph ID ${this.graphId} found..

The export randomUUID was not found in module [project]/node_modules/.pnpm/@[email protected]/node_modules/@ag-ui/client/dist/index.mjs [app-route] (ecmascript) <exports>.
[ui] Did you mean to import transformChunks?
[ui] All exports of the module are statically known (It doesn't have dynamic exports). So it's known statically that the requested export doesn't exist.

なんかエラー出ましたね

@ag-ui/clientライブラリ内でインポートエラーが出てるっぽいので、@ag-ui/clientを最新バージョンに更新してみます。

pnpm add @ag-ui/client@latest

以下の出力の通り、パッチバージョンが更新されました。

dependencies:
- @ag-ui/client 0.0.40
+ @ag-ui/client 0.0.42

再度開発サーバーを起動してブラウザでアクセスしてみると、今度はきちんと画面が表示され、チャットも動くことが確認できました。やったね

CopilotKitのライセンスの話

CopilotKitには有料プランがあり、商用利用にはライセンス料がかかるかも…と思ったのですが、 GitHubリポジトリにはMITライセンスが付与されているため、ここに含まれているコア機能に関してはフリーライセンスで商用利用可能そうです。

ただし、Fully Headless UI、Observability Hooks、CopilotKit Inspectorという3つの機能はCopilotKit Premiumという区分になっており、商用利用は有料となるようです。

独自のUIを作る場合にFully Headless UIは便利なものになるとは思いますが、ぶっちゃけなくてもNext.jsやFastAPIが触れるのであれば自由に作ることは可能そうです。 (気が向いたらAutoGen Studio風のUI再現してみたいな)

おわりに

最近、AIエージェント用のフロントエンドフレームワーク等がいろいろ出てきてなかなか追いきれない……俺は何も分からない……