이것이 에이전트 365의 인제스팅 파이프라인에서 사용하는 표준적인 속성별 명세입니다. 에이전트 365가 수집하는 모든 스팬 - Microsoft OpenTelemetry Distro, Agent 365 SDK, 또는 direct OTel를 통해 전송되는 모든 스팬 모두 반드시 이에 맞춰야 합니다. 각 항목에는 속성이 적용되는 연산 유형, 필수인지, 고급 헌팅 쿼리에서 값이 들어가는 필드 이름(존재하는 경우), 그리고 건너뛸 경우 어떤 영향이 있는지가 나열되어 있습니다.
SDK나 배포판을 사용할 경우, SDK가 이 속성을 자동으로 생성하고, 기본값을 덮어써야 할 때만 값 선택(Picking value ) 섹션이 적용됩니다. 직접 OTel 경로에 있다면 모든 속성을 수동으로 방출합니다; 이들을 요청으로 조립하는 방법은 통합 가이드를 참조하세요.
Attribute table
모든 값은 다음과 같이 전송됩니다. stringValue - 토큰 수는 ( "42" not 42)여야 하며; 포트는 ( "443" not 443)여야 합니다.
작전 레전드.IA, = invoke_agent ET, CH, = chatOM, = output_messagesAll = 모든 = execute_tool 연산에 적용됩니다.
Required legend.
- M: mandatory.
- M*¹: 신체화된 에이전트에게만 의무화됩니다(에이전트는 자체 Entra 에이전트 ID 사용자 계정을 가짐).
- M*²: 에이전트 간 통화에만 의무화됩니다.
-
M*³: 근간이 아닌 구간에만 의무화됨. 근에는
invoke_agent부모가 없습니다. - O*⁴: 선택 사항이며, 스팬 상태가 Error일 때만 의미가 있습니다.
- O: optional.
- 해당 없음: 내보내지 마세요. 에이전트 365가 자동으로 생성됩니다.
"RawEventData field" 열은Verifying inestion 파일의 표준 고급 헌팅 쿼리가 파싱하는 JSON 키를 CloudAppEvents.RawEventData 지정합니다. 빈 셀은 속성이 not 현재 CloudAppEvents에서 노출된다는 의미입니다—Agent 365가 인제스팅, 부모 해석, Microsoft Defender의 에이전트 활동 뷰에 사용하기 때문에 필수 열에 따라 여전히 출력해야 하지만, 오늘날 고급 헌팅에서는 직접 쿼리Microsoft Defender 불가능합니다.
Note
에이전트 365는 정적 레코드 필드(Id, UserTypeRecordTypeWorkloadVersion)와 생성된 요청/응답 ID를 자동으로 채웁니다.
| 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 (IA); AgentName (ET, CH) |
Defender/Admin Center에서는 이름이 없으면 GUID를 보여줘요. |
microsoft.a365.agent.blueprint.id |
All | M |
TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) |
설계도는 appId입니다. 블루프린트가 없는 표준 Entra 앱의 경우, 에이전트의 appId를 재사용하세요. 행정센터의 설계도 롤업이 그렇지 않으면 깨집니다. |
gen_ai.agent.description |
All | O | -- | 관리자 센터의 세부 정보 보기는 에이전트에게 비어 있습니다. |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) |
신 원 시스템에 대한 라벨과 에이전트가 Entra 등록이 없을 때 함께 microsoft.a365.agent.platform.id 사용하는 것. 자유 형식 텍스트; 당신의 신원 시스템을 고유하게 식별하는 값을 선택하세요. 에이전트가 Entra 등록을 가지고 있을 때는 생략하세요—에이전트 365가 자동으로 분류합니다. Microsoft 예약된 값은 사용하지 마세요(값 선택 참조). |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA, 최상위 수준 AlternateId포함); PlatformAgentId (ET, CH) |
비Entra 신원 시스템에서 에이전트의 고유 ID입니다. Free-form text. 와 함께 설정되었다 gen_ai.agent.type. 에이전트가 Entra 등록을 가지고 있을 때는 생략하세요. 값을 선택하기를 참조하세요. |
gen_ai.conversation.id |
All | M |
ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) |
실행을 위한 기본 조인 키입니다. 이 기능이 없으면 실행이 Defender 에이전트 활동 뷰나 관리자 센터에 나타나지 않습니다. |
microsoft.channel.name |
All | M |
ChannelName (IA, 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 (IA) |
텔레메트리를 방출하는 SDK나 서비스의 식별자. 아마도 자원 속성일 수 있습니다. |
client.address |
IA, ET, CH | M |
ClientIP (IA, ET) |
Caller IP. IP 기반 조사는 빈칸 경우 차단됩니다. |
server.address |
IA, ET, CH | M |
ServerAddress (IA, ET) |
서비스가 호출하는 엔드포인트입니다. |
server.port |
IA, ET, CH | M |
ServerPort (IA) |
문자열 인코딩(예: "443"). |
user.id |
IA | M | UserKey |
Microsoft Entra 인간 호출자의 객체 ID. "이 에이전트를 누가 운영했는가"는 없으면 하얀 상태입니다. |
user.email |
IA | O | UserId |
발신자의 UPN입니다. |
user.name |
IA | O | -- | 발신자의 이름을 표시하세요. |
gen_ai.input.messages |
IA, CH | M | -- | 요청 페이로드(JSON 문자열). 하위 분석을 위해 포획되었으나 고급 사냥에서는 아직 수면 위로 나오지 않았습니다. |
gen_ai.output.messages |
IA, CH, OM | M | -- | 응답 페이로드(JSON 문자열). |
gen_ai.execution.type |
IA | O | -- | , , HumanToAgentEventToAgent. 중 하나, Agent2Agent. |
microsoft.a365.agent.thought.process |
IA, CH | O | -- | 자유 텍스트 추론 / 사고의 연쇄. |
gen_ai.author.app.id |
OM | O | -- | Microsoft Entra 앱 ID는 에이전트를 작성하거나 생성한 애플리케이션입니다. |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. Defender 도구 사용 뷰가 없으면 비어 있습니다. |
gen_ai.tool.type |
ET | M | ToolType |
, functionPower Platform Connector, Knowledge SourceAPIbing_groundingMCP Servercode_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가 아닌 대체 ID용으로 예약되어 있습니다. |
gen_ai.caller.agent.type |
IA | N/A | -- | 에이전트 365가 자동 분류합니다. |
microsoft.agent.user.id |
IA, ET, CH | M*¹ |
TargetAgentUserKey (IA); UserKey (ET, CH) |
Microsoft Entra 에이전트 자신의 사용자 계정의 객체 ID. AI 팀원/구현된 요원에게 필수입니다. |
microsoft.agent.user.email |
IA, ET, 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) |
유닉스 에포크 나노스를 문자열로 사용하는 것. |
span.EndTimeUnixNano |
All | M |
CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) |
만약 누락되면 시간 계산이 불가능합니다. |
span.Status.Message |
All | O*⁴ |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
실패한 실행의 근본 원인이 없으면 비어 있습니다. |
span.Status.Code |
All | O*⁴ |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
오류가 없으면 오류 카테고리가 빈칸입니다. |
Note
당신이 내보내는 여러 속성(예: 도구 인수/결과, 모델 매개변수, 채널 딥링크 등)은 Agent 365에서 받아들여지고 하위 Microsoft Defender 뷰에서 사용하지만, 아직 CloudAppEvents.RawEventData JSON 키로 노출되지는 않습니다. 어쨌든 필수 열에 따라 설정하세요 - 앞으로 사냥 페이로드에 추가될 수도 있습니다.
자연스러운 값이 없을 때 선택하는 것
일부 필수 속성은 에이전트의 아키텍처에 존재하지 않을 수 있는 개념을 설명합니다. 자연 값이 없으면 대신 설정할 수 있는 값을 알려드립니다. 필수 필드를 비워두지 마세요—0만 있는 GUID라도 일부 고객 경험에서 플레이를 숨길 수 있습니다.
| 질문 / 시나리오 | Field(s) | 설정할 수 있는 것 |
|---|---|---|
| 제 에이전트는 표준 Entra 앱 등록(Entra 에이전트 ID 설계도에서 만들어진 것이 아닙니다). | gen_ai.agent.id |
Entra 앱의 앱입니다. |
| ↑ 같은 시나리오 | microsoft.a365.agent.blueprint.id |
(에이전트의 appId)와 gen_ai.agent.id 같은 값을 재사용하세요. 스키마는 빈 값이 아닌 값을 요구합니다; 설계도가 없을 때는 에이전트 앱ID를 재사용하는 것이 안전한 기본값입니다. |
| 제 에이전트는 Entra 에이전트 ID 설계도로 만들어졌는데, 같은 설계도에서 하나 이상의 에이전트 정체성을 만들어냅니다. | gen_ai.agent.id |
에이전트 아이덴티티의 appId ( 인스턴스 appId, 블루프린트의 appId가 아닙니다). |
| ↑ 같은 시나리오 | microsoft.a365.agent.blueprint.id |
설계도는 appId입니다. 동일한 설계도에서 발행된 모든 인스턴스는 이 값을 공유합니다. |
| 발신자는 다른 상담원이 아니라 인간 사용자입니다. | 모든 microsoft.a365.caller.agent.* 것과 gen_ai.caller.agent.* 속성 |
Omit. 요원 간 상황에서만 의무화됩니다. |
| 에이전트 간 관계에서: 호출 에이전트는 표준 Entra 앱(청사진은 없음)입니다. | microsoft.a365.caller.agent.blueprint.id |
발신 에이전트의 appId를 재사용하세요. |
| 제 에이전트는 AI 팀원이 아니 에요 - 세입자 내에 자체 사용자 계정이 없거든요. | 모든 microsoft.agent.user.* 속성 |
Omit. 상담원이 자체 Entra 에이전트 ID 사용자 계정을 가지고 있을 때만 의무입니다. |
| 제 에이전트는 세션에 대해 한 번의 실행 이상을 개념하지 않습니다. | microsoft.session.id |
선택 사항입니다 - 생략하세요. 각 런을 별도의 세션으로 만들고 싶다면, 각 런별로 GUID로 설정하세요. |
| 제 에이전트는 대화(원샷, 무상태 대화)라는 개념이 전혀 없습니다. | gen_ai.conversation.id |
매번 새로운 GUID를 생성하세요. 이 필드는 필수입니다; 이 기능을 건너뛰면 Defender 에이전트 활동 뷰와 Microsoft 365 관리 센터에서 실행이 사라집니다. |
| 발신자는 IP가 없습니다(예: 자율 예약 트리거). | client.address |
자신이 제어하는 안정적인 자리 표시자를 사용하세요(예: "0.0.0.0"). 이 필드는 필수입니다; 빈 값은 IP 기반 조사 피벗에서 런을 제거합니다. |
| 에이전트는 진행 중(in-process) 상태에서 실행됩니다; 별도의 '서버'가 호출되는 것도 아닙니다. | 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 상태를 (숫자 코드 1)로 OK 설정하고 메시지를 생략하세요. 파이프라인은 상태가 일 Error때만 이 필드들을 참조합니다. |
| 제 에이전트는 Entra 등록이 없는 비 Entra 신원 시스템을 사용합니다. |
microsoft.a365.agent.platform.id 및 gen_ai.agent.type |
두 가지 모두 모든 경간에 설치하세요.
platform.id 는 당신의 신원 시스템 내 에이전트의 고유 ID입니다; agent.type 는 어떤 정체성 체계인지 식별하는 짧은 라벨입니다. 두 버전 모두 자유 형식의 텍스트니, 본인의 시스템에 맞는 것을 선택하세요.
Microsoft 예약된 타입 값은 사용하지 마세요: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (이 값들은 내부 Microsoft 표면에 예약됨). 인증하는 호출 앱은 이 경로를 사용하려면 Entra 등록이 필요합니다 - 대체 ID 쌍은 발신자가 아니라 타겟 에이전트를 나타냅니다. |
어떤 가치를 넣 microsoft.channel.name어야 할까요? |
microsoft.channel.name |
에이전트가 달리는 표면. Defender와 Admin Center는 키를 문자 그대로 필터링하기 때문에, 짧고 안정적인 소문자 토큰을 사용하세요. 오늘날 표준 값은 와 이며msteams; 일반적인 고객 면에서는 , office, sharepoint, 또는 <your-product-name>를 사용합니다web.outlook 한 값을 정해서 그대로 하세요 - 공구는 msteams와 Microsoft Teams를 같은 채널로 조화시킬 수 없습니다. |
설정 gen_ai.agent.type해야 할까요? |
gen_ai.agent.type |
설정도 하고 microsoft.a365.agent.platform.id 있을 때(예: 에이전트가 Entra 등록이 없을 경우) 적용할 수 있습니다. 두 사람은 요원 365에게 요원이 어떤 신원 체계 출신인지 알려준다. 당신의 정체 성 체계를 고유하게 식별하는 짧은 명칭을 선택하세요.
CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom - 이 값들은 내부 Microsoft용으로 예약되어 있습니다. Entra 등록 대리인의 경우, 해당 필드를 생략하세요; 에이전트 365가 다시 채워. |
내 스팬에 어떤 OTLP kind 를 설정해야 할까요? |
span.kind |
원시 enum 문자열이 아닌 정수 enum 값을 사용하세요 - 1 (), (SERVER),CLIENT23 (), 4 (PRODUCER), (). 5CONSUMERINTERNAL 에이전트 365는 이 중 어느 것도 받아들이며, 에서 고객 눈에 보이는 동작 kind을 도출하지 않으므로 1 , (INTERNAL)는 모든 구간에 안전한 기본값입니다. 만약 친절한 표현이 호출 형태를 반영하길 원한다면, INTERNAL 포(forCLIENToutput_messages / invoke_agent)와 포(forchat / execute_tool)가 합리적입니다. |