エージェント SDK (プレビュー)

Bot Framework/Microsoft Agents SDK アクティビティ ペイロードをユーザー指定のエージェント エンドポイントに転送します。 エージェント エンドポイント URL は、入力パラメーターとして呼び出しごとに指定されます。 認証は、接続の作成時に選択されます。認証なし、静的 API キー、または OAuth (client_credentialsまたはユーザー サインイン) Microsoft Entra ID。 OAuth が選択されている場合、ベアラー トークンの対象ユーザー (接続で構成されたリソース URL) は、ターゲット エージェントが期待する対象ユーザーと一致する必要があります。

このコネクタは、次の製品とリージョンで使用できます。

サービス	クラス	Regions
コピロット スタジオ	Standard	次を除くすべての Power Automate リージョン :      - 米国政府 (GCC)      - 米国政府 (GCC High)      - 21Vianet が運営する China Cloud      - 米国国防総省 (DoD)
ロジック アプリ	Standard	次を除くすべての Logic Apps リージョン :      - Azure Government リージョン      - Azure China リージョン      - 米国国防総省 (DoD)
Power Apps	Standard	次を除くすべての Power Apps リージョン :      - 米国政府 (GCC)      - 米国政府 (GCC High)      - 21Vianet が運営する China Cloud      - 米国国防総省 (DoD)
Power Automate（パワーオートメート）	Standard	次を除くすべての Power Automate リージョン :      - 米国政府 (GCC)      - 米国政府 (GCC High)      - 21Vianet が運営する China Cloud      - 米国国防総省 (DoD)

連絡先
名前	Microsoft
URL	https://support.microsoft.com

コネクタ メタデータ
パブリッシャー	Microsoft
Web サイト	https://www.microsoft.com
プライバシー ポリシー	https://privacy.microsoft.com/
カテゴリ	生産性

エージェント SDK コネクタは、Bot Framework/Microsoft Agents SDK アクティビティ ペイロードをユーザー指定のエージェント エンドポイントに転送します。 エージェント エンドポイント URL は、入力パラメーターとして呼び出しごとに指定されます。 接続では、コネクタがエージェントに対して認証する方法 (認証なし、静的 API キー、Microsoft Entra IDアプリ専用トークン (クライアント資格情報)、またはMicrosoft Entra ID委任されたユーザー トークン (ユーザー サインイン) が選択されます。 どちらのMicrosoft Entra IDオプションでも、ベアラー トークンの対象ユーザー (接続で構成されたリソース URL) は、ターゲット エージェントが期待する対象ユーザーと一致する必要があります。

前提条件

• デプロイされた Microsoft Agents SDK/Bot Framework エージェントは、HTTPS 経由で到達可能です。
• Microsoft Entra ID (クライアント資格情報) の場合: エージェントをホストしているテナントに登録されたMicrosoft Entra ID アプリケーション。ターゲット エージェントを呼び出すclient_credentials許可とアクセス許可で構成されます。
• Microsoft Entra ID (ユーザー サインイン) の場合: クライアント シークレットを持つエージェント独自のMicrosoft Entra ID アプリケーション (そのMicrosoft アプリ ID)、ユーザーが同意できる公開された API スコープ、Microsoft Graph User.Read("サインインしてユーザー プロファイルを読み取る") 同意を持つ委任されたアクセス許可、およびhttps://global.consent.azure-apim.net/redirect/agentsdk Web リダイレクト URI として追加されます。
• API キーとクライアント資格情報のオプションの場合、エージェントの予想されるトークン対象ユーザー (通常は、api://<appId>やアプリ ID GUID など、エージェントの Microsoft アプリ ID)。 ユーザーサインインの場合、対象ユーザーはアプリ ID GUID である必要があります (下記参照)。

資格情報を取得する

Microsoft Entra ID (クライアント資格情報)

コネクタはアプリ専用トークンを送信します。 API 要求を認証するには、次のものが必要です。

1. Microsoft Entra ID アプリケーションのテナント ID。
2. Microsoft Entra ID アプリケーションのクライアント ID (アプリケーション ID)。
3. そのアプリケーションの クライアント シークレット 。
4. ターゲット エージェントで予想される対象ユーザーと一致する リソース URL (Bot Framework スキル認証パターン)。

接続を作成するときに、これらの値を指定します。 対象ユーザーが異なる場合は、エージェントごとに 1 つの接続を作成します。

Microsoft Entra ID (ユーザー サインイン)

コネクタは、接続にサインインしているアカウントの委任されたトークンを送信するため、エージェントはそのアカウントの代わりに (たとえば、Microsoft 365 エージェント SDK ConnectorUserAuthorization ハンドラーを使用して) それを交換できます。 以下が必要です。

1. エージェントのMicrosoft Entra ID アプリケーションのテナント ID。
2. クライアント ID: エージェント独自のMicrosoftアプリ ID。 Microsoft 365 エージェント SDKは、トークンがエージェントの独自のアプリケーションに発行された場合にのみ、ユーザーに代わってトークンを交換します。
3. そのアプリケーションの クライアント シークレット 。
4. リソース URL: エージェントの Microsoft アプリ ID (GUID)、クライアント ID と同じ値。 エージェント独自のアプリケーションはクライアントとリソースの両方であるため、Microsoft Entraにはここで GUID が必要です (それ以外の場合AADSTS90009)。このオプションではapi://<appId>はサポートされていません。

接続を作成するときにこれらの値を指定し、サインインしてエージェントの公開スコープに同意します。 エージェントごとに 1 つの接続を作成します。

また、アプリケーションには、同意を得て、Microsoft Graph User.Read ("サインインとユーザー プロファイルの読み取り") 委任されたアクセス許可も必要です。このアクセス許可がないと、サインインはAADSTS90008で失敗します。

ダウンストリーム API のトークンを交換するには、エージェントのアプリケーションで API の委任されたアクセス許可を構成し、必要なユーザーまたは管理者の同意を取得します。 エージェント独自の API でスコープを公開しても、ダウンストリームのアクセス許可は付与されません。

既知の問題と制限事項

• agentEndpoint入力は、完全な HTTPS URL (たとえば、https://my-agent.azurewebsites.net) である必要があります。 コネクタは /api/messages を追加し、アクティビティ ペイロードを転送します。
• コネクタはアクティビティ ペイロード as-is を転送し、 deliveryMode設定しません。 エージェントは、受信アクティビティで指定されたserviceUrlに POSTing 応答アクティビティを返すことによって非同期 (通常の配信) に応答します (呼び出し元は、たとえば、Microsoft Copilot Studio、SAS キーのコールバック serviceUrlを提供します)。
• Microsoft Entra ID (ユーザー サインイン) 接続は、その接続で行われたすべての呼び出し (エージェントとチャットしている他のユーザーに代わって呼び出しを含む) に対して、接続にサインインしたアカウントの委任されたトークンを常に送信します。 呼び出し元ごとに個別のトークンは送信されないため、アクティビティの from ユーザーはトークン内のユーザーと異なる場合があります。 要求を検証済みトークンのアカウントとしてのみ承認し、アクティビティの from または要求ヘッダーをチャットユーザーの権限として扱いません。 エージェントが各ユーザーとチャットする必要がある場合は、この接続の種類を使用しないでください。
• サインインしたアカウントの同意が取り消されたか、セッションを更新できなくなった場合は、もう一度接続にサインインします。
• このコネクタはプレビュー段階です。 可用性と機能は変更される可能性があります。

接続を作成する

コネクタでは、次の認証の種類がサポートされています。

API キー	ターゲット エージェントがカスタム HTTP ヘッダーで想定する静的 API キーを使用して認証します。 ヘッダー名 (x-api-key など) とその値の両方を指定します。	すべてのリージョン	共有不可
Microsoft Entra ID (クライアント資格情報)	client_credentials フローを使用したMicrosoft Entra ID アプリケーションからの Mint OAuth ベアラー トークン。 ベアラー トークンの対象ユーザー (リソース URL) は、ターゲット エージェントが期待する対象ユーザーと一致する必要があります。	すべてのリージョン	共有不可
Microsoft Entra ID (ユーザー サインイン)	ターゲット エージェントのMicrosoft Entra ID アプリケーション (承認コード フロー) を使用してサインインし、サインインしたアカウントの委任されたベアラー トークンを送信します。 この接続で行われるすべての呼び出しでは、エージェントとチャットしているユーザーではなく、接続にサインインしたアカウントが使用されます。 ユーザーの代わりにトークンを交換するには、エージェントのダウンストリームの委任されたアクセス許可と同意が構成されている必要があります。	すべてのリージョン	共有不可
認証なし	認証ヘッダーなしでターゲット エージェント エンドポイントを呼び出します。 匿名呼び出しを明示的に受け入れるエージェントでのみ使用します。	すべてのリージョン	共有可能
既定 [非推奨]	このオプションは、明示的な認証の種類がない古い接続に対してのみ行われ、下位互換性のためにのみ提供されます。	すべてのリージョン	共有不可

API キー

認証 ID: apiKey

適用対象: すべてのリージョン

ターゲット エージェントがカスタム HTTP ヘッダーで想定する静的 API キーを使用して認証します。 ヘッダー名 (x-api-key など) とその値の両方を指定します。

これは共有可能な接続ではありません。 電源アプリが別のユーザーと共有されている場合、別のユーザーは新しい接続を明示的に作成するように求められます。

名前	タイプ	Description	Required
API キー ヘッダー名	文字列	ターゲット エージェントが API キーを受け取る HTTP ヘッダーの名前 (例: x-api-key または Ocp-Apim-Subscription-Key)。	True
API キーの値	Securestring	ターゲット エージェント エンドポイントに対するすべての要求で送信される静的 API キー値。	True

Microsoft Entra ID (クライアント資格情報)

認証 ID: oauthClientCredentials

適用対象: すべてのリージョン

client_credentials フローを使用したMicrosoft Entra ID アプリケーションからの Mint OAuth ベアラー トークン。 ベアラー トークンの対象ユーザー (リソース URL) は、ターゲット エージェントが期待する対象ユーザーと一致する必要があります。

これは共有可能な接続ではありません。 電源アプリが別のユーザーと共有されている場合、別のユーザーは新しい接続を明示的に作成するように求められます。

名前	タイプ	Description	Required
Tenant	文字列	Microsoft Entra ID アプリケーションのテナント ID	True
クライアント ID	文字列	Microsoft Entra ID アプリケーションのクライアント (またはアプリケーション) ID。	True
クライアント シークレット	Securestring	Microsoft Entra ID アプリケーションのクライアント シークレット。	True
リソースの URL	文字列	OAuth トークンの対象ユーザー。 通常、ターゲット エージェントのMicrosoftアプリ ID (たとえば、api://<appId> アプリ ID GUID)。	True

Microsoft Entra ID (ユーザー サインイン)

認証 ID: oauthAuthorizationCode

適用対象: すべてのリージョン

ターゲット エージェントのMicrosoft Entra ID アプリケーション (承認コード フロー) を使用してサインインし、サインインしたアカウントの委任されたベアラー トークンを送信します。 この接続で行われるすべての呼び出しでは、エージェントとチャットしているユーザーではなく、接続にサインインしたアカウントが使用されます。 ユーザーの代わりにトークンを交換するには、エージェントのダウンストリームの委任されたアクセス許可と同意が構成されている必要があります。

これは共有可能な接続ではありません。 電源アプリが別のユーザーと共有されている場合、別のユーザーは新しい接続を明示的に作成するように求められます。

名前	タイプ	Description	Required
Tenant	文字列	ターゲット エージェントのMicrosoft Entra ID アプリケーションのテナント ID。	True
クライアント ID	文字列	ターゲット エージェントの Microsoft アプリ ID。 エージェント独自のアプリケーションを使用して、エージェントがユーザーの代わりに委任されたトークンを交換できるようにします。	True
クライアント シークレット	Securestring	ターゲット エージェントのMicrosoft Entra ID アプリケーションのクライアント シークレット。	True
リソースの URL	文字列	委任されたトークンの対象ユーザー。 ターゲット エージェントの Microsoft アプリ ID (GUID) である必要があります。クライアント ID と同じ値です。Microsoft Entraは、アプリケーションがそれ自体のトークンを要求するときに GUID のみを受け入れます。	True

認証なし

認証 ID: 匿名

適用対象: すべてのリージョン

認証ヘッダーなしでターゲット エージェント エンドポイントを呼び出します。 匿名呼び出しを明示的に受け入れるエージェントでのみ使用します。

これは共有可能な接続です。 電源アプリが別のユーザーと共有されている場合は、接続も共有されます。 詳細については、キャンバス アプリの Connectors の概要 - Power Apps |Microsoft Docs

既定 [非推奨]

適用対象: すべてのリージョン

このオプションは、明示的な認証の種類がない古い接続に対してのみ行われ、下位互換性のためにのみ提供されます。

これは共有可能な接続ではありません。 電源アプリが別のユーザーと共有されている場合、別のユーザーは新しい接続を明示的に作成するように求められます。

アクション

エージェントにアクティビティを送信する

アクティビティ プロトコル ペイロードを {agentEndpoint}/api/messages のエージェント エンドポイントに転送します。 接続で Microsoft Entra ID OAuth を使用する場合、トークン対象ユーザー (接続上のリソース URL) は、ターゲット エージェント (Bot Framework スキル認証パターン) で想定される対象ユーザーと同じである必要があります。対象ユーザーが異なる場合は、エージェントごとに 1 つの接続を作成します。 コネクタは、アクティビティ ペイロード as-is を転送し、'deliveryMode' を設定しません。エージェントは、受信アクティビティで指定された 'serviceUrl' に応答アクティビティを POSTing することで、非同期 (通常の配信) に応答します。

エージェントにアクティビティを送信する

操作 ID:

SendActivity

アクティビティ プロトコル ペイロードを {agentEndpoint}/api/messages のエージェント エンドポイントに転送します。 接続で Microsoft Entra ID OAuth を使用する場合、トークン対象ユーザー (接続上のリソース URL) は、ターゲット エージェント (Bot Framework スキル認証パターン) で想定される対象ユーザーと同じである必要があります。対象ユーザーが異なる場合は、エージェントごとに 1 つの接続を作成します。 コネクタは、アクティビティ ペイロード as-is を転送し、'deliveryMode' を設定しません。エージェントは、受信アクティビティで指定された 'serviceUrl' に応答アクティビティを POSTing することで、非同期 (通常の配信) に応答します。

パラメーター

Name	キー	必須	型	説明
エージェント エンドポイント URL	agentEndpoint	True	string	ターゲット Microsoft Agents SDK/Bot Framework エンドポイントのベース URL (たとえば、https://my-agent.azurewebsites.net)。 コネクタは /api/messages を追加します。
			object

返品

response

object

定義

オブジェクト

’オブジェクト’ という種類です。