初めてのアドインを Copilot スキルとして構築する

2025-06-10

この記事では、Excel ブックのコンテンツに対してアクションを実行できる単純な Excel Copilot エージェントを構築するプロセスについて説明します。アプリには、Excel 作業ウィンドウアドインも含まれています。

知識の前提条件

Microsoft 365 Copilotでの宣言型エージェントの基本的な理解。まだ理解していない場合は、次のアクションをお勧めします。
- Microsoft 365 Copilotの概要については、「宣言型エージェント」を参照してください。
- 「Microsoft 365 Agent Toolkit を使用して宣言型エージェントを作成する」で始まるチュートリアルを完了します。

ソフトウェアの前提条件

「Microsoft 365 Agent Toolkit を使用して宣言型エージェントを作成する」に記載されているすべての前提条件。
Microsoft 365 エージェントツールキット。

Office アドインから開始する

次の手順で基本的な Excel アドインを作成します。

「Microsoft 365 Agent Toolkit を使用した Office アドインプロジェクトの作成」の手順に従って、Microsoft 365 Agent Toolkit で Office アドインを作成します。 プロジェクトの作成後に停止します。サイドローディングセクションの手順は実行しないでください。

注:

アドインに名前を付けるメッセージが表示されたら、"Excel アドイン + エージェント" を使用します。
プロジェクトが新しい Visual Studio Code ウィンドウで開きます。元の Visual Studio Code ウィンドウを閉じます。
プロジェクトのルートにあるコマンドプロンプトまたは Visual Studio Code TERMINAL で、 npm installを実行します。

アドインをサイドロードしてテストする

次の手順を実行して、アドインが機能することをテストします。
1. [表示] を選択する | Visual Studio Code でを実行します。 [実行とデバッグ] ドロップダウンメニューで、[Excel Desktop (Edge Chromium)] を選択します。
2. F5 キーを押します。プロジェクトがビルドされ、Node dev-server ウィンドウが開きます。このプロセスには数分かかる場合があります。最終的に、Excel が開きます。
注:

コンピューターに Office アドインを初めてサイドロードした場合 (または 1 か月を超えて初めて) 場合は、古い証明書を削除したり、新しい証明書をインストールしたりするように求められる場合があります。両方のプロンプトに同意します。
1. [ホーム] リボンの [アドイン] ボタンを選択し、開いたポップアップでアドインを選択します。
2. [タスクウィンドウの表示] ボタンを含む Contoso アドイン グループが [ホーム] リボンに表示されます。ボタンを使用して、アドインの作業ウィンドウを開きます。
注:

WebView Stop On Load プロンプトが表示されたら、[OK] を選択します。
1. 作業ウィンドウが開いたら、[実行] を選択 します。ワークシート内のセルが黄色に変わります。
2. Excel をシャットダウンし、プロジェクトのルートにあるコマンドプロンプトまたは Visual Studio Code TERMINAL でnpm run stopを実行して、デバッグを停止し、アドインをアンインストールします。
  
  重要
  
  Visual Studio Code の UI でのデバッグの停止は、バグのため現在機能しません。また、Excel を閉じたり、開発サーバーウィンドウを手動で閉じたりすることも、サーバーを確実にシャットダウンすることも、Excel がアドインを取得解除することもありません。 npm run stopを実行する必要があります。

Copilot 宣言型エージェントを追加する

次の手順でエージェントを追加します。

マニフェストファイルで、次の変更を行います。
1. ルートに次のオブジェクトを追加します。規則により、"validDomains" プロパティのすぐ下に配置されます。 "declarativeAgent.json" ファイルは、後の手順で作成します。
```
"copilotAgents": {
  "declarativeAgents": [
    {
      "id": "ContosoCopilotAgent",
      "file": "declarativeAgent.json"
    }
  ]
},
```
2. "extensions.runtimes"配列には複数のオブジェクトがあります。 "id"が "CommandRuntime" であるものを見つけて、配列内の追加のランタイムオブジェクトとしてコピーします。
3. この追加のランタイムオブジェクトに次の変更を加えます。
  1. "id"を "CommandRuntime" から "CopilotAgentActionsRuntime" に変更します。
  2. "actions.id" プロパティを "fillcolor" に変更します。これは、後の手順で追加する関数の ID です。
  3. "actions.type" プロパティを "executeDataFunction" に変更します。
declarativeAgent.json という名前の appPackage フォルダーにファイルを作成します。

次の内容をファイルに貼り付けます。 (この JSON に記載されている Excel-API-local-plugin.json ファイルは、後の手順で作成します)。

{
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
     "version": "v1.4",
     "name": "Excel Add-in + Agent",
     "description": "Agent for working with Excel cells.",
     "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
     "conversation_starters": [
         {
             "title": "Change cell color",
             "text": "I want to change the color of cell B2 to orange"
         }
     ],
     "actions": [
         {
             "id": "localExcelPlugin",
             "file": "Excel-API-local-plugin.json"
         }
     ]
 }

Excel-API-local-plugin.json という名前の appPackage フォルダーにファイルを作成します。

次の内容をファイルに貼り付けます。

{
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
     "schema_version": "v2.3",
     "name_for_human": "Excel Add-in + Agent",
     "description_for_human": "Add-in Actions in Agents",
     "namespace": "addinfunction",
     "functions": [
         {
             "name": "fillcolor",
             "description": "fillcolor changes a single cell location to a specific color.",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "Cell": {
                         "type": "string",
                         "description": "A cell location in the format of A1, B2, etc.",
                         "default" : "B2"
                     },
                     "Color": {
                         "type": "string",
                         "description": "A color in hex format, e.g., #30d5c8",
                         "default" : "#30d5c8"
                     }
                 },
                 "required": ["Cell", "Color"]
             },
             "returns": {
                 "type": "string",
                 "description": "A string indicating the result of the action."
             },
             "states": {
                 "reasoning": {
                     "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
                     "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
                 },
                 "responding": {
                     "description": "`fillcolor` changes the color of a single cell based on the grid location and a color value.",
                     "instructions": "If there is no error present, tell the user the cell location and color that was set."
                 }
             }
         }
     ],
     "runtimes": [
         {
             "type": "LocalPlugin",
             "spec": {
                 "local_endpoint": "Microsoft.Office.Addin",
                 "allowed_host": ["workbook"]
             },
             "run_for_functions": ["fillcolor"]
         }
     ]
 }

\src\commands\commands.ts ファイルを開き、その末尾に次のコードを追加します。

async function fillcolor(cell, color) {
    await Excel.run(async (context) => {
         context.workbook.worksheets
             .getActiveWorksheet()
             .getRange(cell).format.fill.color = color;
         await context.sync();
     })
}

Office.onReady((info) => {
     Office.actions.associate("fillcolor", async (message) => {
         const {Cell: cell, Color: color} = JSON.parse(message);
         await fillcolor(cell, color);
         return "Cell color changed.";
     });
});

アドインと Copilot エージェントを組み合わせたプロジェクト構成ファイルを更新する

プロジェクトのルートには teamsapp.yaml または m365agents.yaml というファイルがあります。その内容を次のように置き換えます。

# yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
# Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
# Visit https://aka.ms/teamsfx-actions for details on actions
version: v1.7

environmentFolderPath: ./env

# Triggered when 'teamsapp provision' is executed
provision:
# Creates a Teams app
  - uses: teamsApp/create
    with:
     # Teams app name
     name: Contoso Agent ${{APP_NAME_SUFFIX}}
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     teamsAppId: TEAMS_APP_ID

# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Extend your Teams app to Outlook and the Microsoft 365 app
  - uses: teamsApp/extendToM365
    with:
     # Relative path to the build app package.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     titleId: M365_TITLE_ID
     appId: M365_APP_ID

# Triggered when 'teamsapp publish' is executed
publish:
# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Apply the Teams app manifest to an existing Teams app in
# Teams Developer Portal.
# Will use the app id in manifest file to determine which Teams app to update.
  - uses: teamsApp/update
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Publish the app to
# Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
# for review and approval
  - uses: teamsApp/publishAppPackage
    with:
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
projectId: da53b0a2-1561-415e-919a-5b870bcd2f49

前の手順で貼り付けたコンテンツの最後の行の projectId の値を、ランダムに生成された新しい GUID に置き換えます。
\env.env.dev ファイルを開き、"ADDIN_ENDPOINT=" 行の直後のファイルの末尾に次の行を追加します。
```
TEAMS_APP_ID=
TEAMS_APP_TENANT_ID=
M365_TITLE_ID=
M365_APP_ID=
```

アドインとエージェントをテストする

すべての Office アプリケーションを閉じます。
Microsoft 365 Agent Toolkit を開きます。
[ ライフサイクル ] ウィンドウで、[ プロビジョニング] を選択します。特に、プロビジョニングでは次の処理が行われます。
- .env.dev ファイルに追加した 4 行の値を設定します。
- パッケージ zip ファイルを使用して、/appPackage フォルダー内に /build フォルダーを作成します。ファイルには、エージェントとプラグインのマニフェストファイルと JSON ファイルが含まれています。
プロジェクトのルートにあるコマンドプロンプトまたは Visual Studio Code TERMINAL で、 npm run dev-server を実行して localhost でサーバーを起動します。アプリが正常にコンパイルされた行がサーバーウィンドウに表示されるまで待ちます。つまり、サーバーはファイルを実行して提供しています。

注:

コンピューターで Office アドインのローカルサーバーを実行した月が初めてである場合は、古い証明書を削除したり、新しい証明書をインストールしたりするように求められる場合があります。両方のプロンプトに同意します。
テストの最初の手順は、プラットフォームによって異なります。
- Windows 上の Office でテストするには、Excel を開きます。しばらくすると、Contoso アドイングループの [ホーム] リボンに [作業ウィンドウの表示] ボタンが表示されます。 (リボンに表示されない場合は、リボン の [アドイン ] ボタンを選択し、開くポップアップで Excel アドイン + エージェント アプリを選択します)。
- Office on the webでテストするには、ブラウザーで [https://excel.cloud.microsoft.com/] に移動し、新しいブックを作成します。
リボンから Copilot を開き、[ Copilot ] ウィンドウでハンバーガーコントロールを選択します。 Excel アドインとエージェントは、エージェント の一覧に含まれている必要があります。 (すべてのエージェントが確実に一覧表示されるようにするには、[ 詳細を表示 ] を選択する必要がある場合があります)。エージェントがそうでない場合は、次のアクションのいずれかまたは両方を試してください。
- 数分待ってから Copilot を再読み込みします。
- Copilot を開いてエージェントの一覧を開き、[Copilot] ウィンドウでカーソルをクリックし、Ctrl+Rキーを押します。
エージェントが一覧表示されたら、それを選択します。 [Excel アドインとエージェント] ウィンドウが開きます。
[ セルの色の会話の変更 ] スターターを選択し、ウィンドウの下部にある会話ボックスの [送信 ] コントロールを押します。確認プロンプトに応答して [ 確認 ] を選択します。セルの色が変更されます。

ヒント

Copilot からエラーが報告された場合は、プロンプトを繰り返しますが、"エラーが発生した場合は、エラーの完全なテキストを報告してください" という文をプロンプトに追加します。
"セル G5 を空の色に設定する" など、会話ボックスにセルと色の他の組み合わせを入力してみてください。

アドインまたはエージェントに変更を加える

アドインとエージェントを組み合わせたライブリロードとホットリロードは、プレビュー期間中はサポートされていません。変更を行うには、まずサーバーをシャットダウンし、次の手順で拡張機能をアンインストールします。

サーバーのシャットダウンは、実行されているウィンドウによって異なります。
- Web サーバーが、npm run dev-serverを実行したのと同じコマンドプロンプトまたは Visual Studio Code TERMINAL で実行されている場合は、ウィンドウにフォーカスを設定して Ctrl+Cキーを押します。プロンプトに応答してプロセスを終了するには、"Y" を選択します。
- Web サーバーが別のウィンドウで実行されている場合は、コマンドプロンプトまたはプロジェクトのルートにある Visual Studio Code TERMINAL で、 npm run stopを実行します。
「キャッシュを手動でクリアする」の手順に従って Office キャッシュをクリアします。
Teams を開き、アプリバーから [アプリ] を選択し、[アプリ] ウィンドウの下部にある [アプリの管理] を選択します。
アプリの一覧 で Excel アドインとエージェント を検索し、名前の左側にある矢印を選択して行を展開します。
行の右端付近にあるごみ箱アイコンを選択し、プロンプトで [削除 ] を選択します。

変更を加え、「アドインとエージェントをテストする」の手順を繰り返します。

トラブルシューティング

「アドインとエージェントの組み合わせのトラブルシューティング」を参照してください。

次の手順

既存のアドインに Copilot エージェントを追加する