Agent 365 の可観測性の概念

この記事では、Agent 365 の可観測性の背後にあるデータモデルについて説明します。テレメトリエージェントが出力するテレメトリ、出力できるユーザー、配置場所、適用される制限について説明します。これらの概念は、あらゆる統合パスに当てはまります: Microsoft OpenTelemetry Distro、Agent 365 SDK、およびdirect OTel。

Note

ワイヤレベルの詳細 - 認証の URL ルート、制限とドロップ条件の HTTP エラーコード、要求ごとのサイズとレートの制限 - 直接 OTel パスに特に適用されます。 SDK と Distro はこれらを抽象化します。この記事の残りの部分 (用語集、データフロー、ID モデル、スコープ、ドロップ条件、データが表示される場所) は、すべてのパスに適用されます。

統合パスを選択する

3 つのパスによって、エージェント 365 に同じスパンデータモデルが出力されます。 1 つ選択します。

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 モデル、スコープ、制限、およびダウンストリームサーフェスがすべて適用されます。

Glossary

App id (appId): Microsoft Entra アプリまたは Microsoft Entra エージェント ID エージェント ID が登録されたときに発行されるアプリケーション識別子。
- Microsoft Entra オブジェクト ID ではなく、OAuth client_id と同じです。
- これらのドキュメント全体で、"エージェント ID" と "ブループリント ID" はどちらも appIdを意味します。
会話: Teams チャットスレッドなどのエージェント操作の論理スレッド。
- gen_ai.conversation.id によって識別。
- 実行の 主要な結合キー。
チャネル: エージェントが実行されるサーフェス( msteams、 outlook、 webなど)。
実行: 1 人のユーザーメッセージで、1 つのエージェントが応答します。を共有する OTel traceIdツリーとしてモデル化されます。

どのように機能するのか

エージェント 365 の概要とテレメトリのフィードの内容については、「 Microsoft Agent 365 の概要を参照してください。

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

1回の実行単位（1回のユーザーメッセージ入力と1回のエージェント返信出力）を表すスパンのツリー。
各スパンは、最上位レベルのエージェント呼び出し、LLM 呼び出し、ツール呼び出し、または最終的な応答という 1 つのステップを記述します。

データフロー

   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 アプリ登録と Microsoft Entra エージェント ID エージェント ID ブループリント (AI チームメイトを含む) の詳細については、「Get started with Agent 365 development」を参照してください。 ID モデルの選択によって、使用する認証フローとエンドポイントが決まります。

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

Authentication

認証は、サービス自身として行うか、ユーザーに代わって行うかによって分かれます。ブランチは、OAuth フロー、アクセス許可を持つトークン要求、および URL ルートを決定します。

サービス自体が認証されます。サインインしているユーザーはいません。自律型、スケジュール済み、またはイベントドリブン型です。
- OAuth フロー: サービス間 (S2S) クライアント資格情報。
- トークン要求: roles。
- URL ルート: /observabilityService/...。
サービスはユーザーに代わって認証されます。AI チームメイトの場合、またはエージェント独自のユーザーアカウントの場合。
- OAuth フロー: On-behalf-of (OBO)。
- トークン要求: scp。
- URL ルート: /observability/...。

同じエージェントアプリは、夜間に自律的な要約パスを実行する AI チームメイトなど、両方のフローに参加できます。詳細については、自律アプリの OAuth フローと代理フローを参照してください。

ID モデルとフローの各組み合わせの完全なトークンレシピについては、統合ガイドの認証レシピを参照してください。

エージェント ID が URL にバインドされている

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

さらに、送信するすべてのスパンで、 gen_ai.agent.id を同じ appId に設定する必要があります。サーバーは、認証されたエージェントに対してペイロード内エージェント ID を検証し、不一致を拒否します。このステップでは、複数のエージェントのスパンが誤って1つのリクエストに混在してしまうことを検出します。

scope (委任) または app role (アプリケーション) は、Microsoft Entra がアクセストークンに含める名前付きアクセス許可です。エージェント 365 テレメトリの場合、アクセス許可は Agent 365 Observability リソース (対象ユーザーAgent365.Observability.OtelWrite) に9b975845-388f-4429-889e-eab1ef63949cされます。

同じアクセス許可名が両方の種類として登録されます。

自動 (S2S/クライアント資格情報) フローのアプリロール。 roles クレームに含まれます。 <resource>/.defaultによって選択されます。
OBO フローの委任されたスコープ。 scp クレームに含まれます。 <resource>/Agent365.Observability.OtelWrite (または<resource>/.default) によって選択されます。

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

アプリへのアクセス許可の追加

標準Microsoft Entra アプリの登録: Azure ポータルで、エージェントのアプリ登録の Agent365.Observability.OtelWriteの下に (S2S のアプリロール、委任されたスコープ) を追加します。
blueprint の場合: 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--token に必要なアプリロール/スコープがないか、URL 内の {agentId} がトークンの appid / azp と一致しません。
413 Payload Too Large--body が 1 MB を超えています。
429 Too Many Requests--レート制限に達しました。Retry-After: 1 に従い、ジッターを加えてバックオフしてください。

ドロップ条件 (HTTP によって受け入れられる要求が、データがダウンストリームに表示されない):

#	状態	Behavior
1	スパン `gen_ai.operation.name` が見つからないか、`{invoke_agent, execute_tool, chat, output_messages}` 内にありません	スパンごとのドロップ。 `partialSuccess.rejectedSpans` + `errorMessage`で表示されます。
2	顧客テナント内に、Microsoft 365 E7 または Microsoft Agent 365 ライセンスが割り当てられているユーザーはいません。テナント内の少なくとも 1 人のユーザーがライセンス assigned を持っている必要があります (テナントに存在する SKU では不十分です。割り当てによってDefenderバックエンドワークフローが開始されます)。ライセンスされたユーザーがエージェントの人間の呼び出し元である必要はありません。	リクエスト全体が何の通知もなく破棄されました。 `200 { "partialSuccess": null }` を返します。

200 OK は、取り込みが行われたことの証拠ではありません。検証フローを使用して、データの土地を確認します。

データが表示される場所

承認されると、スパンは3つの顧客向けエクスペリエンスに表示されるようになります。 3 つすべてが、実行のルートにある有効な invoke_agent スパンに依存します。 chat / execute_tool / output_messages スパンだけを含む実行は、Defender の高度なハンティング（CloudAppEvents テーブル）ではクエリできますが、以下のその他すべての場所では表示されません。

Microsoft Defender。 エージェントアクティビティ (invoke_agent、 execute_tool、 chat) がエージェントアクティビティビューに表示されます。テナント管理者とセキュリティアナリストは、個々の実行、ツール、推論呼び出しの詳細を確認できます。 エージェントアクティビティビューは invoke_agent span を基準にしており、それがない場合、子 span は高度なハンティングで引き続きクエリできるものの、その実行はそこには表示されません。高度なハンティングビュー - CloudAppEvents - は、すべての操作を受け入れます。ActionType は操作（InvokeAgent、InferenceCall、ExecuteToolBySDK、ExecuteToolByGateway、ExecuteToolByMCPServer）を示し、span ごとのフィールドは 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-05-21