Agent 365 におけるオブザーバビリティ (監視) の概念

この記事では、Agent 365 の監視を支えるデータモデルについて解説します。具体的には、テレメトリエージェントがどのようなデータを送信するか、誰が送信できるか、データがどこに集約されるか、および適用される制限について説明します。これらの概念は、Microsoft OpenTelemetry Distro、Agent 365 SDK、および直接の OTel など、あらゆる統合パスに適用されます。

メモ

ワイヤレベルの詳細 (認証における URL ルート、制限とドロップ条件における HTTP エラーコード、リクエストごとのサイズおよびレート制限など) は、特に OTel のダイレクトパスに適用されます。 SDK と Distro が、これらを抽象化します。この記事の残りの部分 (用語集、データフロー、アイデンティティモデル、スコープ、ドロップ条件、データの出現箇所) は、すべてのパスに適用されます。

統合パスを選択してください

3 つのパスが、Agent 365 に対して同一のスパンデータモデルを送信します。いずれかを選択します:

Microsoft OpenTelemetry Distro - は、新規の統合に推奨されています。 Agent 365、Microsoft Foundry、Azure Monitor などを横断する統合型監視 SDK。
Agent 365 SDK (Observability SDK) - 以前の SDK です。破壊的変更なく引き続き動作しますが、新規の統合においては推奨される方法ではありません。既存の SDK ユーザー向けの移行ガイドは近日公開予定です。
Direct OTel - OTLP/HTTP の生のパス。すでに OpenTelemetry パイプラインが構築されている場合、ご利用のエージェントフレームワークが Agent 365 SDK を使用できない場合、またはエージェントが SDK がまだサポートしていない言語 (Java など) で記述されている場合にのみ、これを使用してください。

どのパスを選択する場合でも、以下で説明するデータモデル、ID モデル、スコープ、制限、下流のサーフェスはすべて適用されます。

用語集

App id (appId): Microsoft Entra アプリまたは Microsoft Entra エージェント ID のエージェント ID が登録された際に発行されるアプリケーション識別子。
- Microsoft Entra オブジェクト ID ではなく、OAuth client_id と同等です。
- このドキュメント全体を通じて、「エージェント ID」と「ブループリント ID」は、いずれも appId を指します。
Conversation: Teams のチャットスレッドなど、エージェント間のやり取りの時系列スレッド。
- gen_ai.conversation.id によって識別。
- 実行に使用するプライマリ結合キー 。
チャネル: エージェントが実行される環境: msteams、outlook、webなど。
実行: ユーザーからのメッセージが 1 件に対して、エージェントの返信が 1 件送信されます。これは、traceId を共有する OTel スパンからなるツリーとしてモデル化されています。

この機能の動作

Agent 365 の概要およびテレメトリの活用先については、Microsoft Agent 365 の概要を参照してください。

テレメトリは、OpenTelemetry のトレースデータとして送信します:

1 回の実行 (ユーザーからのメッセージ 1 件の受信、エージェントからの返信 1 件の送信) を表すスパン ツリー。
各スパンは、1 つのステップ (最上位エージェントの呼び出し、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)                  |
  +-------------------------------------+

ID モデル

エージェント ID モデル (標準の Microsoft Entra アプリ登録と、AI チームメイトを含む Microsoft Entra エージェント ID エージェント ID ブループリントの比較) に関する詳しい説明については、Agent 365 開発の開始を参照してください。選択する ID モデルによって、使用する認証フローとエンドポイントが決まります。

エージェントに Microsoft Entra の登録がない場合、これらのルートは直接使用できません。代替 ID 属性 (属性リファレンスを参照) を使用してエージェントを特定し、適切なイングレスパスについて Agent 365 チームにお問い合わせください。

認証

認証は、サービスが自身を認証するのか、それともユーザーに代わって認証を行うのかによって分岐します。この分岐によって、OAuth フロー、権限を保持するトークンのクレーム、URL ルートが決まります。

サービス自身による認証: サインイン済みのユーザーがいない (自律型、スケジュール型、またはイベント駆動型)。
- OAuth フロー: Service-to-service (S2S) クライアント資格情報。
- トークンクレーム: roles.
- URL ルート: /observabilityService/....
サービスがユーザーの代理で認証: AI チームメイトやエージェント自身のユーザーアカウントの場合
- OAuth フロー: On-behalf-of (OBO).
- トークンクレーム: scp.
- URL ルート: /observability/....

同じエージェントアプリが両方のフローに参加することも可能です。たとえば、AIチームメイトが、毎晩の自動要約処理も実行するような場合です。詳細については、自律型アプリの OAuth フローと On-Behalf-Of フローを参照してください。

各 ID モデルとフローの組み合わせに関するトークン作成手順の詳細については、統合ガイドの認証手順を参照してください。

エージェントの ID は URL に紐付けられています

URL 内の {agentId} は、呼び出し元アプリケーションの appId (トークン内の appid または azp クレーム) と一致している必要があります。不一致の場合は 403 Forbidden が返されます。ブループリントから派生した ID の場合、{agentId} はエージェントの ID である appId であり、ブループリントの appId ではありません。

さらに、送信するすべてのスパンにおいて、gen_ai.agent.id を同じ appId に設定する必要があります。サーバーは、ペイロード内のエージェント ID を認証済みエージェントと照合して検証し、不一致の場合は拒否します。この手順により、複数のエージェントからのスパンが誤って 1 つのリクエストに混在してしまうことを予防します

スコープ (委任型) またはアプリロール (アプリケーション) とは、Microsoft Entra がアクセストークンに付与する、名前付きの権限です。 Agent 365 テレメトリについては、Agent 365 Observability リソース (対象 9b975845-388f-4429-889e-eab1ef63949c) に対する権限は Agent365.Observability.OtelWrite です。

同じ権限名が、両方の 種類として登録されています:

自律型 (S2S/クライアント認証情報) フローにおけるアプリのロール。 roles の要求にランディングします。 <resource>/.default によって選択されます。
OBO フローの委任されたスコープ。 scp の要求にランディングします。 <resource>/Agent365.Observability.OtelWrite (または <resource>/.default) によって選択されます。

Agent 365 は、Agent 365 のテレメトリをクエリするオペレーターが使用する読み取り側の権限 Agent365.Observability.OtelRead も公開しています。ほとんどのパートナーには必要ありません。これらのドキュメントはデータのインジェストのみを対象としています。

アプリに権限を追加する

Microsoft Entra アプリの標準的な登録の場合: Azure ポータルで、エージェントのアプリ登録の API 権限 の下に、Agent365.Observability.OtelWrite (S2S 用のアプリロール、委任用のスコープ) を追加します。
ブループリントの場合: Microsoft Entra エージェント ID のエージェント ID ブループリントから作成されたエージェントは、このブループリントで定義された OAuth 権限を継承するため、テナント管理者は権限の設定を一度だけ事前に行うだけで済みます。このブループリントから作成されたすべてのエージェントインスタンスは、それらを自動的に受け取ります。エージェント ID ブループリントの継承可能な権限を構成するを参照してください。

トークンがロール/スコープを保持する前に、顧客のテナントのテナント管理者が同意を与える必要があります。 Microsoft 365リソースへのアクセスをエージェントに付与をご参照ください。

同意がない場合、トークンの取得は AADSTS65001 (「ユーザーまたは管理者が同意していない」) で失敗するか、roles / scp クレームを含まないトークンが発行され、取り込みエンドポイントが 403 で要求を拒否します。

同意はテナントごとに 1 回付与され、その後そのブループリントから構築されるすべてのインスタンスに適用されます。ブループリントに新しい権限が追加された場合にのみ、再同意が必要となります。

制限とドロップの条件

こうした制限を事前に把握しておくことで、統合作業中での予期せぬ事態の発生を予防できます。こうした事態の多くは目に見えない形で発生します (API が要求を受け付けるが、下流にはデータが一切表示されないなど)。

ワイヤーレベル制限:

api-version=1 はすべての要求で必須です。
要求本文の最大サイズは 1 MB です。大型の要求には 413 Payload Too Large が返されます。
2 つのルートには、それぞれ個別のレート制限が設定されています。 429では、Retry-After (1 秒に設定) を優先し、ジッターでバックオフします。

エラー応答:

403 Forbidden--トークンに必要なアプリロール/スコープが欠落している、または URL 内の {agentId} が、トークンの appid / azp と一致しません。
413 Payload Too Large--本文が 1 MB を超えています。
429 Too Many Requests--レート制限に達しました。Retry-After: 1 に従い、ジッターでバックオフしてください。

ドロップ条件 (HTTP により要求が受理されても、データが下流に反映されない場合):

#	条件	動作
1	スパンで `gen_ai.operation.name` が欠落しているか、`{invoke_agent, execute_tool, chat, output_messages}` に含まれていません	スパンごとのドロップ。 `partialSuccess.rejectedSpans` + `errorMessage` で表示されます。
2	顧客テナント内のどのユーザーにも、Microsoft 365 E7 または Microsoft Agent 365 のライセンスが割り当てられていません。テナント内の 1 人以上のユーザーにライセンスが割り当てられている必要があります (テナント内に SKU が存在しているだけでは不十分です。割り当てが行われて初めて、Defender のバックエンドワークフローが開始されます)。ライセンス保有者は、必ずしもエージェントの利用者本人である必要はありません。	要求全体がサイレントにドロップされます。 `200 { "partialSuccess": null }` を返します。

「200 OK」は、データが正常にインジェストされたことの証明にはなりません。検証フローを使用して、データが正しく取り込まれていることを確認してください。

データが表示される場所

承認されると、スパンは 3 つの顧客向けエクスペリエンスに表示されます。 これら 3 つすべては、実行のルートにある有効な invoke_agent スパンに依存しています。 chat / execute_tool / output_messages のスパンしか含まない実行は、Defender の高度なハンティング (CloudAppEvents テーブル) ではクエリの対象となりますが、それより下のすべての画面では表示されません。

Microsoft Defender。 Agent の活動 (invoke_agent、execute_tool、chat) がエージェントの活動ビューに表示されます。テナント管理者とセキュリティアナリストは、個々の実行、ツール、推論呼び出しを詳細に分析することができます。 エージェントアクティビティのビューは invoke_agent スパンをキーとして表示されます。スパンがない場合、詳細検索では子スパンを照会できるにもかかわらず、その実行はそこに表示されません。高度なハンティングビュー (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 のみを送信する実行もここでは表示されません。管理センターが読み取る属性 (エージェント ID、エージェント名、ブループリント ID、発信者 ID、会話 ID、チャネル、エラー状態) は、すべて invoke_agent スパンから取得されます。

Microsoft Purview。 また、エージェントの活動は Microsoft Purview のコンプライアンス管理者に表示され、管理者はそこでエージェントの実行に関するデータ処理やポリシールール (データ漏洩防止、保存期間、通信コンプライアンスなど) を構成できます。 Purview ポリシーが基にする属性 (エージェント ID / ブループリント ID、発信者 ID、会話/チャネル、要求と応答メッセージ) は、すべて invoke_agent スパンとその子要素から取得されます。

次の手順

属性参照 - 属性ごとの仕様、要件、値の選定に関するガイダンス。
トラブルシューティング - インジェストの検証、よくある問題点、エラー応答。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-30