ラボ BAF1 - はじめてのエージェントの構築と実行

このラボでは、 Microsoft 365 Agents SDK と Agent Framework を使用してカスタムのエンジンエージェントを構築し、実行します。スタータープロジェクトを探索し、コアコンポーネントを理解し、エージェントが Microsoft 365 Copilot で動作する様子を確認します。

Zava Insurance Agent は、保険査定担当者が請求処理を効率化するために設計されています。この最初のラボでは、ユーザーに挨拶し、AI を活用した回答を提供できる基本的な会話エージェントから始めます。

Microsoft 365 Agents SDK と Agent Framework とは？

Microsoft 365 Agents SDK は、Microsoft 365 の各チャネル (Teams、Copilot など) にエージェントをデプロイするためのコンテナーとスキャフォールディングを提供し、アクティビティ、イベント、通信を処理します。AI 非依存で、任意の AI サービスを利用できます。

Agent Framework は、LLM、ツール呼び出し、マルチエージェントワークフローを使用して AI エージェントを構築するためのオープンソース開発キットです。Semantic Kernel と AutoGen の後継であり、AI 機能とエージェントロジックを提供します。

これらを組み合わせることで、Agent Framework でインテリジェントなエージェントを構築し、Agents SDK を使って Microsoft 365 にデプロイできます。

演習 1: プロジェクトのクローンと探索

この演習では、Copilot Camp リポジトリをクローンし、スタータープロジェクトの構成を確認してエージェントがどのように整理されているかを理解します。

手順 1: リポジトリのクローン

まず Copilot Camp リポジトリをクローンし、Agent Framework のスタータープロジェクトに移動します。

1️⃣ ターミナルまたはコマンドプロンプトを開きます。

2️⃣ リポジトリをクローンします:

git clone https://github.com/microsoft/copilot-camp.git
cd copilot-camp/src/agent-framework/begin

3️⃣ Visual Studio Code でプロジェクトを開きます:

code .

手順 2: プロジェクト構成の確認

エージェントプロジェクトの構成を理解しましょう。

1️⃣ Visual Studio Code で Explorer ビューのフォルダーを展開します。以下のような構成が表示されるはずです:

begin/
├── src/
│   ├── Agent/
│   │   └── ZavaInsuranceAgent.cs       # Main agent implementation
│   ├── Plugins/                        # Custom plugins (tools) for the agent
│   │   ├── StartConversationPlugin.cs  # Welcome message plugin
│   │   └── DateTimeFunctionTool.cs     # Date/time utility
├── appPackage/                         # Teams app manifest and icons
├── env/                                # Environment configuration files (API keys, endpoints)
├── infra/                              # All required scripts, data and templates for the agent's infrastructure
├── Program.cs                          # Application entry point - configures services and starts web app
├── InsuranceAgent.csproj               # Project file
└── m365agents.local.yml                # M365 Agents provisioning config

手順 3: エージェント実装の理解

メインのエージェントファイルを確認し、動作を把握します。

1️⃣ src/Agent/ZavaInsuranceAgent.cs を Visual Studio Code で開きます。

2️⃣ クラス冒頭付近にある AgentInstructions プロパティを探します。これらの指示が AI モデルの システムプロンプト として機能していることに注目してください。

エージェントの役割を定義しています: "You are a professional insurance claims assistant for Zava Insurance..."
{{PluginName.FunctionName}} 構文を使用して利用可能なツールを列挙しています
{{StartConversationPlugin.StartConversation}} と {{DateTimeFunctionTool.getDate}} を含んでいます

これらの指示により、AI に行動指針と使用可能なツールが伝えられます。

3️⃣ 下にスクロールして コンストラクター メソッド ZavaInsuranceAgent(...) を見つけます。イベントハンドラーが設定されていることを確認します。

OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeMessageAsync) - ユーザーが参加した際にウェルカムメッセージを送信
OnActivity(ActivityTypes.Message, OnMessageAsync) - 受信メッセージを処理

4️⃣ GetClientAgent メソッドを探します。toolOptions を作成し、プラグインを登録している箇所を確認します。

ChatOptions オブジェクトを作成し、Tools リストを設定
AIFunctionFactory.Create を用いて startConversationPlugin.StartConversation を追加
同様に DateTimeFunctionTool.getDate を追加

ここで、会話中に AI が呼び出す プラグイン (ツール) を登録しています。

手順 4: プラグインの確認

プラグインがどのように機能するか見てみましょう。

1️⃣ src/Plugins/StartConversationPlugin.cs を開きます。

2️⃣ プラグインの構造を確認します:

public class StartConversationPlugin
{
    [Description("Starts a new conversation suggesting a conversation flow.")]
    public async Task<string> StartConversation()
    {
        var welcomeMessage = "👋 Welcome to Zava Insurance Claims Assistant!...";
        return welcomeMessage;
    }
}

注目ポイント:

[Description] 属性は AI に いつこのツールを使用するか を伝えます
メソッドはフォーマット済みのウェルカムメッセージを返します
引数のないシンプルなプラグインです

3️⃣ src/Plugins/DateTimeFunctionTool.cs を開きます。

4️⃣ 現在の日付と時刻を提供する方法を確認します。

[Description] に "Gets the current date and time" と記載
getDate() メソッドは static で、DateTime.Now をフォーマットして返します

このプラグインは、エージェントがシステム情報へアクセスしてユーザーの質問に答える方法を示しています。

手順 5: アプリマニフェストと会話スターターの確認

アプリマニフェストを確認し、Microsoft 365 Copilot でエージェントがどのように表示されるか見てみましょう。

1️⃣ appPackage/manifest.json を開きます。

2️⃣ name セクションでエージェントの表示名を確認します。

"name": {
    "short": "Zava Insurance Agent",
    "full": "Zava Insurance Claims Assistant"
}

3️⃣ conversationStarters 配列までスクロールします。これは、ユーザーがエージェントと最初に対話するときに表示される推奨プロンプトです。

"conversationStarters": [
    {
        "title": "Instructions",
        "description": "What can you do?"
    },
    {
        "title": "Today's Date",
        "description": "What's today's date?"
    },
    {
        "title": "About Insurance",
        "description": "Tell me about insurance claims"
    },
    {
        "title": "Claims Process",
        "description": "Explain how claims processing works"
    }
]

これらの会話スターターは、ユーザーがエージェントとどのように対話すればよいかをガイドします。エージェントの機能に合わせてカスタマイズできます。

4️⃣ copilotAgents.declarativeAgent セクションでは、カスタムエンジンエージェントとしての機能が定義されています。

手順 6: アプリケーションエントリポイントの確認

Program.cs で全体がどのように組み合わさっているかを見てみましょう。

1️⃣ Program.cs を開きます。

2️⃣ 理解しておくべき主なセクション:

構成の読み込み: builder.Configuration が設定を読み込む箇所を探します。複数のソースから読み込んでいることに注目してください。

.env ファイル (環境別設定) - AddEnvFile
機密データ (API キーなど) のための User secrets - AddUserSecrets
環境変数 - AddEnvironmentVariables

サービス登録: builder.Services にサービスを登録している箇所を確認します。

AddSingleton<IStorage, MemoryStorage>() - 会話状態用にメモリストレージを登録
AddAgentApplicationOptions() - エージェント構成を登録
AddAgent<ZavaInsuranceAgent>() - エージェント本体をサービスとして登録

チャットクライアント構成: IChatClient がシングルトンとして登録される箇所を確認します。以下のように動作します。

エンドポイント、API キー、デプロイ名を設定から取得
AzureOpenAIClient をエンドポイントと資格情報で作成
指定されたデプロイメント (gpt-4.1) 用のチャットクライアントを返却

これにより、エージェントの AI 機能を支える Azure OpenAI との接続が確立されます。

演習 2: エージェントの構成

エージェントを実行する前に、Azure AI の資格情報を設定する必要があります。

手順 1: 環境ファイルの設定

エージェントは環境ファイルを使用して構成を管理します。設定を行いましょう。

1️⃣ Visual Studio Code で env/ フォルダーに移動します。

2️⃣ 2 つのサンプルファイルがあることを確認します。

.env.local.sample
.env.local.user.sample

3️⃣ .env.local.sample を .env.local にコピーします。

Windows PowerShell:

Copy-Item env/.env.local.sample env/.env.local

macOS/Linux:

cp env/.env.local.sample env/.env.local

4️⃣ .env.local.user.sample を .env.local.user にコピーします。

Windows PowerShell:

Copy-Item env/.env.local.user.sample env/.env.local.user

macOS/Linux:

cp env/.env.local.user.sample env/.env.local.user

手順 2: Azure AI 資格情報の追加

次に、Microsoft Foundry のデプロイメントを使用するようエージェントを構成します。

1️⃣ env/.env.local を Visual Studio Code で開きます。

2️⃣ MODELS_ENDPOINT 変数を見つけ、Lab BAF0 で取得した Azure AI エンドポイントに更新します。

MODELS_ENDPOINT=https://your-resource.services.ai.azure.com/

エンドポイントの確認方法

エンドポイントがわからない場合は、以下の手順で確認できます。

Microsoft Foundry にアクセス
プロジェクトを選択
Settings → Properties を開く
Endpoint の URL をコピー

3️⃣ env/.env.local.user を Visual Studio Code で開きます。

4️⃣ SECRET_MODELS_API_KEY 変数を見つけ、API キーを入力します。

SECRET_MODELS_API_KEY=your-api-key-here

API キーの取り扱いに注意

.env.local.user ファイルには機密情報が含まれており、既に .gitignore に追加されています。このファイルをソース管理にコミットしないでください。

手順 3: Microsoft 365 と Azure へのサインイン

Microsoft 365 Agents Toolkit は、Microsoft 365 と Azure の両方への認証が必要です。

1️⃣ Visual Studio Code で、アクティビティバー (左側) の Microsoft 365 Agents Toolkit アイコンをクリックします。

2️⃣ ツールキットパネルで ACCOUNTS セクションを探します。

3️⃣ Sign in to Microsoft 365 をクリックし、サインインフローを完了します。

4️⃣ Sign in to Azure をクリックし、サインインフローを完了します。

初回サインイン

初回サインイン時には、Microsoft 365 Agents Toolkit 拡張機能に権限を付与する必要があります。

演習 3: エージェントの実行とテスト

いよいよエージェントを実行し、その動きを確認しましょう！

手順 1: エージェントの起動

F5 デバッグ機能を使ってエージェントを実行します。

1️⃣ Visual Studio Code で既定のデバッグ構成 (Preview) Debug in Copilot (Edge) を選択し、 F5 を押すか、メニューの Run → Start Debugging を選択します。

2️⃣ デバッグターゲットを選択するよう求められたら、 (Preview) Debug in Copilot (Edge) を選択します。

デバッグターゲットの選択肢

"Debug in Teams (Edge)" や "Debug in Teams (Chrome)" など複数のオプションが表示される場合があります。Microsoft 365 Copilot でテストするには、必ず (Preview) Debug in Copilot (Edge) を選択してください。

3️⃣ エージェントを初めて実行する際、Microsoft 365 Agents Toolkit は次の操作を行います。

Azure subscription を選択するように求められます
新しい resource group を作成するか既存のものを選択します
リソースの region を選択します (Microsoft Foundry プロジェクトに近いリージョンを推奨)
Azure リソース (Azure Bot Service、App Registration) をプロビジョニングします

このプロビジョニングプロセスには通常 2～3 分かかります。

Azure リソースのプロビジョニング

初回実行時、ツールキットは以下を作成します。

Azure Bot Service - メッセージのルーティングを処理
App Registration - 認証を管理
Dev Tunnel - ローカルマシンへの安全なトンネルを作成

4️⃣ Visual Studio Code の Terminal 出力を確認します。次のようなログが表示されるはずです。

🌍 Environment: local
🏢 Starting Zava Insurance Agent...
🤖 Main agent using model: gpt-4.1
✅ Agent initialized successfully!

5️⃣ Microsoft 365 Copilot がブラウザーで開きます。

6️⃣ Zava Insurance Agent の インストールダイアログ が表示されます。 Add をクリックします。

7️⃣ インストール後、 Open in Copilot または Chat をクリックします。

手順 2: 基本的な会話のテスト

エージェントと対話してみましょう！

1️⃣ Microsoft 365 Copilot で、チャットウィンドウにエージェントと会話スターターが表示されているはずです。

Conversation starters in Microsoft 365 Copilot

2️⃣ 「What can you do?」を選択してウェルカムメッセージを表示します。

Conversation starters in Microsoft 365 Copilot

3️⃣ "What's today's date?" と尋ねてみましょう。

エージェントは DateTimeFunctionTool を呼び出し、現在の日付と時刻を返すはずです。

4️⃣ "What can you do?" または "Start over" と尋ねてみましょう。

エージェントは StartConversationPlugin を呼び出し、再度ウェルカムメッセージを表示します。

5️⃣ 一般的な質問を試してください: "Tell me about insurance claims"

エージェントは保険金請求について有用な説明を提供するはずです。

6️⃣ 範囲外の質問を試してください: "What's the weather today?"

エージェントは保険アシスタントとしての範囲外である旨を丁寧に伝えるはずです。

手順 3: デバッグ出力の確認

1️⃣ Visual Studio Code に戻り、 Debug Console を確認します。

2️⃣ プラグイン呼び出し、AI 応答、メッセージ処理がリアルタイムでログに表示されることを確認します。

演習 4: エージェントのカスタマイズ

エージェントを簡単に変更して、パーソナライズしてみましょう。

手順 1: ウェルカムメッセージの更新

1️⃣ デバッガーを停止します (Shift+F5)。

2️⃣ src/Plugins/StartConversationPlugin.cs を開き、welcomeMessage 変数を探します。

3️⃣ 1 行目を変更して自分の名前を追加します。例: "👋 Welcome! I'm [Your Name]'s Agent!\n\n"

4️⃣ 保存して F5 を押して再起動し、Copilot に "start over" と入力して変更を確認します。

おめでとうございます！

ラボ BAF1 - はじめてのエージェントの構築と実行を完了しました！

このラボで学んだこと:

✅ Agent Framework プロジェクトのクローンと探索
✅ Azure AI 資格情報によるエージェントの構成
✅ ローカルでのエージェントの実行とデバッグ
✅ Microsoft 365 Copilot でのエージェントのテスト
✅ コアコンポーネント (エージェント、プラグイン、インストラクション) の理解
✅ 動作をカスタマイズする簡単な変更の方法

次のラボでは、Azure AI Search と gpt-4.1 を用いたドキュメント検索の統合により、さらに強力な機能を追加します！