ホストされるエージェントのアクセス許可のリファレンス

Microsoft Foundry でホストされるエージェントを使用する場合は、関連するさまざまなアクセス許可を理解することが重要です。 ホスト型エージェントの開発には、Azure Resource Manager コントロール プレーンと Foundry データ プレーンにまたがるいくつかのクラスのアクセス許可が含まれます。

• Foundry リソースを操作するユーザーまたはプリンシパルに付与されるアクセス許可
• Foundry プロジェクトに付与されるアクセス許可
• エージェントに付与されたアクセス許可

この記事は、 ロールベースのアクセス制御 (RBAC) の概念と、Microsoft Foundry で使用できる組み込みロールを紹介する、Microsoft Foundry のロールベースのアクセス制御のコンパニオンです。 先に進む前に、その記事を理解しておく必要があります。 この記事では、ホストされたエージェントの開発とデプロイに関連する操作、それらの操作を実行するために必要なアクセス許可、およびそれらのアクセス許可に対応する組み込みロールについて説明します。

エンド ツー エンドのデプロイとライフサイクルのタスクについては、「 ホストされたエージェントのデプロイ 」および「 ホストされたエージェントのライフサイクルの管理」を参照してください。 ID 固有の動作については、「 エージェント ID」を参照してください。

この記事の役割

Azure AI Foundry のアクセス許可は、Azure Resource Manager (ARM) コントロール プレーンと Foundry データ プレーンの 2 つのプレーンにまたがります。 所有者 ロールと 共同作成者 ロールには、広範な ARM コントロール プレーンのアクセス許可がありますが、データ プレーンのアクセス許可は含まれません。 エージェントの作成や操作などのデータ プレーン操作には、 Azure AI ユーザー、Azure AI プロジェクト マネージャー、Azure AI 所有者などの特定の Azure AI Foundry ロールが必要 です。

この記事では、次の組み込みロールを参照します。 カスタム ロール定義の詳細については、 Azure カスタム ロールに関するページを参照してください。

症状による迅速な診断

アクセス許可の一般的な問題に対処するセクションに直接移動するには、次のリンクを使用します。

• エージェントを作成できない: エージェントの作成を参照してください
• エージェントがモデルにアクセスできない: エージェントの作成とオプションのアカウント アクセスを参照してください
• デプロイに失敗する: ホストされたエージェントのデプロイと Azure Container Registry のセットアップに関するページを参照してください
• エージェントが実行時にイメージをプルできない: Azure Container Registry のセットアップを参照してください
• エージェントの操作が失敗する: エージェントの操作を参照してください
• ロールの割り当てが失敗する: 「ロールの割り当ての作成に必要なセクションと接続のセットアップ」を参照してください
• Teams または M365 Copilot にエージェントを発行できない: Azure Bot Service のセットアップを参照してください

ホストされるエージェント ソリューションのアーキテクチャ

完了したホステッド エージェントのセットアップには、複数の Azure リソース、ID の割り当て、接続の連携が含まれます。 次の図は、主要なコンポーネントとその関係を示しています。

Foundry Account
├── Model Deployment
└── Foundry Project (has managed identity)
    ├── Hosted Agent
    │   └── Agent Version → references container image
    ├── Connection to Azure Container Registry
    └── Connection to Application Insights

Separate Azure Resources:
├── Azure Container Registry → contains container image
├── Application Insights → logs to Log Analytics Workspace
└── Log Analytics Workspace

Role assignments:
• Foundry Project → Azure AI User role on Foundry Account
• Hosted Agent → Azure AI User role on Foundry Project  
• Foundry Project → Container Registry Repository Reader role on Azure Container Registry
• Foundry Project → Log Analytics Data Reader role on Log Analytics Workspace

Optional (Teams / M365 Copilot publishing):
└── Azure Bot Service → connected to agent application (Channels auth mode)

上の図は、リソースがどのように階層的に編成されているか、およびリソース間の通信を可能にするロールの割り当てを示しています。 次のセクションでは、各コンポーネントの詳細な構成要件について説明します。

必要な Azure リソース

ホストされるエージェントのデプロイごとに、次の Azure リソースを適切に構成する必要があります。

• Foundry アカウント
  • ロールの割り当てにより、プロジェクトのマネージド ID がモデル アクセス用のアカウントにアクセスできるようになります。 Azure AI User は推奨される組み込みロールです。
• モデルのデプロイ (アカウント内)
• Foundry プロジェクト (アカウント内)
  • プロジェクトにはマネージド ID があります。 プロジェクトでは、最初のエージェントの作成時にエージェントブループリントとエージェント ID も取得されます。
  • ロールの割り当てにより、ホストされるエージェントのエージェント ID がモデル アクセスのためにプロジェクトにアクセスできるようになります。 Azure AI User は推奨される組み込みロールです。
  • ロールの割り当てにより、クライアント ユーザーまたはプリンシパルは実行時にプロジェクト内のエージェントと対話できます。 Azure AI User は推奨される組み込みロールです。
• ホストされるエージェント (プロジェクト内)
  • エージェントは、エージェントブループリントとエージェント ID を自動的に取得します。
• エージェントのバージョン (ホストされているエージェント オブジェクト内)
• Azure Container Registry (ACR)
  • ロールの割り当てにより、プロジェクトのマネージド ID はレジストリからイメージをプルできます。 Container Registry Repository Reader は、推奨される組み込みロールです。
  • ロールの割り当てにより、エージェントをデプロイするユーザーまたはサービス プリンシパルがレジストリにイメージをプッシュできます。 Container Registry Repository Writer は、推奨される組み込みロールです。
• Application Insights コンポーネント
• Log Analytics ワークスペース (Application Insights コンポーネントにリンク)
  • ロールの割り当てにより、プロジェクトのマネージド ID が評価用のテレメトリを読み取ることができます。 Log Analytics データ閲覧者 は、推奨される組み込みロールです。
• 複数の接続リソース (プロジェクト内):
  • Azure Container Registry の接続が作成されます。この接続は、プロジェクトがイメージのプルに使用します。
  • Application Insights の接続が作成されます。この接続は、プロジェクトがそのエージェントのテレメトリを出力するために使用します。 この接続では、既定では ID は使用されません。

一部のユーザーまたはプリンシパルには、これらのリソースを作成および管理するためのアクセス許可が必要です。 この記事では、Azure リソースがすべて同じリソース グループ内にある構成を前提とし、そのリソース グループに対する書き込みアクセス権の付与を示します。 このリソース グループアプローチは、多くのチームにとって一般的な構成ですが、特定のセットアップは異なる場合があります。 別のリソース組織戦略がある場合は、使用するリソース グループ間でアクセス許可を分割することが必要になる場合があります。

この一覧には、ネットワーク リソースは含まれません。 ただし、Azure リソースをプロビジョニングするユーザーまたはサービス プリンシパルには、リソースをセキュリティで保護するために、仮想ネットワーク、サブネット、およびプライベート エンドポイントを作成および管理するためのアクセス許可も必要になる場合があります。

Agent applications

エージェント アプリケーションを使用する場合、一覧には次も含まれます。

• エージェント アプリケーション (プロジェクト内)
  • エージェント アプリケーションは、エージェント ブループリントとエージェント ID を自動的に取得します。 ホストされるエージェントのエージェント ID に対して、エージェント アプリケーションのエージェント ID を使用してロールの割り当てを繰り返します。
• エージェントのデプロイ (エージェント アプリケーション内)

Azure リソースのセットアップ

Foundry アカウントのセットアップ

Foundry アカウントを作成するには、リソース グループのスコープで Microsoft.CognitiveServices/accounts/write アクセス許可が必要です。

プロジェクトのマネージド ID は、プロジェクト エンドポイントを介してモデル推論を実行するために Foundry アカウントにアクセスする必要があります。 プロジェクトのアクセスは、Foundry アカウントのスコープで Azure AI User ロールによってカバーされます。 このロールの割り当ては、プロジェクトを作成するユーザーまたはサービス プリンシパルのアクセス許可に応じて、プロジェクトの作成時に自動的に作成される場合があります。

エージェント コードがアカウント レベルの OpenAI エンドポイントに直接アクセスする場合や、プロジェクト エンドポイントによってプロキシされていない他のアカウント レベルの機能にアクセスする場合は、さらにロールの割り当てが必要になる場合があります。 詳細については、「 省略可能なアカウント アクセス」を参照してください。

Model deployment

モデル デプロイを作成するには、Foundry アカウントのスコープで Microsoft.CognitiveServices/accounts/deployments/write アクセス許可が必要です。

Project setup

Foundry プロジェクトを作成するには、Foundry アカウントのスコープで Microsoft.CognitiveServices/accounts/projects/write アクセス許可が必要です。

プロジェクトの作成者がアカウントのスコープで Azure AI User ロールを割り当てる機能を持っている場合、システムは自動的に 2 つのロールの割り当てを作成します。

• プロジェクト作成者には、Foundry アカウントのスコープで Azure AI ユーザー ロールが付与されます。
• プロジェクトのマネージド ID には、Foundry アカウントのスコープで Azure AI ユーザー ロールが付与されます。

プロジェクトのエージェント ID にも同様のロールの割り当てが必要です。 詳細については、「 エージェントの作成」 セクションを参照してください。

Azure Container Registry のセットアップ

Azure Container Registry を作成するには、リソース グループのスコープで Microsoft.ContainerRegistry/registries/write アクセス許可が必要です。

プロジェクトのマネージド ID には、ACR からイメージをプルするためのアクセス許可が必要です。 このタスクに適した 2 つの組み込みロールがあり、ACR レジストリ リソース スコープで割り当てる必要があります。

• Container Registry Repository Reader (プルをデータ アクションとしてモデル化するため推奨)
• AcrPull

そのロールの割り当てを作成するには、ACR レジストリのスコープで Microsoft.Authorization/roleAssignments/write アクセス許可が必要です。

Azure でのロールの割り当ての詳細については、「Azure ロールの割り当ての作成」を参照してください。

¹ これらのロールには roleAssignments/write がありますが、ACR のアクセス許可をカバーしない Azure AI User ロールのみを割り当てる制限があります。

レジストリにイメージをプッシュするユーザーまたはサービス プリンシパルにもロールの割り当てが必要です。 詳細については、「 ホストされるエージェントのデプロイ 」セクションを参照してください。

Application Insights と Log Analytics のセットアップ

Application Insights リソースを作成するには、リソース グループのスコープで Microsoft.Insights/components/write アクセス許可が必要です。

Log Analytics ワークスペースを作成するには、リソース グループのスコープで Microsoft.OperationalInsights/workspaces/write アクセス許可が必要です。

評価機能を使用する予定の場合、プロジェクトのマネージド ID には、Log Analytics ワークスペースから読み取るアクセス許可が必要です。 このアクセスを有効にするには、Log Analytics ワークスペースのスコープでプロジェクトのマネージド ID に Log Analytics Data Reader ロールを付与します。

そのロールの割り当てを作成するには、Log Analytics ワークスペースのスコープで Microsoft.Authorization/roleAssignments/write アクセス許可が必要です。

Azure でのロールの割り当ての詳細については、「Azure ロールの割り当ての作成」を参照してください。

¹ これらのロールには roleAssignments/write がありますが、Log Analytics のアクセス許可をカバーしない Azure AI User ロールのみを割り当てるという制約があります。

Connections setup

接続を作成するには、Foundry プロジェクトのスコープで Microsoft.CognitiveServices/accounts/projects/connections/write アクセス許可が必要です。

接続を作成するユーザーまたはサービス プリンシパルには、Application Insights コンポーネントとコンテナー レジストリの接続情報も必要です。 接続の詳細は、それらのリソースを作成したユーザーまたはサービス プリンシパル、またはそれらのリソースに対する読み取りアクセス権を持つことによって提供できます。

Agent applications

エージェント アプリケーションを使用する場合は、Foundry プロジェクトでエージェント アプリケーションを作成する必要があります。 エージェント アプリケーションを作成するには、Foundry プロジェクトのスコープで Microsoft.CognitiveServices/accounts/projects/applications/write アクセス許可が必要です。

agentDeployment オブジェクトは ARM リソースでもありますが、ホストされるエージェントのデプロイ プロセスの一部として作成されます。 詳細については、 ホストされるエージェントのデプロイに関するページを参照してください。

Agent creation

エージェントは、データ プレーン操作によって作成されます。 エージェントを作成するには、Foundry プロジェクトのスコープで Microsoft.CognitiveServices/accounts/AIServices/agents/write アクセス許可が必要です。

エージェント ID はエージェントの作成後にのみ使用できる可能性があるため、一部のロールの割り当ては、この時点まで作成できません。 プロジェクト エンドポイントでモデル推論を実行するには、エージェント ID には Foundry プロジェクトのスコープで次のアクセス許可が必要です。

• Microsoft.CognitiveServices/accounts/AIServices/responses/*
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/read (カスタム定義の場合は、Microsoft.CognitiveServices/accounts/AIServices/agents/*/read を使用します)
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/write (カスタム定義の場合は、Microsoft.CognitiveServices/accounts/AIServices/agents/*/write を使用します)

そのロールの割り当てを作成するには、Foundry プロジェクトのスコープで Microsoft.Authorization/roleAssignments/write アクセス許可が必要です。

Azure でのロールの割り当ての詳細については、「Azure ロールの割り当ての作成」を参照してください。

¹Azure AI Project Manager と Azure AI Account Owner の両方に、 Azure AI User ロールのみを割り当てることができる制約があります。 エージェントのカスタム ロール定義を使用してプロジェクトにアクセスする場合、 Azure AI Project Manager と Azure AI Account Owner はそのカスタム ロールを割り当てることができません。

省略可能なアカウント アクセス

Foundry SDK とプロジェクト エンドポイントをモデル推論に使用すると、プロジェクトは独自のマネージド ID を使用してアカウント レベルのデプロイの推論呼び出しをプロキシします。 ただし、エージェント コードがプロジェクト エンドポイントをバイパスし、アカウント レベルの OpenAI エンドポイントを直接呼び出す場合 (たとえば、 https://{account}.cognitiveservices.azure.com)、エージェントの ID には、アカウント スコープで次のいずれかのロールが必要です。

• Cognitive Services OpenAI ユーザー - OpenAI データ アクションのみを対象としています。
• Azure AI ユーザー - アカウント上のすべての CognitiveServices データ アクションを対象とします。

アカウント レベルの機能は、プロジェクト エンドポイントによってプロキシされません。 これらの機能には、Speech、Content Safety、Computer Vision、Document Intelligence、Language、Translator が含まれます。 エージェントが直接アクセスする場合は、アカウント スコープでロールの割り当てが必要です。 これらの機能については、アカウント スコープで次のいずれかのロールを割り当てます。

• Cognitive Services ユーザー - Speech、Vision、Language、およびその他の OpenAI 以外の機能について説明します。
• Azure AI ユーザー - OpenAI と前述の機能を含むすべての CognitiveServices データ アクションを 1 つの許可でカバーします。

ホステッド エージェントのデプロイ

ホストされるエージェントのデプロイ操作は、コントロール プレーン操作です。 詳細なデプロイ ガイダンスについては、 ホストされたエージェントのデプロイに関するページを参照してください。

レジストリにイメージをプッシュする

エージェントをデプロイするユーザーまたはサービス プリンシパルには、イメージを ACR にプッシュするためのアクセス許可が必要です。 このタスクに適した 2 つの組み込みロールがあり、ACR レジストリ リソース スコープで割り当てる必要があります。

• コンテナー レジストリ リポジトリ ライター (プッシュをデータ アクションとしてモデル化するため推奨)
• AcrPush

新しいエージェント バージョンを作成する

エージェントを作成するには、Foundry プロジェクトのスコープで Microsoft.CognitiveServices/accounts/AIServices/agents/write アクセス許可が必要です。

エージェント アプリケーションを使用する場合は、新しくデプロイされたエージェント バージョンを参照する agentDeployment オブジェクトも作成する必要があります。 これは管理プレーン操作です。 agentDeployment オブジェクトを作成するには、エージェント アプリケーションのスコープでMicrosoft.CognitiveServices/accounts/projects/applications/agentDeployments/writeアクセス許可が必要です。

新しいバージョンを使用するようにエージェントを更新する

エージェント エンドポイントを使用する場合は、エージェント オブジェクトでバージョンの選択が構成されます。 新しいバージョンを使用するようにエージェントを更新するには、Foundry プロジェクトのスコープで Microsoft.CognitiveServices/accounts/AIServices/agents/write アクセス許可が必要です。

代わりにエージェント アプリケーションを使用する場合は、 エージェント アプリケーション オブジェクトでバージョンの選択が構成されます。 新しい agentDeployment オブジェクトを使用するようにエージェント アプリケーションを更新するには、エージェント アプリケーションのスコープで Microsoft.CognitiveServices/accounts/projects/applications/write アクセス許可が必要です。

Azure Bot Service のセットアップ

Microsoft Teamsまたは Microsoft 365 Copilot へのエージェントの発行は省略可能です。 その場合、発行フローはコントロール プレーン操作を実行して Azure Bot Service リソースを作成し、そのチャネルを構成した後、Bot Service からの要求を許可するようにエージェントまたはエージェント アプリケーションを更新します。

ボット サービスの作成

ボット サービス リソースを作成するには、リソース グループのスコープで Microsoft.BotService/botServices/write アクセス許可が必要です。

Configuring channels

ボット サービスで Teams と Microsoft 365 拡張機能チャネルを構成するには、ボット サービス リソースのスコープで Microsoft.BotService/botServices/channels/write アクセス許可が必要です。

エージェントまたはエージェント アプリケーションの更新

発行フローでは、チャネル (Azure Bot Service) がエージェントまたはエージェント アプリケーションの認証モードとして設定されます。 更新されるオブジェクトは、シナリオによって異なります。

• エージェント アプリケーション のシナリオ: エージェント アプリケーション オブジェクトが更新されます。 これはコントロール プレーンの書き込み操作です。 エージェント アプリケーションに記載されているのと同じロール要件が適用されます。
• エージェント エンドポイントのシナリオ: エージェント オブジェクトが更新されます。 これはデータ プレーン書き込み操作です。 「新しいエージェント バージョンの作成」に記載されているのと同じロール要件が適用されます。

Teams または M365 Copilot への発行に関する詳細なガイダンスについては、「 Microsoft 365 Copilot および Microsoft Teams にエージェントを発行する」を参照してください。

Agent interaction

エージェントと対話するには、呼び出し元のユーザーまたはサービス プリンシパルにデータ プレーンのアクセス許可が必要です。 エージェント アプリケーションと対話するには、 エージェント アプリケーションのスコープで Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action する必要があります。

Agent observability

テレメトリ データの表示

エージェントテレメトリ データにアクセスするには、Application Insights リソースに対する読み取りアクセス許可が必要です。 これには、Azure ポータル、Foundry ポータル、API、監視ツールを使用したトレース、ログ、メトリックの表示が含まれます。

Application Insights リソース スコープで 監視閲覧者 を割り当てます。 このロールの */read アクセス許可は、ワークスペース スコープの個別の割り当てを必要とせずに、基になるLog Analytics ワークスペース データにアクセスします。

Log Analytics ワークスペースに対して直接作業する必要がある場合は、ワークスペース スコープで Log Analytics 閲覧者も割り当てます。

請求通貨でのコスト表示

Foundry ポータルで課金通貨でコストを表示するには、Microsoft.Billing/billingProperty/read アクセス許可が必要です。 このアクセス許可には、サブスクリプションまたは課金アカウントスコープの割り当てが必要です。 リソース グループ スコープでは、このアクセス許可はカバーされません。

このアクセス許可はポータルの表示に便利であり、ホストされるエージェントの機能には必要ありません。 ほとんどのユーザーは、このアクセス許可を安全に省略できます。

Related content

• ホステッド エージェント: ホストされるエージェントのアーキテクチャとライフサイクルについて説明します。
• Microsoft Foundry のロールベースのアクセス制御: 組み込みのロール、スコープ、割り当てパターンを確認します。
• エージェント ID: エージェント ID とプロジェクトマネージド ID の違いについて説明します。