สร้างระบบตรวจจับภัยคุกคามรันไทม์สําหรับตัวแทน Copilot Studio

องค์กรสามารถเพิ่มเลเยอร์ของความปลอดภัยให้กับตัวแทน Copilot Studio ของพวกเขาได้โดยการเชื่อมต่อเข้ากับระบบตรวจจับภัยคุกคามรันไทม์ เมื่อเชื่อมต่อแล้ว ตัวแทนจะเรียกใช้ระบบนี้ในขณะทํางาน ตัวแทนให้ข้อมูลแก่ระบบเพื่อให้ระบบสามารถตรวจสอบว่าเครื่องมือที่แผนการเรียกใช้ตัวแทนนั้นถูกกฎหมายหรือไม่ จากนั้นระบบตอบกลับไปยัง Copilot Studio พร้อมการตอบกลับว่า "อนุมัติ" หรือ "บล็อก" ส่งผลให้ตัวแทนสามารถเรียกใช้หรือข้ามเครื่องมือดังกล่าวได้ สําหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีเชื่อมต่อตัวแทนกับระบบตรวจจับภัยคุกคามภายนอกที่มีอยู่ โปรดดู เปิดใช้งานการตรวจจับภัยคุกคามภายนอกและการป้องกันสําหรับตัวแทนแบบกําหนดเองของ Copilot Studio

บทความนี้มีการกําหนดเป้าหมายไปที่นักพัฒนาและอธิบายวิธีการรวมความสามารถในการตรวจจับภัยคุกคามของคุณเองในฐานะผู้ให้บริการความปลอดภัยสําหรับตัวแทน Copilot Studio

การรวมจะขึ้นอยู่กับ API ที่ประกอบด้วยจุดสิ้นสุดสองจุด จุดสิ้นสุดหลักที่คุณจำเป็นต้องใช้งานคือ analyze-tool-execution คุณจําเป็นต้องเปิดเผยจุดสิ้นสุดนี้เป็นอินเทอร์เฟซกับระบบตรวจจับภัยคุกคามของคุณ เมื่อลูกค้ากําหนดค่าระบบของคุณเป็นระบบตรวจจับภัยคุกคามภายนอกแล้ว ตัวแทนจะเรียกใช้ API นี้ทุกครั้งที่ตั้งใจจะใช้เครื่องมือ

นอกเหนือจากanalyze-tool-executionจุดสิ้นสุด คุณยังจําเป็นต้องแสดงจุดสิ้นสุดที่สอง ที่เรียกว่าvalidate จุด validate สิ้นสุดถูกใช้เพื่อตรวจสอบสถานภาพและความพร้อมของจุดสิ้นสุดเป็นส่วนหนึ่งของการตั้งค่าระบบ

ส่วนต่อไปนี้อธิบายแต่ละจุดสิ้นสุดโดยละเอียด

โพสต์ /ตรวจสอบความถูกต้อง

วัตถุประสงค์: ตรวจสอบว่าจุดสิ้นสุดการตรวจจับภัยคุกคามสามารถเข้าถึงและใช้งานได้ ใช้สําหรับการตั้งค่าเริ่มต้นและการทดสอบการกําหนดค่า

ตรวจสอบความถูกต้องของคําขอ

  • วิธีการ: POST

  • เว็บไซต์:https://{threat detection endpoint}/validate?api-version=2025-05-01

  • ส่วนหัว:

    • การอนุญาต: โทเค็นแบเรอร์สําหรับการรับรองความถูกต้อง API

    • x-ms-correlation-id: GUID สําหรับการติดตาม

  • ร่างกาย: เปล่า

ตรวจสอบความถูกต้องของการตอบสนอง

ตัวอย่างการตอบสนอง 200 ตกลง

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

ตัวอย่างการตอบสนองข้อผิดพลาด

ถ้าเกิดข้อผิดพลาด (รหัส HTTP ไม่สําเร็จ) จุดสิ้นสุดจะส่งกลับรหัสข้อผิดพลาด ข้อความ และการวินิจฉัยทางเลือก

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

POST /การวิเคราะห์การใช้งานเครื่องมือ

วัตถุประสงค์: ส่งบริบทการดําเนินการของเครื่องมือสําหรับการประเมินความเสี่ยง ประเมินคําขอการดําเนินการเครื่องมือและตอบสนองว่าจะอนุญาตหรือบล็อกการดําเนินการของเครื่องมือ

คำขอการดำเนินการใช้เครื่องมือวิเคราะห์

  • วิธีการ: POST

  • เว็บไซต์:https://{threat detection endpoint}/analyze-tool-execution?api-version=2025-05-01

  • ส่วนหัว:

    • การอนุญาต: โทเค็นแบเรอร์สําหรับการรับรองความถูกต้อง API
    • เนื้อหา-ชนิด: แอปพลิเคชัน/json

  • ร่างกาย: วัตถุ JSON

ตัวอย่างคําขอสำหรับการวิเคราะห์การปฏิบัติงานของเครื่องมือ

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

การวิเคราะห์การตอบสนองของเครื่องมือที่ดำเนินการ

200 ตกลง

เมื่อคําขอ ถูกต้อง เครื่องมือจะใช้ที่ระบุไว้ในคําขอจะได้รับการประเมินและ อนุญาต หรือ บล็อกโดยยึดตามเกณฑ์ที่กําหนด การตอบสนองสามารถมีเขตข้อมูลต่อไปนี้:

  • blockAction (บูลีน): ว่าควรบล็อกการดําเนินการหรือไม่
  • reasonCode (จํานวนเต็ม เป็นทางเลือก): โค้ดตัวเลขที่อธิบายเหตุผลสําหรับบล็อก
  • เหตุผล (สตริง ตัวเลือก): คําอธิบายที่มนุษย์อ่านได้
  • การวินิจฉัย (วัตถุ ตัวเลือก): รายละเอียดอื่น ๆ สําหรับการติดตามหรือการดีบัก

ตัวอย่างอนุญาตให้มีการตอบกลับ

{
  "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 แบบบูลีน ใช่ ระบุว่าการตรวจสอบความถูกต้องผ่านหรือไม่
สถานะ สตริง ใช่ ข้อความสถานะทางเลือกหรือรายละเอียดเฉพาะของคู่ค้า

การวิเคราะห์การตอบสนองของการดำเนินการของเครื่องมือ

ชื่อ ชนิด ต้องระบุ คำอธิบาย
blockAction แบบบูลีน ใช่ ระบุว่าควรบล็อคการดําเนินการหรือไม่
รหัสเหตุผล จำนวนเต็ม ไม่ รหัสเหตุผลตัวเลขที่เลือกได้ ซึ่งกําหนดโดยคู่ค้า
เหตุผล สตริง ไม่ คําอธิบายเพิ่มเติมที่มนุษย์สามารถอ่านได้
วินิจฉัย สตริง ไม่ ข้อมูลการวินิจฉัยรูปแบบอิสระที่เลือกได้สําหรับการตรวจแก้จุดบกพร่องหรือการวัดและส่งข้อมูลทางไกล ต้องทำให้มีการซีเรียลไลซ์ล่วงหน้า

ErrorResponse

ชื่อ ชนิด ต้องระบุ คำอธิบาย
รหัสข้อผิดพลาด จำนวนเต็ม ใช่ ตัวระบุตัวเลขสําหรับข้อผิดพลาด (ตัวอย่างเช่น 1001 = เขตข้อมูลที่ขาดหายไป 2003 = การรับรองความถูกต้องล้มเหลว)
ข้อความ สตริง ใช่ คําอธิบายข้อผิดพลาดที่มนุษย์อ่านได้
httpStatus จำนวนเต็ม ใช่ รหัสสถานะ HTTP ที่คู่ค้าส่งกลับ
วินิจฉัย สตริง ไม่ ข้อมูลการวินิจฉัยรูปแบบอิสระที่เลือกได้สําหรับการตรวจแก้จุดบกพร่องหรือการวัดและส่งข้อมูลทางไกล ต้องทำให้มีการซีเรียลไลซ์ล่วงหน้า

คำขอการประเมิน

ชื่อ ชนิด ต้องระบุ คำอธิบาย
plannerContext PlannerContext ใช่ ข้อมูลบริบทของระบบวางแผน
toolDefinition ToolDefinition ใช่ รายละเอียดข้อกําหนดเครื่องมือ
inputValues วัตถุ JSON ใช่ พจนานุกรมของคู่คีย์-ค่าที่กําหนดให้กับเครื่องมือ
conversationMetadata ConversationMetadata ใช่ เมตาดาต้าเกี่ยวกับบริบทการสนทนา ผู้ใช้ และการติดตามแผน

PlannerContext

ชื่อ ชนิด ต้องระบุ คำอธิบาย
ข้อความผู้ใช้ สตริง ใช่ ข้อความต้นฉบับส่งโดยเอเจนต์
ความคิด สตริง ไม่ คําอธิบายสําหรับนักวางแผนสําหรับสาเหตุที่เลือกเครื่องมือนี้
chatHistory ChatMessage[] ไม่ รายการของข้อความสนทนาล่าสุดที่แลกเปลี่ยนกับผู้ใช้
ผลลัพธ์จากเครื่องมือก่อนหน้า ToolExecutionOutput[] ไม่ รายการผลลัพธ์เครื่องมือล่าสุด

ChatMessage

ชื่อ ชนิด ต้องระบุ คำอธิบาย
รหัส สตริง ใช่ ตัวระบุที่ไม่ซ้ําสําหรับข้อความนี้ในการสนทนา
บทบาท สตริง ใช่ แหล่งที่มาของข้อความ (ตัวอย่างเช่น ผู้ใช้ ผู้ช่วย)
เนื้อหา สตริง ใช่ เนื้อหาข้อความ
ประทับเวลา สตริง (วันที่-เวลา) ไม่ ตราประทับเวลา ISO 8601 ที่ระบุเมื่อส่งข้อความ

ผลลัพธ์จากการทำงานของเครื่องมือ

ชื่อ ชนิด ต้องระบุ คำอธิบาย
toolId สตริง ใช่ ตัวระบุที่ไม่ซ้ําสําหรับข้อความนี้ในการสนทนา
toolName สตริง ใช่ ชื่อของเครื่องมือ
เอาต์ พุ ต ExecutionOutput[] ใช่ รายการของผลลัพธ์การดําเนินการเครื่องมือ
ประทับเวลา สตริง (วันที่-เวลา) ไม่ การประทับเวลา ISO 8601 จะระบุเมื่อการดําเนินการเครื่องมือเสร็จสิ้น

ExecutionOutput

ชื่อ ชนิด ต้องระบุ คำอธิบาย
ชื่อ สตริง ใช่ ชื่อของพารามิเตอร์เอาต์พุต
คำอธิบาย สตริง ไม่ คําอธิบายสําหรับค่าเอาต์พุต
type ออบเจ็กต์ ไม่ ชนิดข้อมูลของผลลัพธ์
value ค่าข้อมูล JSON ใช่ ค่าเอาต์พุต

ToolDefinition

ชื่อ ชนิด ต้องระบุ คำอธิบาย
รหัส สตริง ใช่ รหัสเฉพาะของเครื่องมือ
type สตริง ใช่ ระบุชนิดของเครื่องมือที่ใช้ในตัววางแผน
ชื่อ สตริง ใช่ ชื่อของเครื่องมือที่มนุษย์สามารถอ่านได้
คำอธิบาย สตริง ใช่ ข้อมูลสรุปของสิ่งที่เครื่องมือทํา
พารามิเตอร์ที่ใส่เข้าไป ToolInput[] ไม่ พารามิเตอร์ข้อมูลป้อนเข้าของเครื่องมือ
outputParameters ToolOutput[] ไม่ พารามิเตอร์เอาต์พุตที่เครื่องมือส่งกลับหลังจากการดําเนินการ

ToolInput

ชื่อ ชนิด ต้องระบุ คำอธิบาย
ชื่อ สตริง ใช่ ชื่อของพารามิเตอร์ข้อมูลป้อนเข้า
คำอธิบาย สตริง ไม่ คําอธิบายค่าที่คาดไว้สําหรับพารามิเตอร์การป้อนข้อมูลนี้
type วัตถุ JSON ไม่ ชนิดข้อมูลของพารามิเตอร์ข้อมูลป้อนเข้า

ToolOutput

ชื่อ ชนิด ต้องระบุ คำอธิบาย
ชื่อ สตริง ใช่ ชื่อของพารามิเตอร์เอาต์พุต
คำอธิบาย สตริง ไม่ คําอธิบายของค่าเอาต์พุต
type วัตถุ JSON ไม่ ชนิดของค่าเอาต์พุต

ConversationMetadata

ชื่อ ชนิด ต้องระบุ คำอธิบาย
เอเจนต์ AgentContext ใช่ ข้อมูลบริบทของตัวแทน
ผู้ใช้ UserContext ไม่ ข้อมูลเกี่ยวกับผู้ใช้ที่โต้ตอบกับตัวแทน
ทริกเกอร์ TriggerContext ไม่ ข้อมูลเกี่ยวกับสิ่งที่กระตุ้นการดำเนินการตามแผน
conversationId สตริง ใช่ ID ของการสนทนาที่กําลังดําเนินอยู่
planId สตริง ไม่ ID ของแผนที่ใช้ในการปฏิบัติตามคําขอของผู้ใช้
planStepId สตริง ไม่ ขั้นตอนภายในแผนที่สอดคล้องกับการดําเนินการของเครื่องมือนี้
parentAgentComponentId สตริง ไม่ รหัสของคอมโพเนนต์ของบริษัทตัวแทนหลัก

AgentContext

ชื่อ ชนิด ต้องระบุ คำอธิบาย
รหัส สตริง ใช่ ID ของเจ้าหน้าที่
รหัสผู้เช่า สตริง ใช่ ผู้เช่าที่มีตัวแทนอยู่
environmentId สตริง ใช่ สภาพแวดล้อมที่มีการเผยแพร่เอเจนต์
รุ่น สตริง ไม่ เวอร์ชันของตัวแทน (ไม่บังคับถ้า isPublished เป็นเท็จ)
เผยแพร่แล้ว แบบบูลีน ใช่ ไม่ว่าบริบทการดําเนินการนี้เป็นเวอร์ชันที่เผยแพร่หรือไม่

UserContext

ชื่อ ชนิด ต้องระบุ คำอธิบาย
รหัส สตริง ไม่ รหัสวัตถุ Microsoft Entra ของผู้ใช้
รหัสผู้เช่า สตริง ไม่ ID ผู้เช่าของผู้ใช้

TriggerContext

ชื่อ ชนิด ต้องระบุ คำอธิบาย
รหัส สตริง ไม่ รหัสของทริกเกอร์ที่กระตุ้นตัววางแผน
schemaName สตริง ไม่ ชื่อของสคีมาทริกเกอร์ที่ใช้เรียกตัววางแผน

การรับรองความถูกต้อง

การรวมที่คุณพัฒนาควรใช้การรับรองความถูกต้อง Microsoft Entra ID ทําตามคําแนะนําที่ รวมแอปของคุณที่สร้างโดยนักพัฒนาของคุณ

ขั้นตอนในการดําเนินการมีดังต่อไปนี้:

  • สร้างการลงทะเบียนแอป สําหรับทรัพยากรในผู้เช่าของคุณ
  • เปิดเผยขอบเขตสําหรับ API เว็บของคุณ ขอบเขตที่แสดงต้องเป็น URL พื้นฐานสําหรับทรัพยากรที่ลูกค้าเรียก ตัวอย่างเช่น ถ้า URL ของ API คือ https://security.contoso.com/api/threatdetectionขอบเขตที่แสดงจะต้องเป็นhttps://security.contoso.com
  • ทั้งนี้ขึ้นอยู่กับวิธีที่คุณใช้บริการของคุณ คุณจําเป็นต้องใช้ตรรกะการอนุญาตและตรวจสอบโทเค็นขาเข้า คุณจําเป็นต้องจัดทําเอกสารถึงวิธีที่ลูกค้าต้องอนุญาตแอปของตน มีหลายวิธีในการทําเช่นนั้น เช่น การใช้รายการรหัสแอปที่อนุญาต หรือการควบคุมการเข้าถึงตามบทบาท (RBAC)

ข้อกําหนดเวลาตอบสนอง

ตัวแทนคาดหวังการตอบสนองจากระบบตรวจจับภัยคุกคามภายในน้อยกว่า 1,000 มิลลิวินาที คุณควรตรวจสอบให้แน่ใจว่าจุดสิ้นสุดของคุณตอบกลับการเรียกภายในกรอบเวลานี้ หากระบบของคุณไม่ตอบสนองในเวลา, ตัวแทนจะปฏิบัติเสมือนว่าคำตอบของคุณคือ "อนุญาต" และเรียกใช้เครื่องมือ

การกําหนดรุ่น API

ในคําขอ เวอร์ชัน API จะถูกระบุผ่าน api-version พารามิเตอร์คิวรี (ตัวอย่างเช่น api-version=2025-05-01) การใช้งานของคุณควรทนต่อเขตข้อมูลที่ไม่คาดคิดอื่น ๆ และไม่ควรล้มเหลวหากมีการเพิ่มค่าใหม่ในอนาคต คู่ค้าไม่ควรตรวจสอบเวอร์ชันของ API เนื่องจากเวอร์ชันทั้งหมดในขณะนี้ถือว่าไม่เสียหาย คู่ค้าควรติดตามเวอร์ชันของ API แต่ไม่ควรทำให้คำขอล้มเหลวเมื่อเห็นเวอร์ชันใหม่

  • Last updated on