これはAgent 365のインジェスションパイプラインで使われている標準的な属性ごとの仕様です。 エージェント365が取り込むすべてのスパンは、Microsoft OpenTelemetry Distro、Agent 365 SDK、またはdirect OTelを通じて送信されるものであっても、すべてこのスパンに準拠しなければなりません。 各エントリには、属性が適用される操作タイプ、必須かどうか、高度なハンティングクエリで値が入るフィールド名(存在する場合)、そしてスキップした場合の影響が記載されています。
SDKやDistroを使っている場合、SDKがこれらの属性を自動で出力し、 Picking value セクションはデフォルトを上書きする必要がある場合にのみ適用されます。 直接OTel経路を行っている場合は、すべての属性を手動で出力します。リクエストにまとめる方法については、 統合ガイドをご覧ください。
Attribute table
すべての値はstringValueとして送信されます- トークンカウントは"42"でなければならず(42ではなく)、ポートは"443"でなければならず(443でないこと)。
オペレーション・レジェンド。IA = invoke_agent、 ET = execute_tool、 CH = chat、 OM = output_messages、 All = すべての操作に適用されます。
Required legend.
- M: mandatory.
- M*¹:具身エージェントのみ必須(エージェントは独自のEntra エージェント IDユーザーアカウントを持つ)。
- M*²:エージェント間の通話のみが必須です。
-
M*³:根部以外のスパンのみが必須です。 根
invoke_agentには親がありません。 - O*⁴:オプションで、スパンの状態がエラーの場合のみ意味を持ちます。
- O: optional.
- 該当なし:放出しないでください。 エージェント365が自動で登場します。
「RawEventData field」列は、Verifying inestionの標準的なアドバンスドハンティングクエリが解析するCloudAppEvents.RawEventData内のJSONキーを指定しています。 空セルの場合は、その属性がnotであり、今日のCloudAppEventsで公開されていることを意味します。Agent 365は取り込み、親解決、Microsoft Defenderのエージェント活動ビューに使うため、Required欄に従っても発行する必要がありますが、現在ではAdvanced Huntingから直接クエリMicrosoft Defenderできません。
Note
エージェント365は静的レコードフィールド(Id、 RecordType、 Workload、 UserType、 Version)と生成されたリクエスト/レスポンス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) |
設計図は アプリです。 ブループリントがない標準的なEntraアプリでは、エージェントのappIdを再利用してください。 管理センターのブループリントロールアップはそうしないと壊れます。 |
gen_ai.agent.description |
All | O | -- | 管理者センターの詳細表示はエージェントの空白です。 |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA); PlatformAgentType (ET)、 CopilotEventData.PlatformAgentType (CH) |
Entra登録がない場合のID システムのラベルと、 microsoft.a365.agent.platform.id を組み合わせるもの。 自由形式のテキスト;自分のアイデンティティシステムを一意に識別できる値を選びましょう。 エージェントがEntra登録を持っている場合は省略してください――エージェント365が自動的に分類します。 Microsoftリバウンド値は使わないでください(Picking values参照)。 |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA、トップレベル AlternateIdも含めます); PlatformAgentId (ET、CH) |
エージェントの非Entra IDシステムにおける固有の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 | -- |
HumanToAgent、Agent2Agent、EventToAgent。 |
microsoft.a365.agent.thought.process |
IA, CH | O | -- | フリーテキストの推論/思考の連鎖。 |
gen_ai.author.app.id |
OM | O | -- | エージェントを作成したアプリケーションのMicrosoft Entra App IDです。 |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. Defenderのツール使用ビューが欠けている場合は空白です。 |
gen_ai.tool.type |
ET | M | ToolType |
function、Power Platform Connector、MCP Server、API、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 |
エージェントの設計図アプリ IDに電話中。 身体化された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(RawEventData年にもCreationTime) |
Unix Epoch nanosを文字列として使います。 |
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キーとして公開されていません。 いずれにせよ「必要」欄で設定してください。将来のリリースで狩猟ペイロードに追加されるかもしれません。
自然な値がないときに選ぶこと
一部の必須属性は、エージェントのアーキテクチャには存在しないかもしれない概念を記述しています。 自然値がなければ、代わりに設定すべき値を以下に示します。 必須フィールドを空欄にしないでください。全てゼロのGUIDでも、顧客対応の体験からあなたのプレイを隠してしまいます。
| 質問/シナリオ | Field(s) | 設定するもの |
|---|---|---|
| 私のエージェントは標準Entraアプリ登録(Entra エージェント IDの設計図から作ったものではありません)。 | gen_ai.agent.id |
Entraアプリの appIdです。 |
| ↑ 同じシナリオ | microsoft.a365.agent.blueprint.id |
gen_ai.agent.idと同じ値(エージェントのappId)を再利用します。 スキーマは空でない値を必要とします。設計図がない場合はエージェントのアプリIDを再利用するのが安全なデフォルトです。 |
| 私のエージェントはEntra エージェント IDブループリントに基づいて構築されています。これは同じブループリントから作られたエージェントのアイデンティティの一つまたは複数です。 | gen_ai.agent.id |
エージェントのアイデンティティの appId ( インスタンス のappIdで、設計図のものではありません)。 |
| ↑ 同じシナリオ | microsoft.a365.agent.blueprint.id |
設計図は アプリです。 同じブループリントから発行されたすべてのインスタンスはこの価値を共有します。 |
| 発信者は人間のユーザーであり、他のエージェントではありません。 | すべての 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 |
1ランごとに新しいGUIDを生成しましょう。 フィールドは必須です。スキップすると、DefenderのエージェントアクティビティビューやMicrosoft 365 管理センターからその実行が削除されます。 |
| 発信者にはIPがありません(例えば、自律的なスケジュールトリガーなど)。 | client.address |
自分でコントロールする安定したプレースホルダー(例えば "0.0.0.0")を使いましょう。 フィールドは必須です。空の値は、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ではないIDシステム を使っています(エージェントは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 かつ outlook されており、一般的な顧客向け面には web、 office、 sharepoint、 <your-product-name> も使われています。 一つの値を選んでそれに固執してください。工具は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 |
整数の列挙値を使用し、原始列挙文字列ではなく 1 (INTERNAL)、 2 (SERVER)、 3 (CLIENT)、 4 (PRODUCER)、 5 (CONSUMER)。 エージェント365はこれらのいずれかを受け入れ、 kindから顧客が目に見える動作を導き出さないため、 1 (INTERNAL)はすべてのスパンで安全なデフォルトです。 コールの形を反映したいなら、invoke_agent / output_messagesはINTERNAL、chat / execute_toolはCLIENTが妥当です。 |