การอ้างอิงแอตทริบิวต์ความสามารถในการสังเกตการณ์ของเอเจนต์ 365

นี่คือข้อมูลจําเพาะแบบแอตทริบิวต์ตามแอตทริบิวต์ตามบัญญัติที่ใช้โดยไปป์ไลน์การนําเข้าของ Agent 365 ทุกช่วงที่นําเข้าโดย Agent 365 ไม่ว่าจะปล่อยโดย Microsoft OpenTelemetry Distro, Agent 365 SDK หรือส่งผ่าน direct OTel จะต้องเป็นไปตามนั้น แต่ละรายการจะแสดงรายการประเภทการดําเนินการที่แอตทริบิวต์นําไปใช้ ไม่ว่าจะเป็นข้อบังคับ ชื่อฟิลด์ที่ค่าของคุณปรากฏขึ้นสําหรับการค้นหาขั้นสูง (หากมีอยู่) และผลกระทบหากคุณข้ามไป

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

Attribute table

ค่าทั้งหมดจะถูกส่งเป็น stringValue - จํานวนโทเค็นต้องเป็น "42" (not 42); พอร์ตต้องเป็น "443" (not 443)

ตํานานปฏิบัติการIA = invoke_agent, ET, = execute_toolCH, = chatOM = output_messages, All = ใช้กับทุกการดําเนินการ

Required legend.

  • M: mandatory.
  • M*¹: บังคับสําหรับเอเจนต์ที่เป็นตัวเป็นตนเท่านั้น (เอเจนต์มีบัญชีผู้ใช้ ID เอเจนต์ของ Entra ของตัวเอง)
  • M*²: บังคับใช้สําหรับการโทรระหว่างตัวแทนกับตัวแทนเท่านั้น
  • M*³: บังคับสําหรับช่วงที่ไม่ใช่รูทเท่านั้น ราก invoke_agent ไม่มีพ่อแม่
  • O*⁴: ไม่บังคับ มีความหมายเฉพาะเมื่อสถานะช่วงเป็นข้อผิดพลาด
  • O: optional.
  • N/A: อย่าปล่อย เอเจนต์ 365 จะเติมข้อมูลอัตโนมัติ

คอลัมน์ "เขตข้อมูล RawEventData" ตั้งชื่อคีย์ JSON ภายใน CloudAppEvents.RawEventData ที่คิวรีการค้นหาขั้นสูงตามรูปแบบบัญญัติในการ แยกวิเคราะห์การนําเข้า การตรวจสอบ เซลล์ว่างหมายความว่าแอตทริบิวต์เป็น not ที่เปิดเผยใน CloudAppEvents วันนี้ คุณยังคงควรปล่อยแอตทริบิวต์ (ตามคอลัมน์ จําเป็น) เนื่องจาก Agent 365 ใช้แอตทริบิวต์สําหรับการนําเข้า การแก้ปัญหาหลักและมุมมองกิจกรรมของเอเจนต์ของ Microsoft Defender แต่ไม่สามารถสืบค้นได้โดยตรงจากการล่าสัตว์ขั้นสูง Microsoft Defender ในปัจจุบัน

Note

เอเจนต์ 365 จะเติมข้อมูลในฟิลด์เรกคอร์ดแบบคงที่ (Id, , RecordType, Workload, UserType) Versionและรหัสคําขอ/การตอบกลับที่สร้างขึ้นโดยอัตโนมัติ

Attribute Applies to Required RawEventData field หมายเหตุ / ผลกระทบหากขาดหายไป
gen_ai.operation.name All M Operation หนึ่งใน invoke_agent, execute_tool, , chat. output_messages ช่วงลดลงหากหายไปหรือไม่รู้จัก
microsoft.tenant.id All M OrganizationId URL {tenantId} เป็นที่เชื่อถือได้ หากคุณตั้งค่านี้และไม่เห็นด้วยคําขอจะถูกปฏิเสธ (403)
gen_ai.agent.id All M TargetAgentId (IA ระดับ AgentIdบนสุดด้วย); AgentId (ET, CH) appId ของแอปการโทร ต้องตรงกับ URL {agentId} และแอปที่ตรวจสอบสิทธิ์แล้ว ไม่ตรงกันจะส่งกลับ 403
gen_ai.agent.name All M TargetAgentName (ไอเอ); AgentName (ET, CH) Defender / ศูนย์ผู้ดูแลระบบจะแสดง GUID ดิบแทนชื่อหากขาดหายไป
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (ไอเอ); AgentBlueprintId (ET, CH) appId ของพิมพ์เขียว สําหรับแอป Entra มาตรฐานที่ไม่มีพิมพ์เขียว ให้ใช้ appId ของตัวแทนซ้ํา การรวบรวมพิมพ์เขียวในศูนย์การจัดการจะหยุดพัก
gen_ai.agent.description All O -- มุมมองรายละเอียดในศูนย์การจัดการว่างเปล่าสําหรับตัวแทน
gen_ai.agent.type All O PlatformTargetAgentType (ไอเอ); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (ช) ป้ายกํากับสําหรับ ระบบข้อมูลประจําตัวของคุณ จับคู่กับ microsoft.a365.agent.platform.id เมื่อตัวแทนไม่มีการลงทะเบียน Entra ข้อความรูปแบบอิสระ เลือกค่าที่ระบุระบบข้อมูลประจําตัวของคุณโดยเฉพาะ ละเว้นเมื่อตัวแทนมีการลงทะเบียน Entra - ตัวแทน 365 จะจัดประเภทอัตโนมัติ อย่าใช้ค่าที่สงวนไว้ Microsoft (ดู การเลือกค่า)
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA ระดับ AlternateIdบนสุดด้วย); PlatformAgentId (ET, CH) รหัสเฉพาะของตัวแทนในระบบข้อมูลประจําตัวที่ไม่ใช่ Entra ของคุณ Free-form text. ตั้งค่าร่วมกับ gen_ai.agent.type. ละเว้นเมื่อตัวแทนมีการลงทะเบียน Entra ดู การเลือกค่า
gen_ai.conversation.id All M ConversationId (ไอเอ, อีที); CopilotEventData.ConversationId / CopilotEventData.ThreadId (ช) คีย์การรวมหลักสําหรับการรัน หากไม่มี การเรียกใช้จะไม่ปรากฏในมุมมองกิจกรรมของตัวแทน Defender หรือศูนย์การจัดการ
microsoft.channel.name All M ChannelName (ไอเอ, ET) พื้นผิวที่ตัวแทนวิ่งเข้าไป ใช้โทเค็นตัวพิมพ์เล็กสั้น ค่าบัญญัติที่ใช้โดยตัวกรอง Defender / ศูนย์การจัดการในปัจจุบันคือ msteams และ outlook สตริงที่กําหนดเอง (ตัวอย่างเช่น web, <your-product-name>) ได้รับการยอมรับ แต่จะไม่หมุนในตัวกรองช่องทางที่มีอยู่แล้วภายใน ค่าเท่ากันในทุกช่วง ดู การเลือกค่า
microsoft.channel.link All O -- Channel deep-link.
microsoft.session.id All O SessionIdentity เซสชันจะว่างเปล่าหากขาดหายไป
microsoft.session.description All O -- Session description.
microsoft.conversation.item.link All O -- ลิงก์ตรงไปยังข้อความ
correlation.id All O -- Cross-service tracing. ไม่ปรากฏในการล่าสัตว์ขั้นสูงในปัจจุบัน
operation.source All O InvokeSource (ไอเอ) ตัวระบุสําหรับ SDK / บริการที่ปล่อยการวัดและส่งข้อมูลทางไกล อาจเป็นแอตทริบิวต์ทรัพยากร
client.address ไอเอ, อีที, CH M ClientIP (ไอเอ, ET) Caller IP. การตรวจสอบตาม IP ถูกบล็อกหากว่างเปล่า
server.address ไอเอ, อีที, CH M ServerAddress (ไอเอ, ET) ปลายทางบริการของคุณกําลังโทร
server.port ไอเอ, อีที, CH M ServerPort (ไอเอ) เข้ารหัสสตริง (เช่น "443")
user.id IA M UserKey รหัสออบเจ็กต์ Microsoft Entra ของผู้โทรที่เป็นมนุษย์ "ใครเป็นผู้บริหารตัวแทนนี้" จะว่างเปล่าหากไม่มีมัน
user.email IA O UserId UPN ของผู้โทร
user.name IA O -- ชื่อที่แสดงของผู้โทร
gen_ai.input.messages IA, CH M -- เพย์โหลดคําขอ (สตริง JSON) จับเพื่อการวิเคราะห์ปลายน้ํา แต่ยังไม่ปรากฏในการล่าสัตว์ขั้นสูง
gen_ai.output.messages IA, CH, โอเอ็ม M -- เพย์โหลดการตอบสนอง (สตริง JSON)
gen_ai.execution.type IA O -- หนึ่งใน HumanToAgent, Agent2Agent, . EventToAgent
microsoft.a365.agent.thought.process IA, CH O -- การให้เหตุผลข้อความอิสระ / ห่วงโซ่ความคิด
gen_ai.author.app.id OM O -- รหัสแอป Microsoft Entra ของแอปพลิเคชันที่เขียน/สร้างตัวแทน
gen_ai.tool.name ET M ToolName Tool name. มุมมองการใช้เครื่องมือของ Defender จะว่างเปล่าหากไม่มี
gen_ai.tool.type ET M ToolType หนึ่งใน function, Power Platform Connector, , APIMCP Server, Knowledge Source, bing_grounding, code_interpreter, . file_search
gen_ai.tool.call.id ET M ToolId ตัวระบุสําหรับการเรียกใช้เครื่องมือนี้
gen_ai.tool.call.arguments ET M -- อาร์กิวเมนต์เครื่องมือ (สตริง JSON) ถูกจับแต่ยังไม่ปรากฏในการล่าสัตว์ขั้นสูง
gen_ai.tool.call.result ET M -- ผลลัพธ์ของเครื่องมือ (สตริง JSON)
gen_ai.tool.description ET O ToolDescription Tool description.
gen_ai.tool.server.name ET O -- ชื่อโฮสต์เซิร์ฟเวอร์เครื่องมือ ตั้งค่าแอตทริบิวต์นี้สําหรับเครื่องมือ MCP
gen_ai.request.model CH M -- ชื่อรุ่น (เช่น gpt-4o) ถูกจับแต่ยังไม่ปรากฏในการล่าสัตว์ขั้นสูง
gen_ai.provider.name CH M -- ชื่อผู้ให้บริการ (เช่น openai)
gen_ai.usage.input_tokens CH O -- จํานวนโทเค็นอินพุต เข้ารหัสสตริง
gen_ai.usage.output_tokens CH O -- จํานวนโทเค็นเอาต์พุต เข้ารหัสสตริง
gen_ai.response.finish_reasons CH O -- Finish reason(s).
microsoft.a365.caller.agent.id IA M*² -- ตัวแทนการโทร appId จําเป็นสําหรับตัวแทนต่อตัวแทน
microsoft.a365.caller.agent.name IA M*² -- ชื่อที่แสดงของตัวแทนการโทร
microsoft.a365.caller.agent.blueprint.id IA M*² AgentBlueprintId รหัสแอปพิมพ์เขียวของตัวแทนการโทร จําเป็นสําหรับ A2A ที่เป็นตัวเป็นตน
microsoft.a365.caller.agent.user.id IA M*² -- ID ผู้ใช้ของตัวแทนการโทร
microsoft.a365.caller.agent.user.email IA M*² -- โทรหาตัวแทน UPN
microsoft.a365.caller.agent.platform.id IA N/A -- สงวนไว้สําหรับบัตรประจําตัวสํารองที่ไม่ใช่ Entra
gen_ai.caller.agent.type IA N/A -- เอเจนต์ 365 จะจัดประเภทอัตโนมัติ
microsoft.agent.user.id ไอเอ, อีที, CH M*¹ TargetAgentUserKey (ไอเอ); UserKey (ET, CH) รหัสวัตถุ Microsoft Entra ของบัญชีผู้ใช้ของตัวแทนเอง จําเป็นสําหรับเพื่อนร่วมทีม AI / ตัวแทนที่เป็นตัวเป็นตน
microsoft.agent.user.email ไอเอ, อีที, CH O*¹ UserId (ET, CH) UPN ของบัญชีผู้ใช้ของตัวแทน
span.SpanId All M OpId OTel SDK ปล่อยสิ่งนี้
span.ParentSpanId All M*³ ParentId จําเป็นสําหรับช่วงที่ไม่ใช่รูทเท่านั้น ราก invoke_agent ไม่มี
span.StartTimeUnixNano All M ระดับ TimeGenerated บนสุด (รวมถึง CreationTime ใน RawEventData) Unix epoch nanos เป็นสตริง
span.EndTimeUnixNano All M CompletionTime (ไอเอ, อีที); CopilotEventData.CompletionTime (ช) ไม่สามารถคํานวณระยะเวลาได้หากขาดหายไป
span.Status.Message All O*⁴ ErrorMessage (ไอเอ, อีที); CopilotEventData.ErrorMessage (ช) สาเหตุหลักของการรันที่ล้มเหลวจะว่างเปล่าหากขาดหายไป
span.Status.Code All O*⁴ ErrorType (ไอเอ); CopilotEventData.ErrorType (ช) หมวดหมู่ข้อผิดพลาดว่างเปล่าหากหายไป

Note

แอตทริบิวต์หลายอย่างที่คุณปล่อยออกมา (เช่น อาร์กิวเมนต์เครื่องมือ/ผลลัพธ์ พารามิเตอร์แบบจําลอง และลิงก์ตรงของช่องทาง) ได้รับการยอมรับโดย Agent 365 และใช้โดยมุมมอง Microsoft Defender ดาวน์สตรีม แต่ยังไม่ได้เปิดเผยเป็นคีย์ JSON CloudAppEvents.RawEventData ตั้งค่าตามคอลัมน์ Required อยู่ดี - อาจถูกเพิ่มลงในเพย์โหลดการล่าสัตว์ในรุ่นต่อๆ ไป

การเลือกค่าเมื่อคุณไม่มีค่าธรรมชาติ

แอตทริบิวต์ที่จําเป็นบางอย่างอธิบายแนวคิดที่อาจไม่มีอยู่ในสถาปัตยกรรมของตัวแทนของคุณ หากไม่มีคุณค่าตามธรรมชาติ ให้ตั้งค่าแทน อย่าปล่อยให้ฟิลด์บังคับว่างเปล่า แม้แต่ GUID ศูนย์ทั้งหมดก็สามารถซ่อนการวิ่งของคุณจากประสบการณ์ที่ต้องเผชิญหน้ากับลูกค้า

คําถาม / สถานการณ์ Field(s) สิ่งที่ต้องตั้งค่า
ตัวแทนของฉันเป็น การลงทะเบียนแอป Entra มาตรฐาน (ไม่ได้สร้างจากพิมพ์เขียว ID เอเจนต์ของ Entra) gen_ai.agent.id appId ของแอป Entra
↑ สถานการณ์เดียวกัน microsoft.a365.agent.blueprint.id ใช้ค่าเดียวกันซ้ํากับ gen_ai.agent.id (appId ของตัวแทน) สคีมาต้องการค่าที่ไม่ว่างเปล่า การนํา appId ตัวแทนกลับมาใช้ใหม่เป็นค่าเริ่มต้นที่ปลอดภัยเมื่อไม่มีพิมพ์เขียว
เอเจนต์ของฉันสร้างจากพิมพ์เขียว ซึ่งเป็นตัวตนของเอเจนต์หนึ่งตัวหรือหลายตัวที่สร้างขึ้นจากพิมพ์เขียวเดียวกัน gen_ai.agent.id appId ของข้อมูลประจําตัวของตัวแทน (appId ของอินสแตนซ์ ไม่ใช่ของพิมพ์เขียว)
↑ สถานการณ์เดียวกัน microsoft.a365.agent.blueprint.id appId ของพิมพ์เขียว อินสแตนซ์ทั้งหมดที่สร้างขึ้นจากพิมพ์เขียวเดียวกันมีค่านี้ร่วมกัน
ผู้โทรเป็นผู้ใช้ที่เป็นมนุษย์ ไม่ใช่ตัวแทนอื่น ทั้งหมด microsoft.a365.caller.agent.* และ gen_ai.caller.agent.* แอตทริบิวต์ Omit. บังคับเฉพาะในสถานการณ์ระหว่างตัวแทนต่อตัวแทนเท่านั้น
ในตัวแทนต่อตัวแทน: ตัวแทนที่โทรเป็นแอป Entra มาตรฐาน (ไม่มีพิมพ์เขียว) microsoft.a365.caller.agent.blueprint.id ใช้ รหัสแอปของตัวแทนการโทรซ้ํา
ตัวแทนของฉัน ไม่ใช่เพื่อนร่วมทีม AI - ไม่มีบัญชีผู้ใช้ของตัวเองในผู้เช่า แอตทริบิวต์ทั้งหมดmicrosoft.agent.user.* Omit. บังคับก็ต่อเมื่อตัวแทนมีบัญชีผู้ใช้ ID เอเจนต์ของ Entra ของตนเอง
ตัวแทนของฉันไม่มีแนวคิดเกี่ยวกับเซสชันนอกเหนือจากการวิ่งเพียงครั้งเดียว microsoft.session.id ไม่บังคับ - ละเว้น หากคุณต้องการให้การเรียกใช้แต่ละครั้งเป็นเซสชันของตัวเอง ให้ตั้งค่าเป็น GUID ต่อการเรียกใช้
ตัวแทนของฉันไม่มีแนวคิดเกี่ยวกับการสนทนา (นัดเดียว ไร้สัญชาติ) gen_ai.conversation.id สร้าง GUID ใหม่ต่อการเรียกใช้ ฟิลด์เป็นข้อบังคับ การข้ามจะเป็นการลบการเรียกใช้จากมุมมองกิจกรรมของตัวแทน Defender และศูนย์การจัดการ ศูนย์การจัดการ Microsoft 365
ผู้โทรไม่มี IP (ตัวอย่างเช่น ทริกเกอร์ตามกําหนดการอัตโนมัติ) client.address ใช้ตัวยึดตําแหน่งที่เสถียรที่คุณควบคุม (ตัวอย่างเช่น "0.0.0.0") ฟิลด์เป็นข้อบังคับ ค่าว่างจะลบการเรียกใช้ออกจาก Pivot การตรวจสอบตาม IP
ตัวแทนทํางานในกระบวนการ ไม่มีการเรียก "เซิร์ฟเวอร์" แยกต่างหาก server.address / server.port ใช้ชื่อโฮสต์ของเครื่องที่เรียกใช้เอเจนต์ (ตัวอย่างเช่น myagent.example.com) และพอร์ตที่ปลายทางของคุณฟัง จําเป็นแม้ว่าจะไม่มีบริการดาวน์สตรีมแยกต่างหากก็ตาม
ช่วงของฉัน chat ไม่มีการใช้โทเค็นแบบจําลอง gen_ai.usage.input_tokens / gen_ai.usage.output_tokens ไม่บังคับ - ละเว้น หากคุณมีจํานวนโดยประมาณ ให้ส่งเป็นstringValue
ช่วงของฉันไม่มีข้อผิดพลาดที่จะรายงาน span.Status.Message, span.Status.Code ตั้งค่าสถานะ OTel เป็น OK (รหัสตัวเลข 1) และละเว้นข้อความ ไปป์ไลน์จะดูฟิลด์เหล่านี้เมื่อสถานะเป็นError
ตัวแทนของฉันใช้ ระบบข้อมูลประจําตัวที่ไม่ใช่ Entra (ตัวแทนไม่มีการลงทะเบียน Entra) microsoft.a365.agent.platform.id และ gen_ai.agent.type ตั้งค่าทั้งสองอย่างในทุกช่วง platform.id คือรหัสเฉพาะของตัวแทนในระบบข้อมูลประจําตัว ของคุณagent.type เป็นป้ายกํากับสั้น ๆ ที่ระบุว่าระบบข้อมูลประจําตัวนั้น ทั้งสองเป็นข้อความรูปแบบอิสระ - เลือกอะไรก็ได้ที่เหมาะสมกับระบบของคุณ อย่าใช้ค่าประเภทที่สงวนไว้ Microsoft: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (ค่าเหล่านี้สงวนไว้สําหรับพื้นผิว Microsoft ภายใน) แอปการโทรที่คุณรับรองความถูกต้องยังคงต้องมีการลงทะเบียน Entra เพื่อใช้เส้นทางเหล่านี้ - คู่รหัสสํารองอธิบายถึงตัวแทน เป้าหมาย ไม่ใช่ผู้โทร
ฉันควรใส่ microsoft.channel.nameค่าอะไร ? microsoft.channel.name พื้นผิวที่ตัวแทนวิ่งเข้าไป ตัวกรอง Defender และศูนย์การจัดการจะปิดสตริงสัญพจน์ ดังนั้นให้ใช้โทเค็นตัวพิมพ์เล็กที่สั้น เสถียร วันนี้ค่าบัญญัติคือ msteams และ outlook;พื้นผิวที่หันหน้าเข้าหาลูกค้าทั่วไปยังใช้ web, office, , sharepointหรือ <your-product-name>. เลือกค่าเดียวและยึดติดกับค่านั้น - เครื่องมือไม่สามารถกระทบยอด msteams และ Microsoft Teams เป็นช่องสัญญาณเดียวกันได้
ฉันควรตั้งค่า gen_ai.agent.type? gen_ai.agent.type เฉพาะในกรณีที่คุณกําลังตั้งค่า microsoft.a365.agent.platform.id ด้วย (ตัวอย่างเช่น ตัวแทนของคุณไม่มีการลงทะเบียน Entra) ทั้งคู่บอก Agent 365 ว่าเจ้าหน้าที่มาจากระบบข้อมูลประจําตัวใด เลือกป้ายกํากับสั้น ๆ ที่ระบุระบบข้อมูลประจําตัว ของคุณ โดยเฉพาะ อย่าใช้ CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent หรือ Custom - ค่าเหล่านั้นจะถูกสงวนไว้สําหรับการใช้งาน Microsoft ภายใน สําหรับตัวแทนที่ลงทะเบียน Entra ให้ละเว้นฟิลด์ เอเจนต์ 365 ทดแทน
ฉันควรตั้งค่า OTLP kind ใดบนช่วงของฉัน span.kind ใช้ค่า enum จํานวนเต็ม ไม่ใช่สตริง enum proto - 1 (INTERNAL), 2 (SERVER), 3 (CLIENT), 4 (), (PRODUCER5CONSUMER) ตัวแทน 365 ยอมรับสิ่งเหล่านี้และไม่ได้รับพฤติกรรมที่ลูกค้ามองเห็นได้จาก kindดังนั้น 1 (INTERNAL) จึงเป็นค่าเริ่มต้นที่ปลอดภัยสําหรับทุกช่วง หากคุณต้องการให้สะท้อนรูปร่างINTERNALการโทร for / output_messagesinvoke_agentและ CLIENT for chat / execute_tool นั้นสมเหตุสมผล