Agent 365 の可観測性の概念

この記事では、エージェント365の観測可能性データモデルについて説明し、テレメトリエージェントが何を発信し、誰が発信できるか、どこに着地し、適用される制限かを説明します。 これらの概念を活用して統合計画を立て、Microsoft OpenTelemetry Distro、廃止されたAgent 365 Observability SDK、そしてダイレクトOTelを通じたテレメトリを理解しましょう。

Note

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

統合パスを選択する

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

Path Description
Microsoft OpenTelemetry Distro 新規の連携に推奨されます。 Agent 365、Microsoft Foundry、Azure Monitor などの統合可観測 SDK。
非推奨の Agent 365 Observability SDK レガシーSDKです。 既存の統合は引き続き動作しますが、新しい統合にはそれを使わないでください。 記事には移行ガイドが含まれています。
直接 OTel 生のOTLP/HTTPパスです。 すでにOpenTelemetryパイプラインが用意されている場合、エージェントフレームワークがMicrosoft OpenTelemetry Distroを使えない場合、またはエージェントがディストリビューションでまだサポートされていない言語（例えばJava）で記述されている場合のみ使用してください。

どちらのパスを選択しても、以下で説明するデータ モデル、ID モデル、スコープ、制限、およびダウンストリーム サーフェスがすべて適用されます。

エージェント365の観測可能性用語集

任期 Description
アプリID(appId) Microsoft EntraアプリまたはMicrosoft Entra エージェント IDエージェントIDが登録された際に発行されるアプリケーション識別子。
- OAuth client_idと等しく、Microsoft EntraオブジェクトIDではありません。
- これらの文書全体で、「エージェントID」と「ブループリントID」はどちらも appIdを意味します。
会話 Teamsチャットスレッドのような論理的なエージェント間のやり取りスレッドです。
- gen_ai.conversation.idで特定。
- 実行のための プライマリジョインキー 。
Channel エージェントが動く表面: msteams、 outlook、 webなど。
実行 1人のユーザーメッセージが入り、1人のエージェントが返信します。OTel のスパン が traceIdを共有する木構造としてモデル化されています。

エージェント365の観察可能性の仕組み

Agent 365およびAgent 365 が収集するテレメトリの概要については、「Microsoft Agent 365の概要」をご覧ください。

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

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

Agent 365 観測性データフロー

以下の図は、エージェントテレメトリーが認証やAgent 365の観測可能性インジェスティングを通じてMicrosoft 365の下流体験へどのように流れていくかを示しています。

Agent 365の観測性データフロー図。

ID モデル

エージェント識別モデル(標準的なMicrosoft Entraアプリ登録とMicrosoft Entra エージェント IDエージェント識別設計図、AIチームメイトを含む)の詳細な説明については、Agent identityを参照してください。 ID モデルの選択によって、使用する認証フローとエンドポイントが決まります。

設計図由来のエージェントの識別情報は、エージェント365登録が完了した後（例えば a365 setup allを通じて）にのみ、Agent 365 に登録されたエージェント インスタンスになります。 Microsoft Entraのアイデンティティを作成するだけではインスタンスが登録されません。 カスタムエンジンエージェントが使うような標準的なMicrosoft Entraアプリの登録は、登録エージェントインスタンスではありません。

エージェントにMicrosoft Entra登録がない場合、これらのルートを直接使用することはできません。 代替ID属性(属性 参照参照)を通じてエージェントを特定し、適切な入力経路についてAgent 365チームに連絡してください。

Authentication

認証は、サービス自体が認証を行うか、ユーザーを代表して認証を行うかによって決まります。 この区別がOAuthフロー、許可を運ぶトークンクレーム、URLルートを決定します。

  • サービス自体が認証されます。サインインしているユーザーはいません。自律型、スケジュール済み、またはイベント ドリブン型です。

    • OAuth フロー: サービス間 (S2S) クライアント資格情報。
    • トークン要求: roles。 未登録のアイデンティティには Agent365.Observability.OtelWrite アプリ ロールが必要です。 Agent 365に登録されたエージェントインスタンスは、その役割なしでアプリのみのトークンを使用できます。
    • 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 / クライアント資格情報) フロー上の未登録 ID のためのアプリ ロール。 roles クレームに含まれます。 <resource>/.defaultによって選択されます。
  • OBO フローの委任されたスコープ。 scp クレームに含まれます。 <resource>/Agent365.Observability.OtelWrite (または<resource>/.default) によって選択されます。

S2Sルートでは、Agent 365に登録されたエージェントインスタンスが、 Agent365.Observability.OtelWrite 役割のないアプリ専用トークンでエクスポートできます。 テレメトリのエクスポートにはObservabilityの許可や管理者の同意は必要ありません。 未登録のアイデンティティでもアプリ ロールが必要で、委任ルートでは委任されたスコープに加えて管理者の同意も必要です。

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

アプリに権限を追加してください

  • 標準的なMicrosoft Entraアプリ登録については、Azureポータルでエージェントのアプリ登録のAgent365.Observability.OtelWriteに追加します。 S2Sにはアプリ ロールを使い、OBOには委任されたスコープを使いましょう。
  • S2Sルート上のブループリント由来エージェントインスタンスの場合: エージェントインスタンスの Agent 365 の登録を完了してください。 登録されたインスタンスは、S2SルートでテレメトリをエクスポートするのにObservability APIの権限や管理者の同意を必要としません。
  • 委託ルート上のブループリント由来エージェントインスタンスの場合:委任Agent365.Observability.OtelWriteスコープをブループリントに追加し、エージェントインスタンスがそれを継承できるようにします。 エージェント ID ブループリントの継承可能なアクセス許可を構成するを参照してください。 Agent 365 CLIで追加するには、Observability permissionsをご覧ください。

トークンが必要な役割や範囲を持つ前に、顧客テナント内のテナント管理者が同意を付与しなければなりません。 Microsoft 365 リソースへのエージェントアクセスを参照してください。

同意がなければ、トークン取得は AADSTS65001 (The user or administrator has not consented to use the application with ID...)で失敗するか、 roles や scp の請求なしにトークンが発行され、インジェスションエンドポイントは 403でリクエストを拒否します。

S2SルートでエクスポートするAgent 365登録エージェントインスタンスは、Observability管理者承認を必要としません。 アプリロールを使用する未登録のS2Sアイデンティティや、委任されたスコープを使用するすべての委任ルートエクスポートには依然として同意が必要です。

同意が必要な場合は、 テナントごとに一度だけ 与えられ、その後設計図から構築されたすべてのインスタンスに適用されます。 再同意は、ブループリントに新しいアクセス許可が追加された場合にのみ必要です。

制限とドロップ条件

これらの制限を事前に知っておくことで、統合時の予期せぬ事態を防げます。 失敗の中には、応答でテレメトリが受け入れられなかったことが報告されていても、成功のHTTPステータスが返されるものがあります。

ワイヤ レベルの制限:

  • すべてのリクエストには api-version=1 を含める必要があります。
  • 最大リクエスト本体サイズは 1MBです。 要求が大きいほど、 413 Payload Too Largeが返されます。
  • 2 つのルートには 個別のレート制限があります。 429では、Retry-After (1 秒に設定) を優先し、ジッターでバックオフします。

S2S認証を使用するオンボード済みのサードパーティ統合は、テレメトリを送信する前の任意の事前チェックとして、テナント適格性エンドポイントを呼び出すことができます。 エンドポイントを使用する場合は、同意やライセンスだけで適格性を推測するのではなく、その決定に頼ってください。 enabled: false回答は、借主が現在資格がないことを意味します。 ボディレス 503 Service Unavailable は適格性を判断できないことを意味します。 まだ適格結果が必要なら、 Retry-After ヘッダーに従って再挑戦してください。

エラー応答:

  • 403 Forbidden: URLに必要なアプリの役割や範囲、または {agentId} が欠けている場合、トークンの appid や azp と一致しません。
  • 413 Payload Too Large:本体が1MBを超えています。
  • 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 OK返しますが、各スパンの results エントリは rejected ステータスを持ち、理由も tenant_not_licensedです。

200 OKは摂取の証拠ではありません。 応答の resultsを確認し、 検証フロー を使ってデータが着地していることを確認します。

エージェント365の観測性データが現れる場所

span を受け入れると、3つの顧客対応エクスペリエンスに表示されます。 これら3つの体験はすべて、ランのルートにある有効な invoke_agent スパンに依存しています。 chat、execute_tool、または output_messages スパンのみのランは、Defender の高度なハンティング（CloudAppEvents テーブル）でクエリ可能ですが、他のすべてのサーフェスからは見えません。

Experience Description
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 のみを発する実行はここでは見えません。 管理センターは invoke_agent スパンからエージェントID、エージェント名、設計図ID、発信者ID、会話ID、チャネル、エラーステータスなどの属性を読み取ります。
Microsoft Purview エージェントの活動はMicrosoft Purview内のコンプライアンス管理者にも表示され、エージェント実行時にデータ処理やポリシールール(データ損失防止、保持、通信準拠など)を設定できます。 Purviewポリシーでキーオフされる属性(エージェントID、設計図ID、発信者識別、会話、チャネル、リクエスト、レスポンスメッセージ)は、 invoke_agent スパンとその子孫から得られます。

次のステップ

  • 最終更新: