Office JavaScript ライブラリを使用してMicrosoft 365 Copilot用の API プラグインをビルドする (プレビュー)

2025-05-20

注:

この記事で説明する開発機能はプレビュー段階です。この機能を試すのをお勧めしますが、運用環境のプラグインでは使用しないでください。初期プレビュー中の制限事項を次に示します。

この機能は、Windows および Office on the web の Office でのみ有効になっています。 Microsoft では、Office on Mac のサポートの提供に取り組んでいます。
この機能は、Excel、PowerPoint、またはWordに対してのみ有効になります。 Outlook のサポートを提供するために取り組んでいます。

宣言型エージェントのプラグインは、 Office JavaScript ライブラリの API を呼び出して、Office アプリケーションで現在開いている Office ドキュメントのコンテンツとメタデータに対して読み取りおよび書き込み操作を実行できます。この機能により、Copilot は Office アドインを必要とする正確でエラーのない方法で Office ドキュメントを操作できます。

Office アドインフレームワークに対する Copilot エージェントの関係

Office アドインと宣言型エージェントプラグインはどちらも Office JavaScript ライブラリの API を呼び出し、ライブラリを使用する Microsoft 365 拡張機能にはプラグイン、アドイン、またはその両方を含めることができます。最適な方法は、拡張機能で有効にする必要があるユーザーシナリオによって異なります。

拡張機能でパラメーターを渡す必要のないシンプルで高速なアクションを提供する必要がある場合は、アドインコマンドと呼ばれるカスタムリボンボタンまたはメニューを含むアドインのみを含めます。
拡張機能にダッシュボードエクスペリエンスが必要な場合、ユーザーが設定を構成する必要がある場合、Office ドキュメントのコンテンツに関するメタデータを表示する必要がある場合、または他の理由でページのようなエクスペリエンスが必要な場合は、作業ウィンドウを含むアドインを含めます。
拡張機能が実行時に渡されるパラメーターを必要とする複雑なアクションを提供する必要がある場合、または自然言語インターフェイスが必要な場合は、Copilot エージェントを含めます。

シナリオ

Office JavaScript ライブラリ API を呼び出す Copilot エージェントが Microsoft 365 拡張機能の価値を高める方法を次に示します。

コンテンツ分析: エージェントを使用して、ドキュメント、プレゼンテーション、スプレッドシートの内容を分析し、見つけた内容に応じてアクションを実行できます。次に例を示します。
- エージェントは提案要求 (RFP) を分析し、バックエンドシステムから RFP の質問に対する回答をフェッチします。ユーザーは、エージェントに "質問に関して知っている回答を入力してください" と要求するだけです。
- エージェントは、ドキュメント自体または顧客のビジネスシステムの他の場所で、特定のアクションを実行する必要があることを意味するコンテンツについて、ドキュメントまたはスプレッドシート内のテーブルを分析します。ユーザーは、"監査リストで見逃した項目がないかドキュメントを確認してください" とエージェントに求める場合があります。
データの信頼された挿入: 一般的な AI エンジンに質問をすると、見つけた情報が結合され、回答が作成されます。誤りを発生する可能性のあるプロセス。ただし、アドインに基づく Copilot エージェントは、信頼されたソースから 変更せずに データを挿入できます。次にいくつか例を示します。
- 編集できるWordへの法的研究の挿入を可能にするエージェントを検討してください。ユーザーはエージェントに「どのような状況で、賃貸人が一方的にインディアナ州の住宅空間のリースを破ることができるか」と尋ねます。次に、エージェントは、優先順位と統計から変更されずにコンテンツをフェッチし、ドキュメントに挿入します。
- デジタル資産のインベントリを管理するエージェントを検討します。 Copilot エージェントチャットで、ユーザーは "それぞれの名前、ダウンロードされた回数、そのサイズをメガバイト単位で、最もダウンロードされた順に並べ替えた色の写真の表を挿入する" と尋ねます。次に、エージェントはレコードのシステムからこのデータを変更せずにフェッチし、テーブルを Excel スプレッドシートに挿入します。

エージェントをアドインと組み合わせると、さらに多くのシナリオが有効になります。 Office アドインにMicrosoft 365 Copilot エージェントを含めると、アドインに少なくとも 2 つの利点があります。

Copilot は、アドインの機能の自然言語インターフェイスになります。
エージェントは、呼び出す JavaScript にパラメーターを渡すことができます。これは、アドイン内の関数コマンドがボタンまたはメニュー項目から呼び出された場合には実行できません。

アドインの使用方法を学習することは、エージェントがアドインを強化する 1 つの方法です。ユーザーが目標を達成するためにアドインで複数の手順またはタスクを実行する必要がある場合、Copilot のチャットインターフェイスを使用すると、アドインの使用を開始するプロセスを容易にすることができます。たとえば、準備する各リースについて回答する必要がある質問の一覧が必要な法律事務所を考えてみましょう。この質問の一覧を作成すると、時間がかかり、労働集約的になる場合があります。ただし、Copilot エージェントは、Office JavaScript ライブラリを使用して、質問の最初の下書きリストを作成し、それらをWordドキュメントに挿入するように求めることができます。

初めての Office JavaScript ライブラリプラグインを作成する

Office JavaScript ライブラリ API を呼び出す Copilot エージェント用の API プラグインを作成するための主要な手順を次に示します。

前提条件を満たしていることを確認します
SimpleMailApp プロジェクトの作成
マニフェストを構成する
宣言型エージェントを構成する
プラグインを構成する
JavaScript 関数を作成する
プロジェクト構成ファイルをコピーする
エージェントとプラグインをテストする
エージェントで変更を加えます

前提条件

「Copilot 機能拡張オプションの要件」で指定されている要件
Visual Studio Code
Node.js 18、20、または 22
Microsoft 365 Agents Toolkit (Teams Toolkit の進化)

プロジェクトを作成する

まず、基本的な宣言型エージェントを作成します。

Visual Studio Code を開きます。
アクティビティバーで [Microsoft 365 Agents Toolkit ] を選択します。
[ Create a New Agent/App]\(新しいエージェント/アプリの作成\) を選択します。
[ 宣言型エージェント] を選択します。
[ アクションなし ] を選択して、基本的な宣言型エージェントを作成します。
[ ワークスペースフォルダー] ボックスの一覧で、[ 既定のフォルダー ] を選択してプロジェクトのルートフォルダーを既定の場所に格納するか、新しいエージェントプロジェクトを配置するフォルダーを参照します。
アプリケーション名として「Excel Agent」と入力し、Enter キーを押します。
プロジェクトが新しい Visual Studio Code ウィンドウで開きます。元の Visual Studio Code ウィンドウを閉じます。

マニフェストを構成する

次の手順では、マニフェストを構成します。

appPackage フォルダー内のmanifest.json ファイルを開きます。
マニフェストスキーマのプレビューバージョンを使用する必要があるため、 $schema プロパティと manifestVersion プロパティを次に置き換えます。
```
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
"manifestVersion": "devPreview",
```
マニフェストのルートに、次の承認プロパティを追加します。このプロパティは、Office ドキュメントの読み取りと書き込みのアクセス許可をエージェントに付与します。
```
"authorization": {
  "permissions": {
    "resourceSpecific": [
      {
        "name": "Document.ReadWrite.User",
        "type": "Delegated"
      }
    ]
  }
}
```
マニフェストのルートに、次の extensions プロパティを追加します。このコードについては、次の点に注意してください。
- requirements.scopes プロパティを使用すると、エージェントは Excel でのみ使用でき、他の Office アプリケーションでは使用できません。
- runtimesのオブジェクトは、エージェントが呼び出す Office JavaScript ライブラリ API を実行するために Office が使用する JavaScript ランタイムを構成します。
- code.script プロパティは、Office JavaScript ライブラリ API を呼び出す関数を含む JavaScript ファイルの URL を指定します。この同じファイルには、 Office.actions.associate メソッドの呼び出しが含まれているので、関数をアクション ID にマップします。このファイルは、後の手順で作成します。
- code.page プロパティは、code.page プロパティで参照されているファイルを読み込む埋め込み<script> タグを含む Web ページの URL を指定します。このファイルは、後の手順で作成します。
- ランタイムオブジェクトには、アクションオブジェクトを含む actions 配列が含まれています
- actions.id プロパティの値は、associateの呼び出しに渡されるのと同じアクション ID です。
- actions.type プロパティは executeDataFunction に設定されます。これは、Copilot によって呼び出されたときにパラメーターを受け取ることができる型です。
```
"extensions": [
  {
    "requirements": {
      "scopes": [
        "workbook"
      ]
    },
    "runtimes": [
      {
        "id": "ContosoAgentRuntime",
        "type": "general",
        "code": {
          "page": "https://localhost:3000/commands.html",
          "script": "https://localhost:3000/commands.js"
        },
        "lifetime": "short",
        "actions": [
          {
            "id": "FillColor",
            "type": "executeDataFunction"
          }
        ]
      }
    ]
  }
]
```

マニフェスト JSON のリファレンスドキュメントは、 Microsoft 365 アプリマニフェストスキーマリファレンスにあります。

宣言型エージェントを構成する

appPackage フォルダー内のファイル declarativeAgent.jsonを開きます。

その内容を次のコードに置き換えます。この JSON について、次の点に注意してください。

このファイルの actions.id プロパティは、 actions.fileで指定されたファイル内のすべての関数の集合 ID です。通常、マニフェスト内の extensions.runtimes.actions.id (特定のアクションの ID) と一致させるべきではありません。
actions.file プロパティで指定するファイルは、後の次の手順で作成します。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
  "version": "v1.4",
  "name": "Excel 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": "ExcelActions",
      "file": "Office-API-local-plugin.json"
    }
  ]
}

宣言型エージェントのリファレンスドキュメントは、Microsoft 365 Copilotの宣言型エージェントスキーマ 1.4 にあります。

プラグインを構成する

appPackage フォルダーにファイルを作成し、declarativeAgent.json ファイルのactions.file プロパティに割り当てられた名前をOffice-API-local-plugin.json。

次の内容をファイルに貼り付けます。この JSON について、次の詳細に注意してください。

API プラグイン構成ファイルは、JavaScript 関数ではなく、エージェントアクションの意味でプラグインの関数を指定します。各アクションの手順が含まれています。また、Copilot のランタイムも構成します。 (前の手順でマニフェストで Office のランタイムを構成しました)。
functions.nameは、アドインマニフェストの extensions.runtimes.actions.id プロパティ (FillColor) と一致する必要があります。
runtimes.run_for_functions配列には、functions.nameと同じ文字列か、それに一致するワイルドカード文字列を含める必要があります。
runtimes.spec.local_endpoint プロパティは、FillColor文字列に関連付けられている JavaScript 関数が、一部の REST エンドポイントではなく Office JavaScript ライブラリで使用できるように指定します。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
  "schema_version": "v2.3",
  "name_for_human": "Excel Agent",
  "description_for_human": "Excel actions in agent",
  "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"
      },
      "run_for_functions": [
        "FillColor"
      ]
    }
  ]
}

API プラグインのリファレンスドキュメントは、Microsoft 365 Copilotの API プラグインマニフェストスキーマ 2.3 にあります。

JavaScript 関数を作成する

プロジェクトのルートで 、src という名前のフォルダーを作成し、その下にコマンドという名前のサブフォルダーを作成 します。
コマンド フォルダーで、commands.ts という名前のファイルを作成し、次の内容を指定します。このコードに関する次の詳細に注意してください。
- fillColor関数は、指定したセルの背景色を指定した色に設定します。これは、後の手順で作成したファイルによって JavaScript ランタイムに読み込まれる Office JavaScript ライブラリからオブジェクトとメソッドを呼び出します。
- associate メソッドの最初のパラメーターは、マニフェストの extensions.runtimes.actions.id プロパティと API プラグイン JSON の functions.name プロパティの両方と完全に一致する必要があります。
- message パラメーターは、Copilot ランタイムによって Office の JavaScript ランタイムに渡されるオブジェクトです。これは、"セル C4 を緑に設定する" など、自然言語プロンプトで指定されたユーザーとしてのセルアドレスと色パラメーターを含むオブジェクトです。
```
async function fillColor(cell, color) {
  // @ts-ignore
  await Excel.run(async (context) => {
    context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
    await context.sync();
  })
}
// @ts-ignore
Office.onReady((info) => {
  // @ts-ignore
  Office.actions.associate("FillColor", async (message) => {
    const { Cell: cell, Color: color } = JSON.parse(message);
    await fillColor(cell, color);
    return "Cell color changed.";
  })
});
```
コマンド フォルダーで、commands.htmlという名前のファイルを作成し、次の内容を指定します。このファイルは、Office が Copilot API プラグインに使用するランタイムの種類に JavaScript ファイルを直接読み込めないため、必要です。代わりに、 <script> 要素を持つ HTML ファイルによって JavaScript が読み込まれます。このファイルに関する次の詳細に注意してください。
- ファイルの唯一の目的は他のファイルを読み込むため、 <body> 要素は空です。ファイルには UI がなく、ユーザーには表示されません。
- これは、Office JavaScript ライブラリである office.jsファイルを Microsoft サーバーから読み込みます。
- この<script>要素はビルド時に後の手順で追加したファイルによってビルド時に追加されるため、commands.js ファイルを読み込む<script>要素がありません (作成したcommands.tsからトランスパイルされます)。
- プロジェクトがビルドされ、サーバー上で提供される場合、この HTML ファイルの URL はマニフェストの extensions.runtimes.code.page プロパティの値と一致します。この記事の「マニフェストを構成する」を参照してください。
```
<html>

<head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />

    
    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
</head>

<body>
</body>

</html>
```

プロジェクト構成ファイルをコピーする

Office では、Office アドインのインフラストラクチャを使用して、Office JavaScript ライブラリの API プラグインを実行します。ローカルの Office API プラグインの初期プレビュー期間中は、この種類のプロジェクト用のエージェントツールキットテンプレートはありません。このため、Office アドインの開発にエージェントツールキットによって使用される一部のファイルをプロジェクトに追加する必要があります。これらのファイルを生成する最も速い方法は、アドインプロジェクトを作成し、必要なファイルをアドインプロジェクトからこのエージェントプロジェクトにコピーしてから、いくつかの簡単な編集を行う方法です。

新しい Visual Studio Code ウィンドウを開きます。
アクティビティバーで [Microsoft 365 Agents Toolkit ] を選択します。
[ Create a New Agent/App]\(新しいエージェント/アプリの作成\) を選択します。
[ Office アドイン] を選択します。
[作業ウィンドウ] を選択します。
[ ワークスペースフォルダー] ボックスの一覧で、[ 既定のフォルダー ] を選択してプロジェクトのルートフォルダーを既定の場所に格納するか、新しいエージェントプロジェクトを配置するフォルダーを参照します。
アプリケーション名として任意の文字列を入力し、Enter キーを押します。
プロジェクトが新しい Visual Studio Code ウィンドウで開きます。新しい Visual Studio Code ウィンドウと、プロジェクトを作成したウィンドウの両方を閉じます。
作成したアドインプロジェクトのルートから、API プラグインプロジェクトのルートに次のファイルをコピーします。ファイルをコピーしたら、アドインプロジェクトフォルダーを削除します。
- babel.config.json
- package.json
- tsconfig.json
- webpack.config.js
注:

これらのファイルの内容の一部は、API プラグインプロジェクトに必要ありません。このセクションの残りの手順では、プラグインがサイドロードされて適切に実行されるようにするために必要な、これらのファイルに最小限の変更のみを加えます。 Office JavaScript ライブラリ API を呼び出すプラグイン用のエージェントツールキットプロジェクトテンプレートの開発に取り組んでいます。
Visual Studio Code で、 webpack.config.js ファイルを開きます。
entry オブジェクトの定義を見つけて、そのオブジェクトから taskpane プロパティを削除します。完了すると、 entry プロパティは次のようになります。
```
entry: {
  polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
  commands: "./src/commands/commands.ts",
},
```

plugins配列の定義を見つけます。上部には、アドイン作業ウィンドウの new HtmlWebpackPlugin の呼び出しがあります。 new HtmlWebpackPluginのこの呼び出しを削除します。完了すると、 plugins 配列全体が次のようになります。

plugins: [
  new CopyWebpackPlugin({
    patterns: [
      {
        from: "appPackage/assets/*",
        to: "assets/[name][ext][query]",
      },
      {
        from: "appPackage/manifest*.json",
        to: "[name]" + "[ext]",
        transform(content) {
          if (dev) {
            return content;
          } else {
            return content.toString().replace(new RegExp(urlDev, "g"), urlProd);
          }
        },
      },
    ],
  }),
  new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"],
  }),
],

appPackage フォルダーには、2 つのイメージファイルがあります。color.png と outline.png。アドインツールインフラストラクチャを使用するには、これらのファイルを移動する必要があります。 appPackage フォルダーに assets という名前のサブフォルダーを作成し、2 つのファイルをそのフォルダーに移動します。
manifest.jsonを開き、colorプロパティとoutlineプロパティの値を新しい場所に合わせて変更します。完了すると、 icons プロパティは次のようになります。
```
"icons": {
    "outline": "assets/outline.png",
    "color": "assets/color.png"
},
```

エージェントとプラグインをテストする

コマンドラインインターフェイス (CLI) で、API プラグインプロジェクトのルートに移動し、 npm installを実行します。インストールが完了するまで待ちます。
すべての Office アプリケーションを閉じます。
Visual Studio Code で、アクティビティバーで [Microsoft 365 Agents Toolkit ] を選択し、[ アカウント ] ウィンドウで、Copilot とカスタムアプリのアップロードのサポートが有効になっている Microsoft 365 アカウントにログインしていることを確認します。
[ライフサイクル] ウィンドウで [プロビジョニング] を選択します。

特に、プロビジョニングでは、パッケージ zip ファイルを含む appPackage フォルダー内にビルド フォルダーが作成されます。ファイルには、エージェントとプラグインのマニフェストファイルと JSON ファイルが含まれています。
プロジェクトのルートにある CLI で、 npm run dev-server を実行して localhost でサーバーを起動します。

注:

古い証明書を削除したり、新しい証明書をインストールしたりするように求められた場合は、両方のプロンプトに同意します。

次の例のように、アプリが正常にコンパイルされたことを示す行がサーバーウィンドウに表示されるまで待ちます。この出力は、サーバーが実行され、ファイルにサービスを提供されていることを意味します。
```
webpack 5.99.8 compiled successfully in 1090 ms
```
テストの最初の手順は、プラットフォームによって異なります。
- Windows 上の Office でテストするには、Excel を開き、ブックを開く (または作成) します。
- Office on the webでテストするには、ブラウザーで [https://excel.cloud.microsoft] に移動し、ブックを開く (または作成) します。
リボンから Copilot を開き、[ Copilot ] ウィンドウでハンバーガーコントロールを選択します。 Excel エージェントは、 エージェントの一覧に含まれている必要があります。 (すべてのエージェントが確実に一覧表示されるようにするには、[ 詳細を表示 ] を選択する必要がある場合があります)。エージェントが一覧に表示されない場合は、次のアクションのいずれかまたは両方を試してください。
- 数分待ってから Copilot を再読み込みします。
- Copilot を開いてエージェントの一覧を開き、[Copilot] ウィンドウにカーソルを置き、Ctrl+Rキーを押します。
[Excel エージェント] を選択し、[セルの色の会話の変更] スターターを選択し、ウィンドウの下部にある会話ボックスで [送信] コントロールを選択します。数秒で、次のような確認プロンプトが表示されます。
確認プロンプトに応答して [ 確認 ] を選択します。セルの色が変更されます。

ヒント

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

エージェントで変更を加えます

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

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

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