ラボ BAF1 - 最初のエージェントの構築と実行

このラボでは、 Microsoft 365 Agents SDK と Agent Framework を使用してカスタムエンジンエージェントを構築し、実行します。スタータープロジェクトを調査し、主要コンポーネントを理解し、Microsoft 365 Copilot 内でエージェントがどのように動作するかを確認します。

Zava Insurance エージェントは、保険査定担当者がクレーム処理を効率化するために設計されています。この最初のラボでは、ユーザーにあいさつし、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 にデプロイできます。

Exercise 1: プロジェクトのクローンと調査

この演習では、Copilot Camp リポジトリをクローンし、スタータープロジェクト構造を調査してエージェントの構成を理解します。

Step 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 .

Step 2: プロジェクト構造の調査

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

1️⃣ Visual Studio Code のエクスプローラービューでフォルダーを展開します。次のような構造が表示されます:

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

Step 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 リストを設定
startConversationPlugin.StartConversation を AIFunctionFactory.Create で追加
DateTimeFunctionTool.getDate も同様に追加

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

Step 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 をフォーマットして返す

このプラグインにより、エージェントがシステム情報へアクセスしてユーザーの質問に回答できます。

Step 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 セクションでは、エージェントがカスタムエンジンエージェントとしてどのような機能を持つかを定義しています。

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

Program.cs で全体がどのようにまとめられているかを見てみましょう。

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

2️⃣ 理解すべき主なセクション:

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

AddEnvFile で .env ファイル（環境別設定）
AddUserSecrets でユーザーシークレット（API キーなど機密情報）
AddEnvironmentVariables で環境変数

サービス登録: builder.Services でサービスを登録している箇所を確認:

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

チャットクライアント設定: IChatClient をシングルトンで登録している箇所を探します。次のような処理を行っています:

エンドポイント、API キー、デプロイ名を構成から取得
AzureOpenAIClient をエンドポイントと資格情報で作成
指定したデプロイ（gpt-4.1）のチャットクライアントを返却

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

Exercise 2: エージェントの構成

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

Step 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

Step 2: Azure AI 資格情報の追加

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

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

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

MODELS_ENDPOINT=https://your-resource.cognitiveservices.azure.com/

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

エンドポイントを忘れた場合:

Azure AI 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 に含まれています。このファイルをソース管理にコミットしないでください。

Step 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 拡張機能に権限を付与する必要があります。

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

それでは、エージェントを実行して動作を確認しましょう！

Step 1: エージェントの起動

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

1️⃣ Visual Studio Code で 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 の選択（Azure AI 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 エージェントの インストールダイアログ が表示されるので Add をクリックします。

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

Step 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" を試してください。

エージェントは AI の知識を活用して、保険クレームについて説明します。

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

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

Step 3: デバッグ出力の確認

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

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

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

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

Step 1: 歓迎メッセージの更新

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

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

3️⃣ 最初の行にあなたの名前を追加します: "👋 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 を統合し、ドキュメント検索によるより強力な機能を追加します！