Copilot Studio エージェント用のランタイム脅威検出システムを構築する

組織は、実行時の脅威検出システムに接続することで、Copilot Studio エージェントにセキュリティレイヤーを追加できます。接続されると、エージェントは実行時にこのシステムを呼び出します。エージェントは、エージェントが呼び出すツールが正当かどうかをシステムが判断できるように、システムにデータを提供します。その後、システムは "承認" または "ブロック" のいずれかの応答で Copilot Studio に応答し、それに応じてエージェントがツールを呼び出すかスキップします。既存の外部脅威検出システムにエージェントを接続する方法の詳細については、「 Copilot Studio カスタムエージェントの外部脅威検出と保護を有効にする」を参照してください。

この記事は開発者を対象としており、Copilot Studio エージェントのセキュリティプロバイダーとして独自の脅威検出機能を統合する方法について説明します。

統合は、2 つのエンドポイントで構成される API に基づいています。実装する必要がある主要なエンドポイントは、 analyze-tool-execution エンドポイントです。このエンドポイントを脅威検出システムのインターフェイスとして公開する必要があります。お客様が外部の脅威検出システムとしてシステムを構成すると、エージェントはツールを呼び出すたびにこの API を呼び出します。

analyze-tool-execution エンドポイントとは別に、validateと呼ばれる 2 つ目のエンドポイントも公開する必要があります。 validate エンドポイントは、システムセットアップの一部としてエンドポイントの正常性と準備状況を確認するために使用されます。

以降のセクションでは、各エンドポイントについて詳しく説明します。

POST /validate

目的： 脅威検出エンドポイントに到達可能で機能していることを確認します。初期セットアップと構成テストに使用されます。

要求を検証する

方式： 投稿
URL:https://{threat detection endpoint}/validate?api-version=2025-05-01
ヘッダー：
- 承認: API 認証のベアラートークン
- x-ms-correlation-id: トレースの GUID
体：空

応答を検証する

200 OK 応答の例

{
  "isSuccessful": true,
  "status": "OK"
}

エラー応答の例

エラーが発生した場合 (失敗した HTTP コード)、エンドポイントはエラーコード、メッセージ、およびオプションの診断を返します。

{
  "errorCode": 5031,
  "message": "Validation failed. Webhook service is temporarily unavailable.",
  "httpStatus": 503,
  "diagnostics": "{\\reason\\:\\Upstream dependency timeout\\}"
}

POST /analyze-tool-execution

目的： リスク評価用のツール実行コンテキストを送信します。ツールの実行要求を評価し、ツールの実行を許可するかブロックするかを応答します。

Analyze-tool-execution request

方式： 投稿
URL:https://{threat detection endpoint}/analyze-tool-execution?api-version=2025-05-01
ヘッダー：
- 承認: API 認証のベアラートークン
- Content-Type: application/json
体： JSON オブジェクト

analyze-tool-execution 要求の例

POST https://security.contoso.com/api/agentSecurity/analyze-tool-execution?api-version=2025-05-01
Authorization: Bearer XXX……
x-ms-correlation-id: fbac57f1-3b19-4a2b-b69f-a1f2f2c5cc3c
Content-Type: application/json

{
  "plannerContext": {
    "userMessage": "Send an email to the customer",
    "thought": "User wants to notify customer",
    "chatHistory": [
      {
        "id": "m1",
        "role": "user",
        "content": "Send an email to the customer",
        "timestamp": "2025-05-25T08:00:00Z"
      },
      {
        "id": "m2",
        "role": "assistant",
        "content": "Which customer should I email?",
        "timestamp": "2025-05-25T08:00:01Z"
      },
      {
        "id": "m3",
        "role": "user",
        "content": "The customer is John Doe",
        "timestamp": "2025-05-25T08:00:02Z"
      }
    ],
    "previousToolOutputs": [
      {
        "toolId": "tool-123",
        "toolName": "Get customer email by name",
        "outputs": {
          "name": "email",
          "description": "Customer's email address",
          "type": {
            "$kind": "String"
          },
          "value": "customer@foobar.com"
        },
        "timestamp": "2025-05-25T08:00:02Z"
      }
    ]
  },
  "toolDefinition": {
    "id": "tool-123",
    "type": "PrebuiltToolDefinition",
    "name": "Send email",
    "description": "Sends an email to specified recipients.",
    "inputParameters": [
      {
        "name": "to",
        "description": "Receiver of the email",
        "type": {
          "$kind": "String"
        }
      },
      {
        "name": "bcc",
        "description": "BCC of the email",
        "type": {
          "$kind": "String"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "result",
        "description": "Result",
        "type": {
          "$kind": "String"
        }
      }
    ]
  },
  "inputValues": {
    "to": "customer@foobar.com",
    "bcc": "hacker@evil.com"
  },
  "conversationMetadata": {
    "agent": {
      "id": "agent-guid",
      "tenantId": "tenant-guid",
      "environmentId": "env-guid",
      "isPublished": true
    },
    "user": {
      "id": "user-guid",
      "tenantId": "tenant-guid"
    },
    "trigger": {
      "id": "trigger-guid",
      "schemaName": "trigger-schema"
    },
    "conversationId": "conv-id",
    "planId": "plan-guid",
    "planStepId": "step-1"
  }
}

Analyze-tool-execution response

200 OK（正常に処理されました）

要求が 有効な場合、要求で指定されたツールの使用が評価され、定義された条件に基づいて許可または ブロックされます。応答には、次のフィールドを含めることができます。

blockAction (Boolean): アクションをブロックする必要があるかどうか
reasonCode (整数、省略可能): ブロックの理由を説明する数値コード
reason (文字列、省略可能): 人間が判読できる説明
診断 (オブジェクト、省略可能): トレースまたはデバッグのその他の詳細

許可応答の例

{
  "blockAction": false
}

ブロック応答の例

{
  "blockAction": true,
  "reasonCode": 112,
  "reason": "The action was blocked because there is a noncompliant email address in the BCC field.",
  "diagnostics": "{\\flaggedField\\:\\bcc\\,\\flaggedValue\\:\\hacker@evil.com\\}"
}

エラー応答の例

要求が 有効でない場合は、エラーコード、メッセージ、HTTP 状態、およびオプションの診断を含むエラー応答が返されます。

{
  "errorCode": 4001,
  "message": "Missing required field: toolDefinition",
  "httpStatus": 400,
  "diagnostics": "{\\missingField\\:\\toolDefinition\\,\\traceId\\:\\abc-123\\}"
}

要求本文と応答本文の構造体のリファレンス

次の表では、エンドポイントの要求本文と応答本文内で使用されるさまざまなオブジェクトの内容について説明します。

ValidationResponse

名前	タイプ	必須	説明
isSuccessful	ブール値	イエス	検証に合格したかどうかを示します。
状態	文字列	イエス	オプションのステータスメッセージまたはパートナー固有の詳細。

AnalyzeToolExecutionResponse

名前	タイプ	必須	説明
blockAction	ブール値	イエス	アクションをブロックするかどうかを示します。
reasonCodeの	整数	いいえ	パートナーによって決定される、省略可能な数値の理由コード。
理由	文字列	いいえ	人間が判読できる省略可能な説明。
diagnostics	文字列	いいえ	デバッグまたはテレメトリのオプションのフリーフォーム診断情報。事前に初期化する必要があります。

ErrorResponse

名前	タイプ	必須	説明
エラーコード	整数	イエス	エラーの数値識別子 (たとえば、1001 = フィールドがありません、2003 = 認証エラー)。
メッセージ	文字列	イエス	エラーの人間が判読できる説明。
httpStatus	整数	イエス	パートナーによって返される HTTP 状態コード。
diagnostics	文字列	いいえ	デバッグまたはテレメトリのオプションのフリーフォーム診断情報。事前に初期化する必要があります。

EvaluationRequest

名前	タイプ	必須	説明
plannerContext	PlannerContext	イエス	Planner コンテキストデータ。
toolDefinition	ToolDefinition	イエス	ツール定義の詳細。
inputValues	JSON オブジェクト	イエス	ツールに提供されるキーと値のペアのディクショナリ。
conversationMetadata	ConversationMetadata	イエス	会話コンテキスト、ユーザー、およびプランの追跡に関するメタデータ。

PlannerContext

名前	タイプ	必須	説明
ユーザーメッセージ	文字列	イエス	エージェントによって送信された元のメッセージ。
考え	文字列	いいえ	このツールが選択された理由に関する Planner の説明。
chatHistory	ChatMessage[]	いいえ	ユーザーと交換された最近のチャットメッセージの一覧。
previousToolsOutputs	ToolExecutionOutput[]	いいえ	最近使用したツール出力の一覧。

ChatMessage

名前	タイプ	必須	説明
id	文字列	イエス	会話内のこのメッセージの一意識別子。
ロール	文字列	イエス	メッセージのソース (ユーザー、アシスタントなど)。
コンテンツ	文字列	イエス	メッセージテキスト。
timestamp	string (date-time)	いいえ	メッセージがいつ送信されたかを示す ISO 8601 タイムスタンプ。

ToolExecutionOutputs

名前	タイプ	必須	説明
toolId	文字列	イエス	会話内のこのメッセージの一意識別子。
toolName	文字列	イエス	ツールの名前。
outputs	ExecutionOutput[]	イエス	ツール実行出力の一覧。
timestamp	string (date-time)	いいえ	ツールの実行が完了した時刻を示す ISO 8601 タイムスタンプ。

ExecutionOutput

名前	タイプ	必須	説明
名前	文字列	イエス	出力パラメーターの名前。
説明	文字列	いいえ	出力値の説明。
型	オブジェクト	いいえ	出力のデータ型。
value	JSON データ値	イエス	出力値。

ToolDefinition

名前	タイプ	必須	説明
id	文字列	イエス	ツールの一意識別子。
型	文字列	イエス	プランナーで使用されるツールの種類を指定します。
名前	文字列	イエス	人間が判読できるツールの名前。
説明	文字列	イエス	ツールの動作の概要。
inputParameters	ToolInput[]	いいえ	ツールの入力パラメーター。
outputParameters	ToolOutput[]	いいえ	実行後にツールから返される出力パラメーター。

ToolInput

名前	タイプ	必須	説明
名前	文字列	イエス	入力パラメーターの名前。
説明	文字列	いいえ	この入力パラメーターに必要な値の説明。
型	JSON オブジェクト	いいえ	入力パラメーターのデータ型。

ToolOutput

名前	タイプ	必須	説明
名前	文字列	イエス	出力パラメーターの名前。
説明	文字列	いいえ	出力値の説明。
型	JSON オブジェクト	いいえ	出力値の型。

ConversationMetadata

名前	タイプ	必須	説明
エージェント	AgentContext	イエス	エージェントコンテキスト情報。
ユーザー	UserContext	いいえ	エージェントと対話しているユーザーに関する情報。
トリガ	TriggerContext	いいえ	プランナーの実行をトリガーした内容に関する情報。
conversationId	文字列	イエス	進行中の会話の ID。
planId	文字列	いいえ	ユーザー要求を満たすために使用されるプランの ID。
planStepId	文字列	いいえ	このツールの実行に対応するプラン内のステップ。
parentAgentComponentId	文字列	いいえ	親エージェントコンポーネントの ID。

AgentContext

名前	タイプ	必須	説明
id	文字列	イエス	エージェントの ID。
tenantId	文字列	イエス	エージェントが存在するテナント。
environmentId	文字列	イエス	エージェントが発行される環境。
バージョン	文字列	いいえ	エージェントのバージョン ( `isPublished` が false の場合は省略可能)。
isPublished	ブール値	イエス	この実行コンテキストが発行済みバージョンかどうか。

UserContext

名前	タイプ	必須	説明
id	文字列	いいえ	ユーザーの Microsoft Entra オブジェクト ID。
tenantId	文字列	いいえ	ユーザーのテナント ID。

TriggerContext

名前	タイプ	必須	説明
id	文字列	いいえ	プランナーをトリガーしたトリガーの ID。
schemaName	文字列	いいえ	プランナーをトリガーしたトリガースキーマの名前。

Authentication

開発する統合では、Microsoft Entra ID 認証を使用する必要があります。開発者が構築するアプリを統合する手順に従います。

実行する手順は次のとおりです。

テナント内のリソースのアプリ登録を作成します。
Web API のスコープを公開します。公開されるスコープは、顧客が呼び出すリソースのベース URL である必要があります。たとえば、API URL が https://security.contoso.com/api/threatdetectionされている場合、公開されるスコープは https://security.contoso.comする必要があります。
サービスの実装方法に応じて、承認ロジックを実装し、受信トークンを検証する必要があります。顧客がアプリを承認する方法を文書化する必要があります。これを行う方法は複数あります。たとえば、アプリ ID の許可リストやロールベースのアクセス制御 (RBAC) の使用などです。

応答時間の要件

エージェントは、1,000 ミリ秒未満の脅威検出システムからの応答を期待します。エンドポイントがこの期間内に通話に応答することを確認する必要があります。システムが時間内に応答しない場合、エージェントは応答が "許可" であるかのように動作し、ツールを呼び出します。

API のバージョン管理

要求では、API バージョンは api-version クエリパラメーター (たとえば、 api-version=2025-05-01) を使用して指定されます。実装は、他の予期しないフィールドに対してトレラントである必要があり、今後新しい値が追加されても失敗しないようにする必要があります。現時点のすべてのバージョンは非破壊的と見なされるため、パートナーは API のバージョンを確認しないでください。パートナーは API バージョンを追跡する必要がありますが、新しいバージョンが表示された場合に要求を失敗させるべきではありません。

フィードバック

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

Last updated on 2025-09-05

次の方法で共有

Copilot Studio エージェント用のランタイム脅威検出システムを構築する

POST /validate

要求を検証する

応答を検証する

200 OK 応答の例

エラー応答の例

POST /analyze-tool-execution

Analyze-tool-execution request

analyze-tool-execution 要求の例

Analyze-tool-execution response

200 OK（正常に処理されました）

許可応答の例

ブロック応答の例

エラー応答の例

要求本文と応答本文の構造体のリファレンス

ValidationResponse

AnalyzeToolExecutionResponse

ErrorResponse

EvaluationRequest

PlannerContext

ChatMessage

ToolExecutionOutputs

ExecutionOutput

ToolDefinition

ToolInput

ToolOutput

ConversationMetadata

AgentContext

UserContext

TriggerContext

Authentication

応答時間の要件

API のバージョン管理

フィードバック

その他のリソース