Agent 365 の可観測性の概念

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

Note

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

統合パスを選択する

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

パス Description
Microsoft OpenTelemetry Distro 新規の連携に推奨されます。 Agent 365、Microsoft Foundry、Azure Monitor などの統合可観測 SDK。
Agent 365 SDK (Observability SDK) 以前のSDKです。 変更を中断することなく引き続き動作しますが、新しい統合の推奨パスではなくなりました。既存の SDK ユーザー向けの移行ガイダンスが提供されます。
直接 OTel 生のOTLP/HTTPパスです。 OpenTelemetry パイプラインが既に配置されている場合、エージェント フレームワークで Agent 365 SDK を使用できない場合、またはエージェントがまだ SDK でサポートされていない言語 (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の概要および収集されるテレメトリについては、「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 モデルの選択によって、使用する認証フローとエンドポイントが決まります。

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

認証

認証は、サービス自身として行うか、ユーザーに代わって行うかによって分かれます。 ブランチは、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 (The user or administrator has not consented to use the application with ID...)で失敗するか、 roles や scp の請求なしにトークンが発行され、インジェスションエンドポイントは 403でリクエストを拒否します。

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

制限とドロップ条件

これらの制限を事前に知っておくことで、統合時の予期せぬ事態を防げます。 失敗の中には、応答でテレメトリが受け入れられなかったことが報告されていても、成功の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の観測性データが現れる場所

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

Experience Description
Microsoft Defender エージェント アクティビティ (invoke_agent、 execute_tool、 chat) がエージェント アクティビティ ビューに表示されます。 テナント管理者とセキュリティ アナリストは、個々の実行、ツール、推論呼び出しの詳細を確認できます。 エージェント アクティビティのビューは invoke_agent スパンをキーとして表示されます。スパンがない場合、詳細検索では子スパンを照会できるにもかかわらず、その実行はそこに表示されません。 高度なハンティング ビュー - 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 スパンとその子孫から得られます。

次のステップ

  • Last updated on