宣言型エージェントに対話型 UI ウィジェットを追加する

対話型 UI ウィジェットを宣言型エージェントに追加するには、 モデル コンテキスト プロトコル (MCP) サーバー ベースのアクション をエージェントに追加し、エージェントで使用される MCP ツールを拡張して UI を含めることができます。 Microsoft 365 Copilotでは、OpenAI Apps SDK を使用して作成された UI ウィジェットがサポートされます。

たとえば、MCP サーバー プラグインについては、GitHub でのMicrosoft 365 Copilotに関する MCP ベースの対話型 UI サンプルに関するページを参照してください。

OpenAI Apps SDK の機能がサポートされる詳細については、「 サポートされている機能」を参照してください。

前提条件

• 「Copilot 機能拡張オプションの要件」で指定されている要件
• UI ウィジェットを提供するリモート MCP サーバー、または UI ウィジェットを実装するように変更できる MCP サーバー
• MCP インスペクターなどの MCP サーバー応答を表示するツール
• Visual Studio Code
• Microsoft 365 Agents Toolkit バージョン 6.5.x 以降の最新のプレリリース バージョン

MCP サーバーの要件

• 認証 - OAuth 2.1 と Microsoft Entra シングル サインオン (SSO) がサポートされています。 開発目的で匿名認証がサポートされています。 認証の詳細については、「 エージェントで API プラグインの認証を構成する」を参照してください。
• 許可される URL - MCP サーバーと ID プロバイダーの両方で、次の URL を許可する必要があります。
  • CORS のウィジェット ホスト URL - Copilot は、MCP サーバー固有のホストの下にウィジェット UI をレンダリングします。 {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com。ここで、 {hashed-mcp-domain} は MCP サーバーのドメインの SHA-256 ハッシュです。 ウィジェット ホスト URL ジェネレーターを使用して、MCP サーバー URL に基づいてホスト URL を生成できます。
  • OAuth 2.1 リダイレクト URI:
    • https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect Copilot 用
    • https://vscode.dev/redirect エージェント ツールキットを使用してツールをフェッチする Visual Studio Code の場合
  • MICROSOFT ENTRA SSO リダイレクト URI:
    • https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect Copilot 用
    • Visual Studio Code では現在、ツールをフェッチするための SSO はサポートされていません
• UI ウィジェット - UI ウィジェットは、MCP アプリまたは OpenAI Apps SDK の要件に従って実装する必要があります。

ベスト プラクティス

UX 設計のベスト プラクティスの詳細については、「 宣言型エージェントでの対話型 UI ウィジェットのユーザー エクスペリエンス ガイドライン」を参照してください。

API の可用性を確認する

すべての window.openai.* API が、すべてのプラットフォームまたはホストで使用できるわけではありません。 サポートされていない API は undefined。 API の可用性を常にチェックし、API が使用できない場合はフォールバックを提供します。

例

この単純なパターンは、API を呼び出す前にチェックすることでランタイム エラーを回避します。

if (window.openai.callTool) {
  const result = await window.openai.callTool({ name: 'myTool', params: {} });
} else {
  // Handle unsupported case — show fallback UI, skip the feature, etc.
}

この例では、全画面表示モードに入るボタンは、ホストが requestDisplayMode API をサポートしている場合にのみレンダリングされます。

function FullScreenButton() {
  // Don't render the button if the host doesn't support it
  if (!window.openai.requestDisplayMode) {
    return null;
  }

  return (
    <button onClick={() => window.openai.requestDisplayMode({ mode: 'fullscreen' })}>
      Enter Fullscreen
    </button>
  );
}

または、ウィジェットが起動時に使用するすべての API の可用性をチェックし、それに応じて機能を有効または無効にすることができます。

interface PlatformCapabilities {
  canCallTools: boolean;
  canChangeDisplayMode: boolean;
  canSendMessages: boolean;
}

function detectCapabilities(): PlatformCapabilities {
  return {
    canCallTools: !!window.openai.callTool,
    canChangeDisplayMode: !!window.openai.requestDisplayMode,
    canSendMessages: !!window.openai.sendMessage,
  };
}

// Use at widget startup
const capabilities = detectCapabilities();

if (!capabilities.canCallTools) {
  // Show a reduced-functionality experience
}

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

1. Visual Studio Code を開き、左側のアクティビティ バーで [Microsoft 365 エージェント ツールキット ] アイコンを選択します。

2. [エージェント ツールキット] 作業ウィンドウで [ 新しいエージェント/アプリの作成 ] を選択します。

   

3. [ 宣言型エージェント] を選択します。

4. [ アクションの追加] を選択し、[ MCP サーバーで開始] を選択します。 メッセージが表示されたら、[ リモート MCP サーバー] を選択します。

5. MCP サーバーの URL を入力します。

6. エージェント プロジェクトの場所を選択します。

7. エージェントの名前を入力します。

これらの手順を完了すると、Agent Toolkit によってエージェントに必要なファイルが生成され、エージェント プロジェクトが読み込まれた新しい Visual Studio Code ウィンドウが開きます。

エージェントを更新してサイドロードする

1. .vscode/mcp.json ファイルを開きます。 ファイル エディターで [ スタート] ボタンを選択します。

2. ファイル エディターで [ ATK: Fetch action from MCP ] ボタンを選択し、[ ai-plugin.json] を選択します。

   

3. 使用するエージェントのツールを選択し、[ OK] を選択します。 UI ウィジェットを持つ少なくとも 1 つのツールを選択してください。

4. 該当する認証の種類を選択します。

   

   重要

   MCP サーバーが開発中で、認証を実装していない場合、この手順はスキップされます。 サーバーに認証を追加したら、マニフェストに認証を手動で追加する必要があります。

5. mcp-tools.jsonを開き、既存の値を MCP サーバーからのtools/list応答 JSON に置き換えます。 MCP Inspector などのテスト ツールを使用して、サーバーから応答を取得します。

   注:

   この手順は一時的なものです。 エージェント ツールキットは、今後この手順を不要にするために更新されます。

6. 左側のアクティビティ バーで [Microsoft 365 Agents Toolkit ] アイコンを選択します。

7. [ アカウント ] ウィンドウ で、[Microsoft 365 にサインイン] を選択します。 (既にサインインしている場合は、次の手順に進みます)。

8. Microsoft 365 アカウントの [ カスタム アプリアップロードが有効] と [ Copilot Access Enabled]\(有効\) の両方が表示されていることを確認します。 そうでない場合は、organization管理者とチェックします。詳細については、「Copilot 機能拡張オプションの要件」を参照してください。

9. [ ライフサイクル ] ウィンドウで、[ プロビジョニング] を選択します。

10. メッセージが表示されたら、認証の詳細を追加します。

11. プロビジョニングが完了したことをツールキットが報告するまで待ちます。

エージェントをテストする

1. ブラウザーを開き、https://m365.cloud.microsoft/chat に移動します。
2. 左側のサイドバーでエージェントを選択します。 エージェントが表示されない場合は、[すべてのエージェント] を選択 します。
3. MCP サーバーを呼び出す操作をエージェントに依頼します。
4. プロンプトが表示されたら、エージェントが MCP サーバーに接続できるようにします。
5. エージェントは UI ウィジェットをレンダリングします。

サポートされている機能

Microsoft 365 Copilotでは、次の機能がサポートされています。

コンポーネント ブリッジ

ツール記述子_meta フィールド

ツール記述子の注釈

コンポーネント リソースの_meta フィールド

CSP オブジェクトのプロパティ

ホスト提供のツールの結果_metaフィールド

クライアント提供の_meta フィールド

関連コンテンツ

• Microsoft 365 Copilot用の MCP サーバーからプラグインをビルドする
• 宣言型エージェントでの対話型 UI ウィジェットのユーザー エクスペリエンス ガイドライン
• OpenAI Apps SDK
• Microsoft 365 Copilot用の MCP ベースの対話型 UI サンプル