Copilot エージェントと Office アドインの組み合わせ (プレビュー)

2025-06-10

注:

この記事では、Copilot 宣言型エージェントについて理解していることを前提としています。そうでない場合は、次から始めます。

Office アドインにMicrosoft 365 Copilot エージェントを含めると、次の 2 つの利点があります。

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

Office アドインは、Copilot エージェントのスキルと考えることもできます。 Office アドインは Office JavaScript ライブラリを使用して Office ドキュメントに対して読み取り操作と書き込み操作を実行するため、これらの操作は Copilot エージェントのアクションになります。

シナリオ

Copilot エージェントを追加すると、ユーザーにアドインの価値が向上する選択された方法を次に示します。

アドインの使用方法を学習する: ユーザーが目標を達成するためにアドインで複数の手順またはタスクを実行する必要がある場合、Copilot のチャットインターフェイスを使用すると、アドインの使用を開始するプロセスを容易にすることができます。たとえば、準備する各リースについて回答する必要がある質問の一覧が必要な法律事務所を考えてみましょう。この質問の一覧を作成すると、時間がかかり、労働集約的になる場合があります。ただし、Office JavaScript ライブラリを使用する Copilot エージェントは、質問の最初の下書きリストを作成し、それらをWordドキュメントに挿入するように求めることができます。
コンテンツ分析: エージェントを使用して、ドキュメントまたはスプレッドシートのコンテンツを分析し、見つけた内容に応じてアクションを実行できます。次に例を示します。
- エージェントは提案の要求を分析し、バックエンドシステムから RFP の質問に対する回答をフェッチします。ユーザーは、エージェントに対して「質問に関する既知の回答を入力する」よう求めるメッセージを表示するだけです。
- エージェントは、ドキュメント自体または顧客のビジネスシステムの他の場所で、特定のアクションを実行する必要があることを意味するコンテンツについて、ドキュメントまたはスプレッドシート内のテーブルを分析します。ユーザーは、"監査リストで見逃した項目がないかドキュメントを確認してください" と言う場合があります。
信頼できるデータの挿入: 一般的な AI エンジンに質問を求める場合は、見つけた情報を組み合わせて回答を作成します。誤りを発生する可能性のあるプロセス。ただし、アドインに基づく Copilot エージェントは、信頼されたソースから 変更せずに データを挿入できます。次にいくつか例を示します。
- 編集できるWordへの法的調査の挿入を可能にするアドインを検討してください。ユーザーはエージェントに「どのような状況でインディアナ州の住宅空間のリースが賃貸人によって一方的に壊れる可能性があるか」と求めます。その後、アドインは、前例と法令からコンテンツを変更せずにフェッチします。
- デジタル資産のインベントリを管理するアドインについて考えてみましょう。 Copilot エージェントチャットで、ユーザーは "それぞれの名前、ダウンロードされた回数、およびサイズ (MB 単位) を含む色の写真の表を挿入し、ほとんどのダウンロード順に並べ替える」を求めます。その後、アドインはレコードシステムからこのデータを変更せずにフェッチし、テーブルを Excel スプレッドシートに挿入します。

Copilot エージェントとアドインフレームワークの関係

Copilot エージェントは、アドインの自然言語インターフェイスです。

アドインは、Copilot エージェントのスキル のみに 構成できます。作業ウィンドウ、カスタムリボンボタン、またはカスタムメニューを含める必要はありません。しかし、それはCopilotスキルであることに加えて、これらののいずれかを持つことができます。最適な方法は、アドインで有効にする必要があるユーザーシナリオによって異なります。

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

注:

現時点では、Excel、PowerPoint、Word アドインのみを Copilot のスキルとして構成できます。 Outlook のサポートに取り組んでいます。
Copilot エージェントは現在、Office on Mac ではサポートされていません。
アドインでは、 Microsoft 365 の統合マニフェストを使用して Copilot のスキルとして構成する必要があります。
コンテンツアドインを Copilot のスキルにすることはできません。

主なタスク

アドインを Copilot スキルとして構成するには、2 つの主要なタスクがあり、アドインの関数コマンドを構成するための 2 つのタスクに似ています。

エージェントのアクションを実装する JavaScript 関数を作成します。
JSON を使用して Office と JavaScript ランタイムにこれらの関数の名前を指定します。

JSON 構成

Copilot スキルへのアドインの構成には、次のサブセクションで説明されている 3 つの JSON 形式のファイルが必要です。

Microsoft 365 の統合マニフェスト

マニフェストには、構成する 2 つの部分があります。まず、アクションによって呼び出される JavaScript 関数を識別するアクションオブジェクトを作成します。次の例を示します (余分なマークアップが省略されています)。このコードについては、次の点に注意してください。

"page" プロパティは、関数が定義されている JavaScript ファイルの URL を指定する埋め込みスクリプトタグを含む Web ページの URL を指定します。この同じファイルには、 Office.actions.associate メソッドの呼び出しが含まれているので、関数をアクション ID にマップします。
マニフェストの "actions.id" プロパティは、 associate の呼び出しに渡されるのと同じアクション ID です。
"actions.type" プロパティは、パラメーターを受け取ることができ、Copilot によって呼び出すことができる型である "executeDataFunction" に設定されます。

"extensions": [

    ...

    "runtimes": [
        {
            "id": "CommandsRuntime",
            "type": "general",
            "code": {
                "page": "https://localhost:3000/commands.html"
            },
            "lifetime": "short",
            "actions": [
                {
                    "id": "fillcolor",
                    "type": "executeDataFunction",
                }
            ]
        }
    ]
]

次に、エージェントの詳細な構成を含むファイルを識別する宣言型エージェントオブジェクトを作成します。次に例を示します。

"copilotAgents": {
    "declarativeAgents": [
        {
        "id": "ContosoCopilotAgent",
        "file": "declarativeAgent.json"
        }
    ]
}

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

宣言型エージェントの構成

エージェント構成ファイルにはエージェントの指示が含まれており、エージェントのアクションの詳細な構成を含む 1 つ以上の API プラグイン構成ファイルを指定します。次に例を示します。この JSON については、次の点に注意してください。

会話スターターが Copilot のチャットキャンバスに表示されます。
このファイルの "actions.id" プロパティは、 "actions.file"で指定されたファイル内のすべての関数の集合 ID です。マニフェスト内の "actions.id" と一致する必要はありません。

{
    "$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"
        }
    ]
}

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

Copilot API プラグインの構成

API プラグイン構成ファイルは、アクションの指示を含め、JavaScript 関数ではなく、エージェントアクションの意味でプラグインの "関数" を指定します。また、Copilot 用の JavaScript ランタイムも構成します。次に例を示します。この JSON について、次の点に注意してください。

"functions.name"は、アドインマニフェストの "extensions.runtimes.actions.id" プロパティと一致する必要があります。
"reasoning.description"と"reasoning.instructions"は、REST API ではなく JavaScript 関数を参照します。
"responding.instructions" プロパティは、応答方法に関する Copilot へのガイダンスのみを提供します。応答に制限や構造要件は設定されません。
"runtimes.run_for_functions"配列には、"functions.name"と同じ文字列か、それに一致するワイルドカード文字列を含める必要があります。
"runtimes.spec.local_endpoint" プロパティは新しく、API プラグインスキーマのメインリファレンスドキュメントにはまだ記載されていません。詳細については、以下を参照してください。この場合、"fillcolor" 文字列に関連付けられている JavaScript 関数が、一部の REST エンドポイントではなく Office アドインで使用できるように指定します。 -"runtimes.spec.allowed_host" プロパティは新しく、API プラグインスキーマのメインリファレンスドキュメントにはまだ含まれません。詳細については、以下を参照してください。この場合、エージェントは Excel でのみ表示されるように指定します。

{
    "$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 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"]
        }
    ]
}

API プラグインのリファレンスドキュメントは、Microsoft 365 Copilotの API プラグインマニフェストスキーマ 2.3 にあります。 "runtimes.spec" プロパティの 2 つの新しいプロパティのドキュメントを次に示します。

プロパティ	型	説明
`local_endpoint`	String	省略可能。使用可能な JavaScript 関数のセットの ID。このプロパティは、 `"runtimes.spec.url"` プロパティとほぼ同じですが、REST API ではなく、クライアント上のローカル関数の場合です。現在、使用できる値は "Microsoft.Office.Addin" のみです。
`allowed_host`	String	省略可能。エージェントをホストできる Office アプリケーション Copilots を指定します。指定できる値は、"document"、"mail"、"presentation"、および "workbook" です。

JavaScript 関数を作成する

Copilot エージェントによって呼び出される JavaScript 関数は、関数コマンドの作成とまったく同じように作成されます。次に例を示します。このコードについては、次の点に注意してください。

関数コマンドとは異なり、Copilot アクションに関連付けられている関数はパラメーターを受け取ることができます。
associate メソッドの最初のパラメーターは、アドインマニフェストの "extensions.runtimes.actions.id" プロパティと API プラグインの JSON の "functions.name" プロパティの両方と一致する必要があります。

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, color} = JSON.parse(message);
        await fillColor(cell, color);
        return "Cell color changed.";
    });
});

関数が作成されたら、関数を使用して JavaScript ファイルを読み込む <script> タグを含む UI レス HTML ファイルを作成します。この HTML ファイルの URL は、マニフェスト内の "extensions.runtimes.code.page" プロパティの値と一致している必要があります。この記事の「 Microsoft 365 の統合マニフェスト」を参照してください。

エージェントとアドインの組み合わせのトラブルシューティング

一般的な問題と推奨される解決策を次に示します。

エージェントアクションが失敗し、アドインでアクションが見つからなかったことを示すメッセージが表示されます。考えられる原因を次に示します。
- プラグインの JSON の "functions.name" プロパティ値が、アドインマニフェストの"extensions.runtimes.actions.id" プロパティと完全に一致しません。
- マニフェストには一致する "actions.id" がありますが、同じアクションオブジェクトの兄弟 "actions.type" 値は "executeDataFunction" ではありません。
エージェントアクションが失敗し、アクションハンドラーの登録が見つからなかったことを示すメッセージが表示されます。考えられる原因は次のとおりです。
- アドインの JavaScript には、プラグインの JSON 内の "functions.name" プロパティ値と完全に一致する最初のパラメーターを使用したOffice.actions.associateの呼び出しはありません。