แนวคิดการสังเกตการณ์ของ Agent 365

บทความนี้อธิบายโมเดลข้อมูลที่อยู่เบื้องหลังการสังเกตการณ์ของ Agent 365 ได้แก่ ข้อมูลที่เอเจนต์การวัดและส่งข้อมูลทางไกลส่งออกมา ใครสามารถส่งข้อมูลได้ ข้อมูลถูกส่งไปที่ใด และขีดจำกัดที่ใช้ แนวคิดเหล่านี้ใช้กับทุกเส้นทางการรวม: Microsoft OpenTelemetry Distro, Agent 365 SDK และ direct OTel

หมายเหตุ

รายละเอียดเชิงเทคนิค - เช่น เส้นทาง URL ใน การตรวจสอบสิทธิ์ รหัสข้อผิดพลาด HTTP ใน ขีดจำกัดและเงื่อนไขการทิ้งข้อมูล และขีดจำกัดขนาดและอัตราต่อคำขอ - จะใช้เฉพาะกับเส้นทาง OTel แบบตรงเท่านั้น SDK และ Distro จะซ่อนรายละเอียดเหล่านี้ให้คุณ ส่วนที่เหลือของบทความนี้ (อภิธานศัพท์ โฟลว์ข้อมูล แบบจำลองข้อมูลประจำตัว ขอบเขต เงื่อนไขการวาง ที่ข้อมูลแสดงขึ้น) จะนำไปใช้กับทุกเส้นทาง

เลือกเส้นทางการรวมระบบ

สามเส้นทางจะส่งโมเดลข้อมูลสแปนแบบเดียวกันเข้าสู่ Agent 365 เลือกอย่างใดอย่างหนึ่ง:

  • Microsoft OpenTelemetry Distro - แนะนำสำหรับการผสานระบบใหม่ SDK แบบรวมสำหรับการสังเกตการณ์ทั่วทั้ง Agent 365, Microsoft Foundry, Azure Monitor และอื่นๆ
  • Agent 365 SDK (Observability SDK) - SDK รุ่นก่อนหน้า ยังคงสามารถใช้งานได้โดยไม่มีการเปลี่ยนแปลงที่ทำให้เสียความเข้ากันได้ แต่ไม่ใช่เส้นทางที่แนะนำสำหรับการผสานรวมใหม่อีกต่อไป จะมีคำแนะนำในการเปลี่ยนผ่านสำหรับผู้ใช้ SDK ที่มีอยู่ในเร็ว ๆ นี้
  • Direct OTel - เส้นทาง OTLP/HTTP ดิบ ใช้งานเฉพาะเมื่อคุณมี OpenTelemetry pipeline อยู่แล้ว หรือเฟรมเวิร์กเอเจนต์ของคุณไม่สามารถใช้ Agent 365 SDK ได้ หรือเอเจนต์ของคุณเขียนด้วยภาษาที่ SDK ยังไม่รองรับ (เช่น Java)

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

คำศัพท์

  • รหัสแอป (appId): ตัวระบุแอปพลิเคชันที่ออกเมื่อมีการลงทะเบียนแอป Microsoft Entra หรือ ข้อมูลประจำตัวของเอเจนต์ ID เอเจนต์ของ Microsoft Entra
    • เท่ากับ OAuth client_idไม่ใช่รหัสออบเจ็กต์ Microsoft Entra
    • ตลอดทั้งเอกสารนี้ "รหัสเอเจนต์" และ "รหัสพิมพ์เขียว" หมายถึง appId
  • การสนทนา: ลำดับเชิงตรรกะของการโต้ตอบกับเอเจนต์ เช่น เธรดการแชทของ Teams
    • ระบุโดย gen_ai.conversation.id
    • คีย์การรวมหลักสำหรับการรัน
  • ช่องทาง: แพลตฟอร์มที่เอเจนต์ทำงานอยู่: msteams, outlook, web เป็นต้น
  • การรัน: ข้อความจากผู้ใช้หนึ่งครั้ง และคำตอบจากเอเจนต์หนึ่งครั้ง ถูกจำลองเป็นโครงสร้างแบบต้นไม้ของสแปน OTel สแปน ที่แชร์ traceId

วิธีการทำงาน

สำหรับภาพรวมของ Agent 365 และข้อมูลการวัดและส่งข้อมูลทางไกลที่เชื่อมต่อ โปรดดูที่ ภาพรวมของ Microsoft Agent 365

คุณส่งการวัดและส่งข้อมูลทางไกลเป็นข้อมูลการติดตาม OpenTelemetry:

  • โครงสร้างแบบต้นไม้ของ สแปน ที่อธิบาย รัน หนึ่งครั้ง (ข้อความจากผู้ใช้หนึ่งข้อความเข้า และการตอบกลับจากเอเจนต์หนึ่งข้อความออก)
  • แต่ละสแปนจะอธิบายขั้นตอนเดียว ได้แก่ การเรียกใช้งานเอเจนต์ระดับบนสุด การเรียกใช้งาน LLM การเรียกใช้เครื่องมือ หรือการตอบกลับขั้นสุดท้าย

โฟลว์ข้อมูล

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

โมเดลข้อมูลประจำตัว

สำหรับคำอธิบายอย่างละเอียดเกี่ยวกับโมเดลข้อมูลประจำตัวของเอเจนต์ (การลงทะเบียนแอป Microsoft Entra แบบมาตรฐาน เทียบกับ แบบพิมพ์เขียวข้อมูลประจำตัวเอเจนต์ ID เอเจนต์ของ Microsoft Entra รวมถึงเพื่อนร่วมทีม AI) โปรดดูที่ เริ่มต้นใช้งานการพัฒนา Agent 365 การเลือกโมเดลข้อมูลประจำตัวของคุณจะเป็นตัวกำหนดว่าโฟลว์การรับรองความถูกต้องและปลายทางใดที่คุณจะใช้

หากเอเจนต์ของคุณไม่มีการลงทะเบียน Microsoft Entra จะไม่สามารถใช้เส้นทางเหล่านี้ได้โดยตรง ระบุเอเจนต์ผ่านแอตทริบิวต์ ID สำรอง (ดูที่ การอ้างอิงแอตทริบิวต์) และติดต่อทีม Agent 365 เกี่ยวกับเส้นทางขาเข้าที่เหมาะสม

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

การรับรองความถูกต้องจะแยกสาขาว่าบริการของคุณรับรองความถูกต้องด้วยตนเองหรือในนามของผู้ใช้ สาขาจะกำหนดโฟลว์ OAuth การอ้างสิทธิ์โทเค็นที่มีสิทธิ์ และเส้นทาง URL

  • บริการยืนยันตัวเอง: ไม่มีผู้ใช้ที่ลงชื่อเข้าใช้ – อัตโนมัติ จัดกำหนดการ หรือขับเคลื่อนด้วยเหตุการณ์

    • โฟลว์ OAuth: ข้อมูลรับรองไคลเอ็นต์แบบบริการถึงบริการ (S2S)
    • การอ้างสิทธิ์โทเค็น: roles
    • เส้นทาง URL: /observabilityService/...

  • บริการยืนยันตัวตนในนามของผู้ใช้: สำหรับเพื่อนร่วมทีม AI หรือสำหรับบัญชีผู้ใช้ของเอเจนต์เอง

    • โฟลว์ OAuth: ในนามของผู้ใช้ (OBO)
    • การอ้างสิทธิ์โทเค็น: scp
    • เส้นทาง URL: /observability/...

แอปเอเจนต์เดียวกันสามารถเข้าร่วมในทั้งสองโฟลว์ เช่น เพื่อนร่วมทีม AI ที่ทำงานสรุปผลอัตโนมัติในแต่ละคืนด้วย สำหรับข้อมูลเพิ่มเติม ดู โฟลว์ OAuth ของแอปอิสระ และ โฟลว์ในนามของผู้ใช้

สำหรับรายละเอียดเกี่ยวกับสูตรโทเค็นสำหรับแต่ละชุดของโมเดลข้อมูลประจำตัวและโฟลว์ โปรดดู ขั้นตอนการรับรองความถูกต้อง ในคู่มือการรวม

ข้อมูลประจำตัวของเอเจนต์ถูกผูกไว้กับ URL

{agentId} ใน URL ต้องมีค่าเท่ากับ appId ของแอปพลิเคชันที่เรียก (ซึ่งก็คือการอ้างสิทธิ์ appid หรือ azp ในโทเค็นของคุณ) เมื่อเกิดข้อไม่ตรงกัน ระบบจะส่งคืน 403 Forbidden สำหรับข้อมูลประจำตัวที่ได้มาจากแบบพิมพ์เขียว {agentId} คือ appId ของข้อมูลประจำตัวเอเจนต์ ไม่ใช่ appId ของแบบพิมพ์เขียว

นอกจากนี้ ทุกสแปนที่คุณส่งต้องตั้งค่า gen_ai.agent.id เป็น appId เดียวกัน เซิร์ฟเวอร์จะตรวจสอบตัวตนของเอเจนต์ที่อยู่ในส่วนข้อมูลกับเอเจนต์ที่ผ่านการรับรองแล้ว และจะปฏิเสธหากพบว่าไม่ตรงกัน ขั้นตอนนี้จะตรวจจับการผสมสแปนจากหลายเอเจนต์เข้าในคำขอเดียวโดยไม่ได้ตั้งใจ

ขอบเขต (แบบได้รับมอบหมาย) หรือ บทบาทแอป (แอปพลิเคชัน) คือสิทธิ์ที่ระบุชื่อที่ Microsoft Entra สร้างลงในโทเค็นการเข้าถึง สำหรับการวัดและส่งข้อมูลทางไกลของ Agent 365 สิทธิ์คือ Agent365.Observability.OtelWrite บนทรัพยากร Agent 365 Observability (ผู้ชม 9b975845-388f-4429-889e-eab1ef63949c)

ชื่อสิทธิ์เดียวกันถูกกำหนดไว้ใน ทั้งสอง ประเภท:

  • บทบาทแอปสำหรับโฟลว์แบบอัตโนมัติ (S2S / ข้อมูลประจำตัวไคลเอ็นต์) ไปอยู่ในการอ้างสิทธิ์ roles เลือกโดย <resource>/.default
  • ขอบเขตที่ได้รับมอบหมาย สำหรับโฟลว์ OBO ไปอยู่ในการอ้างสิทธิ์ scp เลือกโดย <resource>/Agent365.Observability.OtelWrite (หรือ <resource>/.default)

Agent 365 ยังเปิดเผยสิทธิ์ในการอ่าน Agent365.Observability.OtelRead ซึ่งใช้โดยผู้ปฏิบัติงานที่สืบค้นข้อมูลการวัดและส่งข้อมูลทางไกลของ Agent 365 คู่ค้าส่วนใหญ่ไม่จำเป็นต้องใช้ เอกสารเหล่านี้ครอบคลุมเฉพาะการนำเข้าเท่านั้น

การเพิ่มสิทธิ์ลงในแอปของคุณ

  • สำหรับการลงทะเบียนแอป Microsoft Entra มาตรฐาน: ในพอร์ทัล Azure ให้เพิ่ม Agent365.Observability.OtelWrite (บทบาทแอปสำหรับ S2S, ขอบเขตสำหรับผู้รับมอบสิทธิ์) ภายใต้ สิทธิ์ API บนการลงทะเบียนแอปของเอเจนต์
  • สำหรับ Blueprint: เอเจนต์ที่สร้างขึ้นจากแบบพิมพ์เขียวข้อมูลประจำตัวของเอเจนต์ ID เอเจนต์ของ Microsoft Entra จะสืบทอดสิทธิ์ OAuth ที่กำหนดไว้ในแบบพิมพ์เขียวดังนั้นผู้ดูแลระบบผู้เช่าจึงจัดเตรียมสิทธิ์ล่วงหน้าหนึ่งครั้ง อินสแตนซ์ของเอเจนต์แต่ละตัวที่สร้างขึ้นจากแบบพิมพ์เขียวนั้นจะได้รับสิทธิ์เหล่านี้โดยอัตโนมัติ ดู กำหนดค่าสิทธิ์ที่สืบทอดได้สำหรับแบบพิมพ์เขียวข้อมูลประจำตัวของเอเจนต์

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

หากไม่ได้ให้ความยินยอม การขอรับโทเค็นจะล้มเหลวด้วย AADSTS65001 ("ผู้ใช้หรือผู้ดูแลระบบไม่ได้ให้ความยินยอม") หรือโทเค็นจะออกโดยไม่มีการอ้างสิทธิ์ roles / scp และปลายทางการนำเข้าจะปฏิเสธคำขอด้วย 403

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

ขีดจำกัดและเงื่อนไขการทิ้งข้อมูล

การทราบขีดจำกัดเหล่านี้ล่วงหน้าจะช่วยป้องกันปัญหาไม่คาดคิดระหว่างการผสานรวม – ส่วนใหญ่จะเงียบ (API ยอมรับคำขอ แต่ข้อมูลจะไม่ปรากฏที่ปลายทาง)

ขีดจำกัดระดับสาย:

  • api-version=1 ต้องมีในทุกคำขอ
  • ขนาดเนื้อหาคำขอสูงสุดคือ 1 MB คำขอที่มีขนาดใหญ่กว่าจะได้รับ 413 Payload Too Large
  • สองเส้นทางมีข้อจำกัดอัตราที่แยกจากกัน บน 429 ให้ปฏิบัติตาม Retry-After (ตั้งค่าเป็น 1 วินาที) และถอยกลับด้วย jitter

การตอบสนองข้อผิดพลาด:

  • 403 Forbidden--โทเค็นขาดบทบาท/ขอบเขตของแอปที่จำเป็น หรือ {agentId} ใน URL ไม่ตรงกับ appid / azp ของโทเค็นของคุณ
  • 413 Payload Too Large--เนื้อหาเกิน 1 MB
  • 429 Too Many Requests--ถึงขีดจำกัดอัตรา ปฏิบัติตาม Retry-After: 1 และถอยกลับด้วย jitter

เงื่อนไขการตัดทิ้ง (คำขอที่ HTTP ยอมรับ แต่ข้อมูลไม่ปรากฏในระบบปลายทาง):

# เงื่อนไข พฤติกรรม
1 สแปน gen_ai.operation.name ขาดหายไปหรือไม่อยู่ใน {invoke_agent, execute_tool, chat, output_messages} การทิ้งข้อมูลแต่ละสแปน ปรากฏใน partialSuccess.rejectedSpans + errorMessage
2 ไม่มีผู้ใช้รายใดในผู้เช่าลูกค้าที่ได้รับมอบหมายสิทธิ์การใช้งาน Microsoft 365 E7 หรือ Microsoft Agent 365 ผู้ใช้อย่างน้อยหนึ่งรายในผู้เช่าต้องได้รับการมอบหมายสิทธิ์การใช้งาน (การมี SKU อยู่ในผู้เช่าเพียงอย่างเดียวไม่เพียงพอ – การมอบหมายจะเป็นการเริ่มเวิร์กโฟลว์แบ็กเอนด์ของ Defender) ผู้ใช้ที่ได้รับสิทธิ์การใช้งานไม่จำเป็นต้องเป็นบุคคลที่เรียกใช้งานเอเจนต์เอง คำขอทั้งหมดถูกทิ้งโดยไม่มีการแจ้งเตือน ส่งกลับ 200 { "partialSuccess": null }

200 OK ไม่ใช่หลักฐานการนำเข้า ใช้ขั้นตอนการตรวจสอบเพื่อยืนยันว่าข้อมูลถูกส่งถึงแล้ว

ช่องทางที่ข้อมูลของคุณปรากฏ

เมื่อได้รับการยอมรับแล้ว ช่วงของคุณจะปรากฏในประสบการณ์ที่แสดงต่อลูกค้าสามแบบ ทั้งสามขึ้นอยู่กับสแปน invoke_agent ที่ถูกต้องที่รากของการรัน การรันที่มีเฉพาะสแปน chat / execute_tool / output_messages สามารถสืบค้นได้ใน Defender advanced hunting (ตาราง CloudAppEvents) แต่จะไม่ปรากฏในอินเทอร์เฟซอื่น ๆ ด้านล่าง

Microsoft Defender กิจกรรมของเอเจนต์ (invoke_agent, execute_tool, chat) ปรากฏในมุมมองกิจกรรมของเอเจนต์ ผู้ดูแลระบบผู้เช่าและนักวิเคราะห์ความปลอดภัยสามารถตรวจสอบรายละเอียดการดำเนินการแต่ละรายการ เครื่องมือแต่ละรายการ และการเรียกใช้การอนุมานแต่ละรายการ มุมมองกิจกรรมของเอเจนต์อ้างอิงจาก invoke_agentสแปน หากไม่มีสแปน การรันจะไม่ปรากฏในมุมมองนั้น แม้ว่าช่วงย่อยจะยังสามารถค้นหาได้ผ่าน advanced hunting มุมมอง advanced-hunting - CloudAppEvents - รองรับทุกการดำเนินการ: ActionType สะท้อนถึงการดำเนินการ (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) และฟิลด์ต่อสแปนอยู่ภายใน RawEventData ชื่อฟิลด์ที่ลูกค้ามองเห็นได้จับคู่โดยตรงกับแอตทริบิวต์สแปนที่คุณส่ง: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id และอื่นๆ ดู การอ้างอิงแอตทริบิวต์ สำหรับการแมปทั้งหมด

ศูนย์การจัดการ Microsoft 365 กิจกรรมของเอเจนต์ยังปรากฏใน มุมมองสินค้าคงคลังเอเจนต์และมุมมองด้านความปลอดภัย ที่ผู้ดูแลระบบผู้เช่าใช้เพื่อบริหารจัดการเอเจนต์ในผู้เช่าของตน ศูนย์การจัดการนำเข้า invoke_agent แถวเท่านั้น: เอเจนต์ที่ไม่มีการวัดและส่งข้อมูลทางไกล invoke_agent จะไม่ปรากฏในสินค้าคงคลัง และการเรียกใช้ที่ปล่อยเฉพาะ chat / execute_tool / output_messages จะมองไม่เห็นที่นี่ แอตทริบิวต์ที่ศูนย์การจัดการอ่าน (รหัสเอเจนต์ ชื่อเอเจนต์ รหัสพิมพ์เขียว ข้อมูลประจำตัวผู้โทร รหัสการสนทนา ช่องทาง สถานะข้อผิดพลาด) ทั้งหมดมาจากสแปน invoke_agent

Microsoft Purview กิจกรรมของเอเจนต์ยังถูกนำเสนอแก่ผู้ดูแลระบบด้านการปฏิบัติตามข้อบังคับใน Microsoft Purview ซึ่งพวกเขาสามารถกำหนดค่าการจัดการข้อมูลและกฎนโยบายสำหรับการทำงานของเอเจนต์ (การป้องกันการสูญหายของข้อมูล การเก็บรักษา การปฏิบัติตามข้อกำหนดของการสื่อสาร และอื่นๆ ที่คล้ายกัน) แอตทริบิวต์ที่นโยบาย Purview ใช้เป็นคีย์ (รหัสเอเจนต์ / รหัส Blueprint, ข้อมูลประจำตัวผู้โทร, การสนทนา / ช่องทาง, ข้อความคำขอและการตอบกลับ) ทั้งหมดมาจากสแปน invoke_agent และโหนดสืบทอด

ขั้นตอนถัดไป

  • การอ้างอิงแอตทริบิวต์ - รายละเอียดแต่ละแอตทริบิวต์ ข้อกำหนด และคำแนะนำการเลือกค่าของแต่ละแอตทริบิวต์
  • การแก้ไขปัญหา - การยืนยันการนําเข้า ข้อผิดพลาดทั่วไป และการตอบสนองต่อข้อผิดพลาด
  • Last updated on