Skip to content

Fujiwo/Shos.AIAgentSample

BranchesTags

Repository files navigation

Shos.AIAgentSample

License: MIT .NET C#

AIエージェント開発ハンズオンセミナー (開発者向け) のサンプルコードとチュートリアル

リポジトリ: https://github.com/Fujiwo/Shos.AIAgentSample

目次

概要

このリポジトリは、Microsoft Agent Framework と Model Context Protocol (MCP) を使用した AI エージェント開発の実践的なチュートリアルを提供します。ローカル LLM (Ollama) や Azure OpenAI を利用した AI エージェントの作成から、MCP サーバーの実装、そしてエージェントと MCP サーバーの統合まで、段階的に学習できます。

🎯 このリポジトリで学べること

学習内容 説明
✅ AI エージェントの基礎 AI エージェントの基本概念から実装まで体系的に学習
✅ 複数の LLM 利用 ローカル LLM (Ollama) と Azure OpenAI の両方の利用方法
✅ MCP サーバー開発 Model Context Protocol サーバーの作成と統合
✅ 多様なアプリケーション コンソールアプリ、Web アプリ、CAD アプリの実装
✅ 実践的な統合 複数の外部ツールを活用した実践的なエージェント開発

⚠️ 重要な注意事項

このサンプルコードとチュートリアルは、執筆時点のプレビュー版の Microsoft Agent Framework が基になっています。 Microsoft Agent Framework は、今後のバージョンアップで内容が変わる可能性があります。

特徴

  • 🔧 .NET ベースの実装 - C# と .NET を使用した実装例
  • 🤖 複数の LLM 対応 - ローカル LLM (Ollama) と Azure OpenAI の両方に対応
  • 🔌 MCP サーバーの実装 - STDIO と SSE の両方のトランスポート方式をサポート
  • 📖 段階的な学習 - 基礎から応用まで、ステップバイステップで学習
  • 💡 実践的なサンプル - コンソールアプリ、Web アプリ、CAD アプリを提供
  • 🇯🇵 日本語ドキュメント - すべてのチュートリアルを日本語で提供

クイックスタート

最も簡単に AI エージェントを試すには、以下の手順に従ってください：

手順

  1. リポジトリをクローン

    git clone https://github.com/Fujiwo/Shos.AIAgentSample.git
cd Shos.AIAgentSample

  2. Ollama をインストール（ローカル LLM を使用）

  3. LLM モデルをダウンロード

    ollama pull llama3.2

  4. Visual Studio でソリューションを開く

    • Shos.AIAgentSample.sln を Visual Studio で開く

  5. サンプルプロジェクトを実行

    • FCAIAgent1 プロジェクトを右クリックし、「スタートアップ プロジェクトに設定」を選択
    • F5 キーを押してデバッグ実行

詳細な手順とオプション設定は、チュートリアルの実施方法を参照してください。

内容一覧

0. 準備

1. AI エージェントの作成 (LLM 利用)

2. MCP サーバーの作成

3. AI エージェントでの MCP サーバーの利用

4. 後片付け

チュートリアルの実施方法

このチュートリアルは、AI エージェント開発の基礎から応用まで、段階的に学習できるように設計されています。

前提条件

必須要件

以下のツールがインストールされている必要があります:

ツール バージョン 説明
.NET SDK 8.0 以上（推奨: 9.0） C# アプリケーションの実行に必要
Visual Studio または VS Code VS 2022 (17.12+) または VS Code 開発環境（チュートリアルは Visual Studio を前提）
Node.js v24.0 以上推奨 MCP サーバーの動作確認ツールに必要

詳細なインストール手順は インストールガイド を参照してください。

LLM の選択（いずれかを選択）

使用する LLM に応じて、以下のいずれかを選択してください:

選択肢 メリット 必要なもの ガイド
Ollama ・無料
・インターネット接続不要
・プライバシー保護		 Ollama のインストール インストールガイド
Azure OpenAI ・高性能
・最新モデルが利用可能
・スケーラブル		 ・Azure アカウント
・Azure OpenAI リソース
・API キー		 設定ガイド

注意: Azure OpenAI を使用する場合、API の利用に応じて課金が発生します。

推奨される前提知識

  • プログラミング: C# の基礎、.NET アプリケーション開発経験
  • コマンドライン: 基本的なコマンド操作（cd, dotnet コマンドなど）
  • Git: リポジトリのクローンと基本操作

推奨される参考資料

事前学習として以下の資料が役立ちます：

学習の進め方

ステップ 1: 環境準備

  1. リポジトリのクローン

    git clone https://github.com/Fujiwo/Shos.AIAgentSample.git
cd Shos.AIAgentSample

  2. 必要なツールのインストール

    インストールガイドに従って、必要なツールをインストールしてください。

  3. ソリューションを開く

    Visual Studio で Shos.AIAgentSample.sln を開きます。

ステップ 2: チュートリアルの実施

推奨される学習順序：

  1. 準備編（所要時間：30分〜1時間）

  2. 基礎編（所要時間：1〜2時間）

  3. MCP サーバー編（所要時間：1〜2時間）

  4. 応用編（所要時間：1〜2時間）

  5. 後片付け

ステップ 3: サンプルプロジェクトの実行

各プロジェクトは独立して実行できます。チュートリアルに従って作成することもできますが、既存のサンプルプロジェクトを参照・実行することもできます。

⚠️ 注意: 既存のサンプルを実行する場合、API キーやエンドポイント、プロジェクトのパスなどを、環境に合わせてソースコード内に追記する必要があります。

コンソールアプリケーションの実行例
# 基本的な AI エージェント (FCAIAgent1〜5)
cd FCAIAgent1
dotnet run

# MCP サーバーの例
cd McpServer.Con
dotnet run
Web アプリケーションの実行例
# Web チャットアプリケーション (FCAIChat1〜5)
cd FCAIChat1
dotnet run

# ブラウザで以下にアクセス:
# - HTTPS: https://localhost:5001
# - HTTP: http://localhost:5000
Visual Studio での実行
  1. Visual Studio で Shos.AIAgentSample.sln を開く
  2. ソリューションエクスプローラーで実行したいプロジェクトを右クリック
  3. 「スタートアップ プロジェクトに設定」を選択
  4. F5 キーまたは「デバッグの開始」を押して実行

学習のヒント

効果的に学習を進めるためのポイント：

ヒント 説明
📚 順番に進める 各チュートリアルは前のステップの知識を前提としています。順番に進めることを強く推奨します
💭 コードを理解する 単にコピー＆ペーストするのではなく、各コードの意味を理解しながら進めてください
🔬 実験する サンプルコードを改変して、動作を確認することで理解が深まります
🐛 エラーに慣れる エラーメッセージを読み、問題を解決するプロセスも重要な学習です
📝 コメントを読む サンプルコードには詳細なコメントが付いています。よく読んで理解を深めてください

プロジェクト構成

このリポジトリには、段階的に学習できる複数のサンプルプロジェクトが含まれています。

AI エージェントプロジェクト

各プロジェクトは前のプロジェクトの機能を拡張していく形になっています：

🤖 コンソールアプリケーション (FCAIAgent シリーズ)

プロジェクト 学習ステップ 主な機能 チュートリアル
FCAIAgent1 ステップ 1 ・Ollama を使用したローカル LLM との通信
・シンプルな1回のプロンプトと応答		 1.1
FCAIAgent2 ステップ 2 ・Ollama と Azure OpenAI の両方に対応
・チャットクライアントの切り替え機能		 1.2
FCAIAgent3 ステップ 3 ・会話履歴を保持したチャット機能
・AgentThread を使用した対話セッション管理		 1.3
FCAIAgent4 ステップ 4 ・STDIO トランスポートを使用した MCP サーバー接続
・外部ツール（時刻取得など）の利用		 3.1
FCAIAgent5 ステップ 5 ・複数の MCP サーバー（時刻、天気、ファイルシステム）の同時利用
・より実践的なツール統合の例		 3.2
FCAIAgent 最終形態 FCAIAgent5 と同等の実装 -

🔧 MCP サーバープロジェクト

プロジェクト トランスポート 主な機能 チュートリアル
McpServer.Con STDIO ・標準入出力を通じた通信
・時刻取得ツールの実装例
・ローカルプロセス間通信向け		 2.1
McpServer.Sse HTTP/SSE ・Server-Sent Events によるリアルタイム通信
・天気予報ツールの実装例
・ネットワーク経由での利用が可能		 2.2

🌐 Web アプリケーション (FCAIChat シリーズ)

コンソールアプリケーションと並行して、同等の機能を Web インターフェースで提供するプロジェクト群です：

プロジェクト 学習ステップ 主な機能 対応チュートリアル
FCAIChat1 ステップ 1 ・ASP.NET Core MVC を使用した Web UI
・ローカル LLM (Ollama) との対話		 1.1
FCAIChat2 ステップ 2 ・Ollama と Azure OpenAI の切り替え機能
・Web ベースの UI で LLM を選択可能		 1.2
FCAIChat3 ステップ 3 ・セッション管理による会話履歴の保持
・連続的な対話のサポート		 1.3
FCAIChat4 ステップ 4 ・Web インターフェースから MCP ツールを利用
・ユーザーフレンドリーな対話型 AI 体験		 3.1
FCAIChat5 ステップ 5 ・複数のツールを統合した実践的な Web アプリケーション
・エンドユーザー向けの完全な AI エージェント体験		 3.2

🎨 CAD アプリケーション (FCAICad1)

Windows Forms を使用した、AI エージェントを統合した CAD (Computer-Aided Design) アプリケーションです。自然言語で図形描画を指示でき、AI エージェントがそれを解釈して実際に描画を実行します。

プロジェクト概要

プロジェクト プラットフォーム 主な機能
FCAICad1 Windows Forms ・自然言語による図形描画指示
・AI エージェントによる描画コマンド自動実行
・リアルタイム図形表示
・Windows Forms を使った GUI 実装

AI エージェントに提供されるツール

FCAICad1 では、以下のツール（関数）を AI エージェントに提供しています：

ツール 説明 パラメータ
GetPaperSize() 用紙サイズ（幅と高さ）を取得 なし（戻り値: width, height）
DrawLine() 直線を描画 startX, startY, endX, endY（始点と終点の座標）

実装のポイント

  • 自然言語インターフェース: ユーザーは「右上から左下に線を引いて」といった自然な指示を入力できます
  • AI による解釈: エージェントが指示を解釈し、適切なツールを呼び出します
  • 即座の可視化: 描画結果がリアルタイムに画面に表示されます

このプロジェクトは、AI エージェントをデスクトップアプリケーションに統合し、自然言語でアプリケーションを制御する実例を提供します。今後、より多くの描画ツール（円、矩形、テキストなど）を追加することで、より高度な CAD システムへと発展させることができます。

Note

FCAICad1 は Windows Forms を使用しているため、Windows でのみ動作します。

📚 ドキュメントとリソース

  • Documents/ - チュートリアルドキュメントと画像
    • 各ステップの詳細な説明
    • スクリーンショットによる視覚的なガイド
    • PDF およびスライド形式のセミナー資料

⚙️ 設定ファイル

  • .mcp.json - ルートディレクトリの MCP サーバー設定（サンプル）
  • .vscode/mcp.json - Visual Studio Code 用の MCP サーバー設定
  • Shos.AIAgentSample.sln - Visual Studio ソリューションファイル

技術スタックと実行環境

開発・実行環境

カテゴリ 内容
言語 C# 12.0
ランタイム .NET 8.0 以上（推奨: .NET 9.0）
IDE Visual Studio 2022（17.12 以降）、または Visual Studio Code
対応 OS Windows 11/10（全機能）、macOS、Linux（FCAICad1 を除く）

実行環境

オペレーティングシステム

OS サポート状況 備考
Windows 11/10 ✅ すべてのプロジェクト FCAICad1 を含むすべてのプロジェクトが動作
macOS ✅ 一部対応 FCAIAgent、FCAIChat、MCP サーバープロジェクトをサポート
Linux ✅ 一部対応 FCAIAgent、FCAIChat、MCP サーバープロジェクトをサポート

Note

FCAICad1 プロジェクトは Windows Forms を使用しているため、Windows でのみ動作します。macOS および Linux では実行できません。

言語とランタイム

  • 言語: C# 12.0
  • ランタイム: .NET 8.0 以上（推奨: .NET 9.0）
  • IDE: Visual Studio 2022（17.12 以降）、または Visual Studio Code

主要な依存パッケージ

AI エージェント関連

  • Microsoft.Agents.AI (プレリリース版)
  • Microsoft.Extensions.AI
  • ModelContextProtocol (プレリリース版)
  • OllamaSharp - ローカル LLM との通信
  • Azure.AI.OpenAI - Azure OpenAI との通信

Web アプリケーション関連（FCAIChat）

  • Microsoft.AspNetCore.Identity.EntityFrameworkCore - 認証・認可
  • Microsoft.AspNetCore.SignalR - リアルタイム通信
  • Microsoft.EntityFrameworkCore.SqlServer - データベースアクセス

デスクトップアプリケーション関連（FCAICad）

  • Windows Forms (.NET 8.0+)

技術用語の補足

AI エージェント関連用語
  • AI エージェント: LLM を活用して、ユーザーの要求に応じた処理を自律的に実行するソフトウェアコンポーネント
  • LLM (Large Language Model): 大規模言語モデル。自然言語を理解し生成する AI モデル
  • Microsoft Agent Framework: Microsoft が提供する AI エージェント開発用のフレームワーク（プレビュー版）
  • IChatClient: .NET の AI 拡張における、チャット機能を提供する標準インターフェース
  • AgentThread: 複数ターンの対話を管理するためのオブジェクト
MCP 関連用語
  • MCP (Model Context Protocol): AI エージェントと外部ツールやデータソースを接続するための標準プロトコル
  • STDIO: 標準入出力。プロセス間通信の基本的な方式
  • SSE (Server-Sent Events): サーバーからクライアントへの一方向リアルタイム通信プロトコル
LLM プラットフォーム
  • Ollama: ローカル環境で大規模言語モデルを実行するためのツール
  • Azure OpenAI: Microsoft Azure が提供するクラウド型の LLM サービス

ファイル・ディレクトリ構成

Shos.AIAgentSample/
├── 📄 README.md                                    # このファイル
├── 📄 LICENSE.txt                                  # ライセンス情報（MIT License）
├── 📄 Shos.AIAgentSample.sln                       # Visual Studio ソリューション
├── 📄 .mcp.json                                    # MCP サーバー設定（ルート、サンプル）
│
├── 📁 .github/                                     # GitHub Actions とエージェント設定
├── 📁 .vscode/
│   └── 📄 mcp.json                                # Visual Studio Code 用 MCP 設定
│
├── 📁 Documents/                                   # 📚 チュートリアルとリソース
│   ├── 📁 Images/                                 # チュートリアル用画像
│   ├── 📄 tutorial.md                             # チュートリアルメインページ
│   ├── 📄 tutorial.0.1.md                         # 0.1 インストールガイド
│   ├── 📄 tutorial.0.2.md                         # 0.2 Azure OpenAI セットアップ
│   ├── 📄 tutorial.1.1.md                         # 1.1 ローカル LLM の利用
│   ├── 📄 tutorial.1.2.md                         # 1.2 Azure OpenAI の利用
│   ├── 📄 tutorial.1.3.md                         # 1.3 複数ターンのチャット
│   ├── 📄 tutorial.2.1.md                         # 2.1 MCP サーバー (STDIO)
│   ├── 📄 tutorial.2.2.md                         # 2.2 MCP サーバー (SSE)
│   ├── 📄 tutorial.2.3.md                         # 2.3 MCP サーバーの動作確認
│   ├── 📄 tutorial.3.1.md                         # 3.1 MCP サーバー利用（単数）
│   ├── 📄 tutorial.3.2.md                         # 3.2 MCP サーバー利用（複数）
│   ├── 📄 tutorial.4.1.md                         # 4.1 後片付け
│   ├── 📄 aiagentlog.md                           # AI エージェント開発ログ
│   ├── 📄 maf.md                                  # Microsoft Agent Framework 情報
│   └── 📄 2025010.AIエージェント開発ハンズオンセミナー.pdf # セミナー資料
│
├── 📁 FCAIAgent/                                   # 🤖 最終形態の AI エージェント (FCAIAgent5と同等)
│   ├── 📄 Program.cs
│   └── 📄 FCAIAgent.csproj
│
├── 📁 FCAIAgent1/                                  # 🤖 ステップ 1: 基本的な AI エージェント
│   ├── 📄 Program.cs                              # メインプログラム
│   └── 📄 FCAIAgent1.csproj                       # プロジェクトファイル
│
├── 📁 FCAIAgent2/                                  # 🤖 ステップ 2: LLM 選択機能追加
│   ├── 📄 Program.cs
│   └── 📄 FCAIAgent2.csproj
│
├── 📁 FCAIAgent3/                                  # 🤖 ステップ 3: 複数ターン対話
│   ├── 📄 Program.cs
│   └── 📄 FCAIAgent3.csproj
│
├── 📁 FCAIAgent4/                                  # 🤖 ステップ 4: MCP サーバー連携（単数）
│   ├── 📄 Program.cs
│   └── 📄 FCAIAgent4.csproj
│
├── 📁 FCAIAgent5/                                  # 🤖 ステップ 5: MCP サーバー連携（複数）
│   ├── 📄 Program.cs
│   └── 📄 FCAIAgent5.csproj
│
├── 📁 FCAIChat1/                                   # 🌐 ステップ 1: 基本的な Web チャット
│   ├── 📁 Controllers/                            # MVC コントローラー
│   ├── 📁 Models/                                 # データモデル
│   ├── 📁 Views/                                  # Razor ビュー
│   ├── 📁 wwwroot/                                # 静的ファイル (CSS, JS, etc.)
│   └── 📄 FCAIChat1.csproj
│
├── 📁 FCAIChat2/                                   # 🌐 ステップ 2: LLM 選択機能付き Web チャット
│   └── 📄 FCAIChat2.csproj
│
├── 📁 FCAIChat3/                                   # 🌐 ステップ 3: 複数ターン対話 Web チャット
│   └── 📄 FCAIChat3.csproj
│
├── 📁 FCAIChat4/                                   # 🌐 ステップ 4: MCP 連携 Web チャット（単数）
│   └── 📄 FCAIChat4.csproj
│
├── 📁 FCAIChat5/                                   # 🌐 ステップ 5: MCP 連携 Web チャット（複数）
│   └── 📄 FCAIChat5.csproj
│
├── 📁 FCAICad1/                                    # 🎨 CAD アプリケーション
│   ├── 📄 Program.cs                              # メインプログラムとツール定義
│   ├── 📄 ChatAgent.cs                            # AI エージェント実装
│   ├── 📄 MainForm.cs                             # メインフォーム
│   ├── 📄 View.cs                                 # 描画ビュー
│   ├── 📄 Model.cs                                # データモデル
│   └── 📄 FCAICad1.csproj
│
├── 📁 McpServer.Con/                               # 🔧 STDIO MCP サーバー
│   ├── 📄 Program.cs                              # 時刻取得ツール実装
│   └── 📄 McpServer.Con.csproj
│
├── 📁 McpServer.Sse/                               # 🔧 HTTP/SSE MCP サーバー
│   ├── 📄 Program.cs                              # 天気予報ツール実装
│   └── 📄 McpServer.Sse.csproj
│
└── 📁 Reviews/                                     # コードレビュー記録

トラブルシューティング

よくある問題と解決方法

ビルドエラーが発生する

  • .NET SDK のバージョン確認

    dotnet --version

    .NET 8.0 以上（推奨: .NET 9.0）がインストールされているか確認してください。

  • パッケージの復元

    dotnet restore

  • プロジェクトのクリーンとリビルド

    dotnet clean
dotnet build
Ollama に接続できない

  • Ollama が起動しているか確認

    • Windows: タスクトレイに Ollama アイコンが表示されているか確認
    • ブラウザで http://localhost:11434 にアクセスして動作確認

  • モデルがダウンロードされているか確認

    ollama list

  • 必要なモデルのダウンロード

    ollama pull llama3.2
Azure OpenAI に接続できない

  • API キーとエンドポイントの確認

    • Azure Portal で正しい API キーとエンドポイントを取得しているか確認
    • コード内の設定値が正しいか確認

  • デプロイ名の確認

    • Azure OpenAI Studio でデプロイしたモデル名が正しいか確認

  • ネットワーク接続の確認

    • ファイアウォールやプロキシ設定を確認
MCP サーバーが見つからない

  • .mcp.json のパス確認

    • .mcp.json 内のパスが環境に合っているか確認
    • Windows の場合: バックスラッシュ (\) を使用
    • Linux/Mac の場合: スラッシュ (/) を使用

  • MCP サーバーのビルド確認

    cd McpServer.Con
dotnet build
Web アプリケーションが起動しない

  • ポートの競合確認

    • 他のアプリケーションが同じポートを使用していないか確認
    • launchSettings.json でポート番号を変更可能

  • HTTPS 証明書の問題

    dotnet dev-certs https --trust
CAD アプリケーションが起動しない
  • Windows Forms の要件
    • FCAICad1 は Windows でのみ動作します
    • .NET デスクトップ開発ワークロードがインストールされているか確認

問題が解決しない場合は、Issues で質問してください。

ライセンス

MIT License

Copyright (c) 2025 Fujio Kojima

詳細は LICENSE.txt を参照してください。

作者

小島 富治雄 (Fujio Kojima) - ソフトウェア開発エンジニア

🏆 経歴・実績

  • Microsoft MVP for Development Tools - Visual C# (Jul. 2005 - Dec. 2014)
  • Microsoft MVP for .NET (Jan. 2015 - Oct. 2015)
  • Microsoft MVP for Visual Studio and Development Technologies (Nov. 2015 - Jun. 2018)
  • Microsoft MVP for Developer Technologies (Nov. 2018 - Jun. 2026)

📫 連絡先・リンク

謝辞

このプロジェクトは、以下のオープンソースプロジェクトと技術を使用しています：

これらの素晴らしいツールとフレームワークを提供してくださった開発者とコミュニティの皆様に深く感謝いたします。

貢献

このプロジェクトへの貢献を歓迎します！バグ報告、機能要望、ドキュメントの改善、プルリクエストなど、あらゆる形での貢献をお待ちしています。

貢献の方法

  1. このリポジトリをフォーク

    • GitHub で「Fork」ボタンをクリック

  2. フィーチャーブランチを作成

    git checkout -b feature/amazing-feature

  3. 変更をコミット

    git commit -m 'Add some amazing feature'

  4. ブランチにプッシュ

    git push origin feature/amazing-feature

  5. プルリクエストを作成

    • GitHub でプルリクエストを作成してください

報告とフィードバック

種類 方法
🐛 バグ報告 Issues でバグを報告
💡 機能要望 Issues で新機能を提案
❓ 質問 Discussions で質問を投稿

皆様からのフィードバックと貢献をお待ちしています！

重要な注意事項

⚠️ このリポジトリのコードは学習・チュートリアル目的で提供されています。

使用上の注意

項目 注意事項
🔬 開発段階 プレビュー版の Microsoft Agent Framework を使用しています
🏭 本番環境 本番環境での使用前に、適切なセキュリティレビューと最適化を行ってください
🔐 セキュリティ API キーやシークレットは環境変数や安全な設定管理ツールを使用してください
📦 将来の変更 Microsoft Agent Framework は今後のバージョンアップで仕様が変わる可能性があります

推奨事項

  • 学習目的: このリポジトリは学習とプロトタイピングに最適です
  • 本番利用: 本番環境に適用する場合は、コードのレビューと最適化を実施してください
  • セキュリティ: 機密情報の取り扱いには十分注意してください

Last Updated: 2025-01
Repository: https://github.com/Fujiwo/Shos.AIAgentSample
License: MIT License

このリポジトリに関するご質問やフィードバックは、Issues または Discussions でお気軽にお寄せください。

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages