方法: コードアプリを Microsoft Copilot Studio エージェントに接続する

Microsoft Copilot Studio エージェントは、AI を利用した機能をコードアプリに提供します。この記事では、Microsoft Copilot Studio コネクタをコードアプリに追加し、エージェントを呼び出してユーザー入力を処理し、インテリジェントな応答を返す方法について説明します。

[前提条件]

初期化されたコードアプリのプロジェクト
環境内で公開されている Microsoft Copilot Studio エージェント
コードアプリをデータに接続する方法の基本的な理解

Microsoft Copilot Studio 接続があることを確認する

コードアプリを Copilot Studio エージェントに接続するには、環境内に Microsoft Copilot Studio 接続が必要です。既に存在するかどうかを確認するか、新しく作成します。

既存の接続を確認する

pac connection list コマンドを使用して Microsoft Copilot Studio 接続が既にあるかどうかを確認するには:

pac connection list

API ID /providers/Microsoft.PowerApps/apis/shared_microsoftcopilotstudioを使用して接続を探し、 connectionId 値をコピーします。

新しいつながりの作成

既存の接続がない場合は、Power Apps Maker ポータル UI を使用して接続を作成する必要があります。コードアプリをデータに接続し、connectionIdをコピーする方法の手順に従います。

Microsoft Copilot Studio コネクタを追加する

Microsoft Copilot Studio 接続を作成した後、PAC CLI pac code add-data-source コマンドを使用してコードアプリに追加します。

pac code add-data-source -a "shared_microsoftcopilotstudio" -c <connectionId>

このコマンドは自動的に次の操作を行います。

Copilot Studio データソースを使用して power.config.json ファイルを更新します
src/generated フォルダーに TypeScript モデルとサービスファイルを生成します

公開して、エージェント名を取得する

コードアプリからエージェントを呼び出すには、その前にエージェントを発行し、その名前を取得する必要があります。

エージェントを公開する

Copilot Studio でエージェントを開く
[ 発行] を選択してエージェントを発行する

エージェント名を取得する

Copilot Studio で、[チャネル] に移動 します。
[Web アプリ] を選択します。
接続文字列を表示して、エージェント名を見つけます。

URL の形式は

https://{id}.environment.api.powerplatform.com/copilotstudio/dataverse-backed/authenticated/bots/{agentName}/conversations?api-version=2022-03-01-preview

エージェント名の例:cr3e1_customerSupportAgent

ヒント

URL に表示されるとおりにエージェント名をコピーします。エージェント名では大文字と小文字が区別され、通常は発行者プレフィックスが含まれます。

Copilot Studio エージェントを呼び出す

コネクタが追加されたら、コードアプリから Copilot Studio エージェントを呼び出すことができます。次の手順では、生成されたサービスをインポートし、エージェントにメッセージを送信し、その応答を処理する方法を示します。

`ExecuteCopilotAsyncV2` アクションを使用する

ExecuteCopilotAsyncV2 アクションを使用して、コードアプリからエージェントを呼び出します。このアクションは、エージェントの応答を同期的に返します。これは、Microsoft Copilot Studio コネクタに含まれるエージェントの実行アクションと待機アクションです。

API パス:/proactivecopilot/executeAsyncV2

生成されたサービスをインポートする

データソースを追加した後、生成された TypeScript サービスをインポートします。

import { CopilotStudioService } from './generated/services/CopilotStudioService';

エージェントにメッセージを送信する

ExecuteCopilotAsyncV2 メソッドを使用してメッセージを送信し、エージェントの応答を待機します。

const response = await CopilotStudioService.ExecuteCopilotAsyncV2({
  message: "What is the status of my order?",
  notificationUrl: "https://notificationurlplaceholder",
  agentName: "cr3e1_customerSupportAgent"
});

要求パラメーター

ExecuteCopilotAsyncV2 メソッドは、次のパラメーターを受け入れます。

パラメーター	必須	タイプ	Description
`message`	イエス	文字列	エージェントに送信するプロンプトまたはデータ。構造化データの JSON 文字列を指定できます。
`notificationUrl`	イエス	文字列	プレースホルダー URL ( `"https://notificationurlplaceholder"`を使用)。 API にはこの URL が必要ですが、同期モードでは使用されません。
`agentName`	イエス	文字列	発行済みの Copilot Studio エージェントの名前。

応答の構造

応答には、次のプロパティが含まれています。

プロパティ	タイプ	Description
`responses`	`string[]`	エージェントからの応答文字列の配列
`conversationId`	`string`	追跡用の会話 ID
`lastResponse`	`string`	エージェントからの最新の応答
`completed`	`boolean`	エージェントが処理を完了したかどうか

例: エージェントの応答を取得する

const response = await CopilotStudioService.ExecuteCopilotAsyncV2({
  message: "Summarize the latest product trends",
  notificationUrl: "https://notificationurlplaceholder",
  agentName: "cr3e1_trendAnalyzer"
});

if (response.data.completed) {
  const agentResponse = response.data.lastResponse;
  console.log("Agent response:", agentResponse);
}

例: JSON 応答を解析する

多くの場合、エージェントは応答を JSON 文字列として返します。応答を解析して特定のデータを抽出します。

const response = await CopilotStudioService.ExecuteCopilotAsyncV2({
  message: JSON.stringify({ query: "monthly sales" }),
  notificationUrl: "https://notificationurlplaceholder",
  agentName: "cr3e1_dataAnalyzer"
});

if (response.data.responses && response.data.responses.length > 0) {
  // Parse the JSON response
  const parsedData = JSON.parse(response.data.responses[0]);
  const summary = parsedData.summary;
  const metrics = parsedData.metrics;

  console.log("Summary:", summary);
  console.log("Metrics:", metrics);
}

トラブルシューティング

Copilot Studio エージェントへの接続または呼び出しで問題が発生した場合は、次の解決策が最も一般的な問題に対処します。

エージェントが応答を返さない

ソリューション：ExecuteCopilotAsyncV2操作 (/proactivecopilot/executeAsyncV2) を使用していることを確認します。その他のエンドポイントには、既知の制限があります。

ExecuteCopilot (/execute) - 応答ではなく、 ConversationIdのみを返します (fire-and-forget)。
ExecuteCopilotAsync (/executeAsync) - 502 "サーバー応答を読み取ることができません" エラーが返されることがあります。

応答でのプロパティの大文字と小文字の区別エラー

ソリューション： 応答プロパティの大文字と小文字は実装によって変わることがあります。すべてのバリエーションを確認します。

conversationId
ConversationId
conversationID

オプショナルチェイニングを使用するか、異なる大文字・小文字のバリエーションを確認します。

const convId = response.data.conversationId ??
               response.data.ConversationId ??
               response.data.conversationID;

エージェントから空または予期しない応答が返される

ソリューション： 次のことを確認します。

Copilot Studio でエージェントを発行しました。
エージェント名が正しく、発行されたエージェントと一致します。
メッセージ形式は、エージェントが想定したものと一致します。
エージェントに、入力を処理するように構成されたトピックがあります。

こちらも参照ください

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-02-19