Copilot エージェントは Microsoft 365 のアプリです

[アーティクル]
10/03/2024

重要

API プラグインは現在、宣言型エージェント内のアクションとしてのみサポートされています。 Microsoft 365 Copilotでは有効になっていません。 API プラグインを宣言型エージェントに追加する方法を示す例については、「プラグインの追加」を参照してください。
この機能は、すべてのMicrosoft 365 Copilotライセンステナントで既定で有効になっています。管理者は、ユーザーとグループごとにこの機能を無効にし、個々のプラグインの使用を承認する方法と、有効にするプラグインを制御できます。詳細については、「統合アプリでの Copilot エージェントの管理」を参照してください。

Copilot エージェントを構築するときは、Microsoft 365 用のアプリもビルドします。 Microsoft 365 用アプリは、共通のマニフェストスキーマとパッケージ形式、および統合された配布と管理のプロセスとツールを共有します。最終的な結果として、アプリと Copilot エージェントは、可能な限り最も広い対象ユーザーに到達し、ユーザーのワークフロー内でコンテキストに応じて表示されます。

この記事では、Copilot エージェント開発用の Microsoft 365 アプリモデルの重要な部分について説明します。

Microsoft 365 のアプリモデル

Microsoft 365 エコシステムは統合アプリプラットフォームに進化しており、共通のアプリモデルを使用してアプリを定義してパッケージ化できます。他の Microsoft 365 アプリケーションで実行するように Teams アプリを拡張する方法として始まった機能は、Microsoft Graph コネクタ、Outlook アドイン、および今では Copilot エージェントの配布をサポートするように拡張されました。

アプリパッケージ

Copilot エージェントを含む Microsoft 365 のアプリパッケージは、1 つ以上の構成 (マニフェスト) ファイルとアプリアイコンを含む zip ファイルです。アプリロジックとデータストレージは他の場所でホストされ、HTTPS 経由で Microsoft 365 ホストアプリケーションによってアクセスされます。アプリパッケージを管理者に送信して、organizationに発行するか、パートナーセンターに送信して Microsoft AppSource に発行します。

少なくとも、アプリパッケージには次のものが含まれます。

アプリの構成、機能、必要なリソース、および重要な属性について説明するアプリマニフェスト (manifest.json)。
大きな色のアイコン (color.png)、Microsoft Copilot UI とストアにエージェントを表示するフルカラー 92x92 アイコン、および
小さなアウトラインアイコン (outline.png)、背景が透明な 32 x 32 アイコン (現時点では Copilot では使用されていませんが、検証に合格するために必要)

アプリパッケージには、宣言型エージェントと API プラグインの定義のほか、サポートされている他の言語用のローカライズファイルも含めることができます。

Microsoft 365 アプリパッケージの構造を示す図: アプリマニフェスト (.json ファイル) + .zip ファイルにラップされたアイコン (色とアウトライン .png ファイル)

アプリのアイコン

アプリパッケージには、.png ファイルとして、アプリアイコンの色バージョンとアウトラインバージョンの両方を含める必要があります。これらのアイコンには、ストアの検証に合格するための特定のサイズ要件があります。

注:

現時点では、Copilot エージェントをエンドユーザーに表すために色アイコンのみが使用されますが (ストア登録情報とMicrosoft 365 Copilot UI 内の両方)、Microsoft AppSource にアプリパッケージを送信する場合はアウトラインアイコンが必要です。

Microsoft 365 アプリパッケージの色アイコンとアウトラインアイコン、 Teams ストアとアプリバーのアプリアイコンに関する詳細な設計ガイダンス。

カラーアイコン

色アイコンは、Microsoft Copilot UI と製品内 (Teams、Outlook、Microsoft 365) アプリストア内のエージェントを表します。

色アイコン:

任意の色を指定できます
合計 192 x 192 ピクセルにする必要があります
シンボル自体には 96 x 96 ピクセルにする必要があります ( トリミングされたホストシナリオで 48 ピクセルのパディングを許可する)
完全に固体または完全に透明な正方形の背景の上に座る必要があります

アウトラインアイコン

アウトラインアイコンは、Teams アプリバーでピン留めされたアプリやアクティブなアプリを表すために使用されます。現時点では Copilot エージェントには使用されていませんが、アプリパッケージが検証に合格するためには引き続き必要です。

アウトラインアイコン:

32 x 32 ピクセルにする必要があります
透明な背景を持つ白、または白い背景で透明にする必要があります
シンボルの周囲に追加のパディングを含めることはできません

アプリマニフェスト

Microsoft 365 のアプリマニフェストは、アプリの機能と特性を記述する JSON ファイルです。その中核となる Microsoft 365 のアプリマニフェストは、Teams アプリをビルドするためのスキーマですが、その後 (バージョン 1.13 以降) に拡張され、Teams に加えて Microsoft 365 ホスト全体で実行されるアプリを定義しています。

Microsoft Copilot Studioを使用して宣言型エージェントを構築している場合は、作成プロセス中に指定した情報に基づいてアプリマニフェストが自動的に生成されます。

すべてのアプリマニフェストには、次の情報が含まれている必要があります。

マニフェストフィールド	説明
version	MAJOR 形式のアプリのバージョン番号。マイナー。PATCH (semver 標準)。
id	MICROSOFT アプリケーション登録ポータル (apps.dev.microsoft.com) から GUID 形式でこのアプリの一意に生成された識別子。
ディベロッパー	名前、Web サイト、プライバシーポリシーと利用規約へのリンクなど、開発者に関する情報。 AppSource に送信されるアプリの場合、値はパートナーセンターアプリ申請フォームで指定された値と一致する必要があります。
name	アプリケーションホスト内のエンドユーザーに表示されるアプリの名前。
description	ユーザー向けのアプリの短い説明と長い説明。 AppSource に送信されるアプリの場合、これらの値は AppSource エントリの情報と一致する必要があります。
アイコン	カラーアイコンファイルとアウトラインアイコンファイルへの相対パス。
accentColor	アウトラインアイコンの背景としてとを使用する色 ( RGB 16 進値など `#4464ee`)。
特定のアプリ機能の定義	個人用タブ (staticTabs)、メッセージ拡張機能 (composeExtensions)、ボットなど、各アプリ機能の定義。宣言型エージェントと API プラグインは、 copilotAgents ノードの下で定義されます。

次の例は、メッセージ拡張機能と宣言型エージェントアプリ機能の最後にプレースホルダーセクションがあるアプリマニフェストを示しています。

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.18/MicrosoftTeams.schema.json",
    "manifestVersion": "1.18",
    "version": "1.0.0",
    "id": "00000000-0000-0000-0000-000000000000",
    "developer": {
        "name": "Northwind Traders",
        "websiteUrl": "https://www.example.com",
        "privacyUrl": "https://www.example.com/termofuse",
        "termsOfUseUrl": "https://www.example.com/privacy"
    },
    "icons": {
        "color": "Northwind-Logo-196.png",
        "outline": "Northwind-Logo-32.png"
    },
    "name": {
        "short": "Northwind Inventory",
        "full": "Northwind Inventory App"
    },
    "description": {
        "short": "App allows you to find and update product inventory information",
        "full": "Northwind Inventory is the ultimate tool for managing your product inventory. With its intuitive interface and powerful features, you'll be able to easily find your products by name, category, inventory status, and supplier city. You can also update inventory information with the app."
    },
    "accentColor": "#3690E9",
    "composeExtensions": {
        ...
    },
    "copilotAgents": {
        ...
    }
}

詳細については、「開発者プレビューアプリマニフェストスキーマリファレンス」を参照してください。

`copilotAgents` 定義

宣言型エージェントと API プラグインにはそれぞれ独自の定義スキーマがあります。宣言型エージェントの定義ファイルは、アプリマニフェストの copilotAgents オブジェクトから参照されます。

次の例は、宣言型エージェントを参照する方法を示しています。

    "copilotAgents": {
        "declarativeAgents": [
            {
                "id": "agent1",
                "file": "declarativeAgent1.json"
            }
        ]
    },

API プラグインの定義は、宣言型エージェント定義から参照されます。

宣言型エージェントマニフェストと API プラグインマニフェストを参照するアプリマニフェストを示す図。宣言型エージェントマニフェストは、別の API プラグインマニフェストを参照します

以下のことに注意してください。

現在、アプリマニフェストごとにサポートされている宣言型エージェント定義は 1 つだけです。宣言型エージェントごとにサポートされる API プラグインは 1 つだけです。
Copilot Studioを使用して Copilot エージェントをビルドすると、アプリマニフェストの生成全体の一部として、それぞれに固有idのが生成されます。 Teams Toolkit または独自の IDE を使用してエージェントを構築する場合は、独自の id 規則またはフレンドリ名に従って自分を割り当てます。

宣言型エージェントマニフェスト

宣言型エージェントマニフェストには、Copilot 応答の指示、会話の開始サンプルプロンプト、接地に使用されるデータソース、およびエージェントが実行できるアクションの一覧 (API プラグインスキル) が含まれています。

詳細については、「Microsoft 365 Copilotの宣言型エージェントマニフェストスキーマ」を参照してください。

API プラグインマニフェスト

API プラグインマニフェストには、サポートされている API や実行できる操作など、プラグインの機能が記述されています。また、名前、説明、バージョン、対話する REST API の OpenAPI 定義への参照などのメタデータも含まれます。 API プラグインは、宣言型エージェントマニフェストから参照して、宣言型エージェントエクスペリエンス内で使用できます。

詳細については、Microsoft 365 Copilotの API プラグインマニフェストスキーマに関するページを参照してください。

エージェントのローカライズ

Copilot エージェントをローカライズする方法は、アプリマニフェストで他の機能 (タブ、ボット、メッセージ拡張機能など) をローカライズする方法とは若干異なります。

従来の Teams アプリ機能と Copilot エージェントの両方に同じローカライズファイル (言語ごと) を使用します。ただし、他のすべてのアプリマニフェストフィールドは、言語ファイルの JSONPath 式を使用して参照されますが、Copilot エージェント関連のフィールドはディクショナリキーを使用して参照されます。アプリマニフェスト自体で既定の言語文字列を使用する従来の Teams アプリ機能とは異なり、ローカライズされた Copilot エージェントには、既定の言語と追加の言語ごとに言語ファイルが必要です。

Copilot エージェントをローカライズするためのアプリマニフェスト、宣言型エージェントマニフェスト、および言語ファイルの関係を示す図

次の手順では、Copilot エージェントの追加の言語 (既定を超える) をサポートする方法を示します。

1. トークン化されたキーを使用して Copilot エージェントマニフェストを更新する

ローカライズするフィールド値に対して、宣言型エージェントまたは API プラグインマニフェストをトークン化されたキー (二角かっこなど [[PLUGIN_NAME]]) で更新します。ローカライズキーは、この正規表現と大きく一致します。 ^[a-zA-Z_][a-zA-Z0-9_]*$

次の例は、名前と説明のトークン化された値を持つ宣言型エージェントマニフェストを示しています。

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

2. アプリマニフェストに追加 `localizationInfo` する

localizationInfo言語タグと、アプリパッケージ内でサポートされている各言語ファイルへの相対パスを使用して、セクションをアプリマニフェストに追加します。

Copilot エージェントで複数の言語がサポートされている場合は、サポートされているすべての言語 (既定の言語を含む) にスタンドアロン言語ファイルを指定する必要があります。

次の例は、アプリマニフェストのローカライズ情報セクションを示しています。

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

Copilot エージェントが追加の言語をサポートしていない場合、既定の言語文字列はアプリマニフェストファイル自体内で表されます。 (単一言語アプリパッケージでは、既定の言語に個別の言語ファイルは必要ありません)。

3. 追加言語ごとにローカライズファイルを作成する

前の手順のアプリマニフェストで指定したファイル名 ( defaultLanguageFile および file プロパティ) を使用して、トークン化されたキーの値を使用して、サポートされている言語ごとにローカライズファイルを作成します。

次の例は、 fr.jsonCopilot エージェントと個人用タブの両方にローカライズされた文字列を含む言語ファイルを示しています。

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

アプリマニフェストのローカライズ可能なフィールド

言語ファイルごとに、ローカライズする必要があるアプリのローカライズスキーマから次のプロパティを指定します。

マニフェストフィールド	説明	最大長	必須
`@schema`	ローカライズスキーマの URL。 Copilot エージェントの場合は、devPreview: を使用します `https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`。マニフェストスキーマのバージョンは、アプリマニフェストとローカライズファイルの両方で同じである必要があります。		✔️
`name.short`	アプリマニフェストの短い名前を指定された値に置き換えます。	30 文字	✔️
`name.full`	アプリマニフェストの完全な名前を指定された値に置き換えます	100 文字	✔️
`description.short`	アプリマニフェストの短い説明を指定された値に置き換えます。	80 文字	✔️
`description.full`	アプリマニフェストの完全な説明を指定された値に置き換えます。	4,000 文字	✔️
Copilot エージェントのローカライズされた文字列のキーと値のペア	Copilot エージェントの場合は、ローカライズされた値でトークン化されたキー (アプリ `manifest.json`で指定されているが、二重角かっこなし) を使用します。例: `"DA_Name": "Agent de Communications"`
他のアプリコンポーネントのローカライズされた文字列の JSONPath/値ペア	他のすべての (クラシック Teams) アプリコンポーネントの場合は、ローカライズされた値のキーとして JSONPath 式を使用します。例: `"staticTabs[0].name": "Accueil"`

詳細については、「アプリのローカライズ (Microsoft Teams)」と「ローカライズスキーマリファレンス」を参照してください。

宣言型エージェントマニフェストのローカライズ可能なフィールド

宣言型エージェントマニフェスト内では、次のフィールドをローカライズできます。

マニフェストフィールド	説明	最大長	必須
`name`	宣言型エージェントの名前。空白以外の文字を少なくとも 1 つ含む必要があります。	100 文字	✔️
`description`	宣言型エージェントの説明。空白以外の文字を少なくとも 1 つ含む必要があります。	1,000 文字	✔️
`conversation_starters`	宣言型エージェントが回答できる質問の例のリスト (配列)。各例は、と `text`の両方がローカライズ可能なオブジェクト`title`によって表されます。	配列内の 6 つのオブジェクト

詳細については、「宣言型エージェントマニフェストリファレンス」を参照してください。

API プラグインマニフェストのローカライズ可能なフィールド

API プラグインマニフェスト内では、次のフィールドをローカライズできます。

マニフェストフィールド	説明	最大長	必須
`name_for_human`	プラグインの人間が判読できる短い名前。空白以外の文字を少なくとも 1 つ含む必要があります。	20 文字	✔️
`description_for_model`	モデルに提供されるプラグインの説明(プラグインの目的、その機能が関連する状況など)。	2,048 文字
`description_for_human`	プラグインの人間が判読できる説明。	100 文字	✔️
`logo_url`	オーケストレーターが使用できるロゴを取得するために使用される URL。
`legal_info_url`	プラグインのサービス条件を含むドキュメントを検索する絶対 URL。
`privacy_policy_url`	プラグインのプライバシーポリシーを含むドキュメントを検索する絶対 URL。

詳細については、「 API プラグインマニフェストリファレンス」を参照してください。

次の方法で共有

Copilot エージェントは Microsoft 365 のアプリです

Microsoft 365 のアプリモデル

アプリパッケージ

アプリのアイコン

カラーアイコン

アウトラインアイコン

アプリマニフェスト

`copilotAgents` 定義

宣言型エージェントマニフェスト

API プラグインマニフェスト

エージェントのローカライズ

1. トークン化されたキーを使用して Copilot エージェントマニフェストを更新する

2. アプリマニフェストに追加 `localizationInfo` する

3. 追加言語ごとにローカライズファイルを作成する

アプリマニフェストのローカライズ可能なフィールド

宣言型エージェントマニフェストのローカライズ可能なフィールド

API プラグインマニフェストのローカライズ可能なフィールド

関連項目

フィードバック

その他のリソース

次の方法で共有

Copilot エージェントは Microsoft 365 のアプリです

Microsoft 365 のアプリ モデル

アプリ パッケージ

アプリのアイコン

カラー アイコン

アウトライン アイコン

アプリ マニフェスト

copilotAgents 定義

宣言型エージェント マニフェスト

API プラグイン マニフェスト

エージェントのローカライズ

1. トークン化されたキーを使用して Copilot エージェント マニフェストを更新する

2. アプリ マニフェストに追加 localizationInfo する

3. 追加言語ごとにローカライズ ファイルを作成する

アプリ マニフェストのローカライズ可能なフィールド

宣言型エージェント マニフェストのローカライズ可能なフィールド

API プラグイン マニフェストのローカライズ可能なフィールド

関連項目

フィードバック

その他のリソース

Microsoft 365 のアプリモデル

アプリパッケージ

カラーアイコン

アウトラインアイコン

アプリマニフェスト

`copilotAgents` 定義

宣言型エージェントマニフェスト

API プラグインマニフェスト

1. トークン化されたキーを使用して Copilot エージェントマニフェストを更新する

2. アプリマニフェストに追加 `localizationInfo` する

3. 追加言語ごとにローカライズファイルを作成する

アプリマニフェストのローカライズ可能なフィールド

宣言型エージェントマニフェストのローカライズ可能なフィールド

API プラグインマニフェストのローカライズ可能なフィールド