エージェント ID: 自律的および対話型のエージェントパターン

エージェント ID を使用すると、エージェントアプリケーションが自律的に、またはユーザーに代わって動作する高度な認証シナリオが可能になります。 Microsoft Entra SDK for AgentID でエージェント ID を使用すると、独自のコンテキストで動作する自律エージェントと、ユーザーに代わって動作する対話型エージェントの両方を作成できます。これらのシナリオを容易にするために、SDK では、エージェント ID とユーザーコンテキストを指定するための特定のクエリパラメーターがサポートされています。

エージェント ID の詳細なガイダンスについては、Microsoft エージェント ID プラットフォームのドキュメントを参照してください。

概要

エージェント ID では、次の 2 つの主要なパターンがサポートされます。

自律エージェント: エージェントは、独自のアプリケーションコンテキストで動作します。
対話型エージェント: 対話型エージェントは、ユーザーに代わって動作します。

SDK は、次の 3 つの省略可能なクエリパラメーターを受け入れます。

AgentIdentity - エージェント ID の GUID。
AgentUsername - 特定のユーザーのユーザープリンシパル名 (UPN)。
AgentUserId - UPN の代わりに、特定のユーザーのユーザーオブジェクト ID (OID)。

優先順位ルール

AgentUsername と AgentUserId は相互に排他的です。規則 2: 相互排他性で説明されているように、両方のパラメーターを含む要求は検証に失敗します。要求ごとにこれらのパラメーターを 1 つだけ指定します。

Microsoft Entra ID構成

アプリケーションでエージェント ID を構成する前に、Microsoft Entra IDで必要なコンポーネントを設定します。新しいアプリケーションをMicrosoft Entra IDテナントに登録するには、アプリケーションの登録に関するページを参照してください。

エージェント ID の前提条件

エージェントアプリケーションの登録:
- Microsoft Entra IDに親エージェントアプリケーションを登録します。
- ダウンストリーム API の API アクセス許可を構成します。
- クライアント資格情報 (FIC+MSI、証明書、またはシークレット) を設定します。
エージェント ID の構成:
- エージェントブループリントを使用してエージェント ID を作成します。
- エージェント ID に必要なアクセス許可を割り当てます。
アプリケーションのアクセス許可:
- 自律的なシナリオに対してアプリケーションのアクセス許可を付与します。
- ユーザー委任シナリオに対して権限を委任します。
- 必要に応じて、管理者の同意が提供されていることを確認します。

Microsoft Entra IDでエージェント ID を構成する詳細な手順については、Microsoft エージェント ID プラットフォームのドキュメントを参照してください。

セマンティックルール

正常に認証するには、エージェント ID パラメーターを正しく使用する必要があります。次の規則は、 AgentIdentity、 AgentUsername、および AgentUserId パラメーターの使用を制御します。 SDK から返される検証エラーを回避するには、次の規則に従います。

規則 1: AgentIdentity の要件

AgentUsername または AgentUserId は AgentIdentityとペアにする必要があります。

AgentUsernameなしでAgentUserIdまたはAgentIdentityを指定した場合、要求は検証エラーで失敗します。

# INVALID - AgentUsername without AgentIdentity
GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

# VALID - AgentUsername with AgentIdentity
GET /AuthorizationHeader/Graph?AgentIdentity=agent-client-id&AgentUsername=user@contoso.com

規則 2: 相互排他性

AgentUsername と AgentUserId は相互に排他的なパラメーターです。

同じ要求で AgentUsername と AgentUserId の両方を指定することはできません。両方のパラメーターを指定すると、要求は検証エラーで失敗します。

# INVALID - Both AgentUsername and AgentUserId specified
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

# VALID - Only AgentUsername
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# VALID - Only AgentUserId
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

ルール 3: 自律型と対話型

パラメーターの組み合わせによって、認証パターンが決まります。

パラメーター	パターン	Description
`AgentIdentity` のみ	自律エージェント	エージェント ID のアプリケーショントークンを取得します
`AgentIdentity` + `AgentUsername`	対話型エージェント	指定されたユーザーのユーザートークンを取得します (UPN 別)
`AgentIdentity` + `AgentUserId`	対話型エージェント	指定したユーザーのユーザートークンを取得します (オブジェクト ID による)。

例:

# Autonomous agent - application context
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id

# Interactive agent - user context by username
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# Interactive agent - user context by user ID
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

使用パターン

使用パターンごとに、パラメーターの組み合わせによって、認証フローと取得されたトークンの種類が決まります。

パターン 1: 自律エージェント

エージェントアプリケーションは、独自のアプリケーションコンテキストで独立して実行され、アプリケーショントークンを取得します。

シナリオ: ファイルを単独で処理するバッチ処理サービス。

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012

トークンの特性:

トークンの種類: アプリケーショントークン
件名 (sub): エージェントアプリケーションのオブジェクト ID
エージェントの ID 用に作成されたトークン
アクセス許可: エージェント ID に割り当てられたアプリケーションのアクセス許可

ユースケース:

自動バッチ処理
バックグラウンドタスク
システム間操作
ユーザーコンテキストのないスケジュールされたジョブ

パターン 2: 自律ユーザーエージェント (ユーザー名別)

エージェントは、UPN によって識別された特定のユーザーに代わって実行されます。

シナリオ: チャットアプリケーションでユーザーに代わって機能する AI アシスタント。

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUsername=alice@contoso.com

トークンの特性:

トークンの種類: ユーザートークン
件名 (sub): ユーザーのオブジェクト ID
トークンクレームに含まれるエージェントIDの側面
インタラクティブ権限: ユーザーにスコープが設定されたインタラクティブな権限

ユースケース:

対話型エージェントアプリケーション
ユーザー委任を使用した AI アシスタント
ユーザースコープにおける自動化
カスタマイズされたワークフロー

パターン 3: 自律ユーザーエージェント (オブジェクト ID 別)

エージェントは、オブジェクト ID で識別された特定のユーザーに代わって動作します。

シナリオ: 格納されているユーザー ID を使用してユーザー固有のタスクを処理するワークフローエンジン。

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUserId=87654321-4321-4321-4321-210987654321

トークンの特性:

トークンの種類: ユーザートークン
件名 (sub): ユーザーのオブジェクト ID
トークンクレームに含まれるエージェントIDの側面
インタラクティブ権限: ユーザーにスコープが設定されたインタラクティブな権限

ユースケース:

保存されたユーザー識別子を持つ実行時間の長いワークフロー
複数のユーザーに代わってバッチ操作を実行する
ユーザー参照にオブジェクト ID を使用するシステム

パターン 4: 対話型エージェント (呼び出し元のユーザーに代わって動作)

エージェント Web API は、ユーザートークンを受け取り、検証し、そのユーザーに代わって委任された呼び出しを行います。

シナリオ: 着信ユーザートークンを検証し、ダウンストリームサービスへの委任された呼び出しを行う対話型エージェントとして機能する Web API。

フロー:

エージェント Web API は、呼び出し元のアプリケーションからユーザートークンを受け取ります。
/Validate エンドポイントを介してトークンを検証します。
/AuthorizationHeaderと受信 Authorization ヘッダーのみを使用してAgentIdentityを呼び出すことによって、ダウンストリーム API のトークンを取得します。

# Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>

# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>

トークンの特性:

トークンの種類: ユーザートークン (OBO フロー)
件名 (sub): 元のユーザーのオブジェクト ID
エージェントがユーザーの仲介役として機能する
アクセス許可: ユーザーにスコープが設定された対話型のアクセス許可

ユースケース:

エージェントとして機能する Web API
対話型エージェントサービス
ダウンストリーム API に委任するエージェントベースのミドルウェア
ユーザーコンテキストを検証して転送するサービス

パターン 5: 通常の要求 (エージェントなし)

エージェントパラメーターを指定しない場合、SDK は受信トークンの ID を使用します。

シナリオ: エージェント ID を使用しない標準の代理 (OBO) フロー。

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

トークンの特性:

トークンの種類: 受信トークンと構成に依存
標準の OBO またはクライアント資格情報フローを使用する
エージェント ID ファセットなし

コード例

次のコードスニペットは、さまざまなプログラミング言語を使用してさまざまなエージェント ID パターンを実装する方法と、SDK エンドポイントと対話する方法を示しています。このコードでは、SDK へのプロセス外呼び出しを処理して、ダウンストリーム API 呼び出しの承認ヘッダーを取得する方法を示します。

TypeScript: 自律エージェント

const sidecarUrl = "http://localhost:5000";
const Agent ID = "12345678-1234-1234-1234-123456789012";

async function runBatchJob() {
  const response = await fetch(
    `${sidecarUrl}/AuthorizationHeader/Graph?AgentIdentity=${agentId}`,
    {
      headers: {
        'Authorization': 'Bearer system-token'
      }
    }
  );
  
  const { authorizationHeader } = await response.json();
  // Use authorizationHeader for downstream API calls
}

Python: ユーザー ID を持つエージェント

import requests

sidecar_url = "http://localhost:5000"
agent_id = "12345678-1234-1234-1234-123456789012"
user_email = "alice@contoso.com"

response = requests.get(
    f"{sidecar_url}/AuthorizationHeader/Graph",
    params={
        "AgentIdentity": agent_id,
        "AgentUsername": user_email
    },
    headers={"Authorization": f"Bearer {system_token}"}
)

token = response.json()["authorizationHeader"]

TypeScript: 対話型エージェント

async function delegateCall(userToken: string) {
  // Validate incoming token
  const validation = await fetch(
    `${sidecarUrl}/Validate`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  const claims = await validation.json();
  
  // Call downstream API on behalf of user
  const response = await fetch(
    `${sidecarUrl}/DownstreamApi/Graph`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  return await response.json();
}

HttpClient を使用した C#

using System.Net.Http;

var httpClient = new HttpClient();

// Autonomous agent
var autonomousUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}";
var response = await httpClient.GetAsync(autonomousUrl);

// Delegated agent with username
var delegatedUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUsername={Uri.EscapeDataString(userPrincipalName)}";
response = await httpClient.GetAsync(delegatedUrl);

// Delegated agent with user ID
var delegatedByIdUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUserId={userObjectId}";
response = await httpClient.GetAsync(delegatedByIdUrl);

エラーシナリオ

エージェント ID パラメーターを正しく構成しないか、正しく使用しないと、SDK は検証エラーを返します。次のセクションでは、一般的なエラーシナリオとそれに対応する応答について説明します。エラー処理の詳細については、トラブルシューティングガイドを参照してください。

AgentUsername で AgentIdentity が見つからない

要求:

GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

応答:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername requires AgentIdentity to be specified"
}

AgentUsername と AgentUserId の両方を指定

要求:

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

応答:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername and AgentUserId are mutually exclusive"
}

AgentUserId 形式が無効です

要求:

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=invalid-guid

応答:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUserId must be a valid GUID"
}

ベストプラクティス

入力を検証する: 要求を行う前に、常にエージェント ID パラメーターを検証します。
使用可能な場合はオブジェクト ID を使用します。オブジェクト ID の方が安定しています。
適切なエラー処理を実装する: エージェント ID 検証エラーを適切に処理します。
セキュリティで保護されたエージェント資格情報: エージェント ID クライアント ID と資格情報を保護します。
監査エージェントの操作: セキュリティとコンプライアンスのためにエージェント ID の使用状況をログに記録して監視します。
両方のパターンをテストする: テストで自律的なシナリオと委任されたシナリオの両方を検証します。
ドキュメントの意図: 各ユースケースに適したエージェントパターンを明確に文書化します。

フィードバック

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

Last updated on 2026-04-19

エージェント ID: 自律的および対話型のエージェント パターン

概要

優先順位ルール

Microsoft Entra ID構成

エージェント ID の前提条件

セマンティック ルール

規則 1: AgentIdentity の要件

規則 2: 相互排他性

ルール 3: 自律型と対話型

使用パターン

パターン 1: 自律エージェント

パターン 2: 自律ユーザー エージェント (ユーザー名別)

パターン 3: 自律ユーザー エージェント (オブジェクト ID 別)

パターン 4: 対話型エージェント (呼び出し元のユーザーに代わって動作)

パターン 5: 通常の要求 (エージェントなし)

コード例

TypeScript: 自律エージェント

Python: ユーザー ID を持つエージェント

TypeScript: 対話型エージェント

HttpClient を使用した C#

エラー シナリオ

AgentUsername で AgentIdentity が見つからない

AgentUsername と AgentUserId の両方を指定

AgentUserId 形式が無効です

ベスト プラクティス

関連するコンテンツ

フィードバック

その他のリソース

エージェント ID: 自律的および対話型のエージェントパターン

セマンティックルール

パターン 2: 自律ユーザーエージェント (ユーザー名別)

パターン 3: 自律ユーザーエージェント (オブジェクト ID 別)

エラーシナリオ

ベストプラクティス