Referenz zu gehosteten Agent-Berechtigungen

Beim Arbeiten mit hosted Agents in Microsoft Foundry ist es wichtig, die verschiedenen berechtigungen zu verstehen. Es gibt mehrere Klassen von Berechtigungen für die Entwicklung gehosteter Agents, die die Azure Resource Manager Steuerungsebene und die Gießereidatenebene umfassen:

• Berechtigungen, die Benutzern oder Prinzipale gewährt werden, die mit Foundry-Ressourcen arbeiten
• Berechtigungen, die dem Foundry-Projekt erteilt wurden
• Berechtigungen, die dem Agent gewährt werden

Dieser Artikel ist ein Begleiter für die Role-basierte Zugriffssteuerung für Microsoft Foundry, in dem rollenbasierte Zugriffssteuerungskonzepte und die integrierten Rollen eingeführt werden, die in Microsoft Foundry verfügbar sind. Bevor Sie fortfahren, sollten Sie sich mit diesem Artikel vertraut machen. In diesem Artikel werden die Vorgänge behandelt, die an der Entwicklung und Bereitstellung gehosteter Agent beteiligt sind, die berechtigungen, die zum Ausführen dieser Vorgänge erforderlich sind und welche integrierten Rollen diese Berechtigungen abdecken.

Informationen zu End-to-End-Bereitstellungs- und Lebenszyklusaufgaben finden Sie unter Bereitstellen eines gehosteten Agents und Verwalten des Lebenszyklus des gehosteten Agents. Informationen zum identitätsspezifischen Verhalten finden Sie unter Agent-Identität.

Rollen in diesem Artikel

Azure AI Foundry Berechtigungen umfassen zwei Ebenen: die steuerebene Azure Resource Manager (ARM) und die Gießereidatenebene. Besitzer - und Mitwirkenderrollen verfügen über umfassende Berechtigungen für die ARM-Steuerungsebene, enthalten jedoch keine Berechtigungen für die Datenebene. Datenebenenvorgänge wie das Erstellen von Agents oder die Interaktion mit ihnen erfordern bestimmte Azure AI Foundry Rollen wie Azure AI User, Azure AI Project Manager oder Azure AI Owner.

In diesem Artikel werden auf die folgenden integrierten Rollen verwiesen. Informationen zu benutzerdefinierten Rollendefinitionen finden Sie unter Azure benutzerdefinierte Rollen.

Schnelle Diagnose durch Symptom

Verwenden Sie diese Links, um direkt zu Abschnitten zu springen, die allgemeine Berechtigungsprobleme beheben:

• Agent kann nicht erstellt werden: Anzeigen der Agenterstellung
• Agent kann nicht auf Modelle zugreifen: Anzeigen der Agent-Erstellung und optionaler Kontozugriff
• Deployment schlägt fehl: Siehe Hosted-Agentbereitstellung und Azure Container Registry Setup
• Agent kann zur Laufzeit keine Bilder abrufen: Siehe Azure Container Registry Setup
• Agentinteraktion schlägt fehl: Anzeigen der Agent-Interaktion
• Fehler bei der Rollenzuweisung: Siehe Erstellen dieser Rollenzuweisung erfordert Abschnitte und Das Setup von Connections
• Kann agent nicht in Teams oder M365 Copilot: Siehe Azure Bot Service Setup

Architektur der gehosteten Agent-Lösung

Eine abgeschlossene Einrichtung des gehosteten Agents umfasst mehrere Azure Ressourcen, Identitätszuweisungen und Verbindungen, die zusammenarbeiten. Das folgende Diagramm zeigt die wichtigsten Komponenten und deren Beziehungen:

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)

Das obige Diagramm zeigt, wie Ressourcen hierarchisch organisiert werden und welche Rollenzuweisungen die Kommunikation zwischen ihnen ermöglichen. Die folgenden Abschnitte enthalten detaillierte Konfigurationsanforderungen für jede Komponente.

Erforderliche Azure-Ressourcen

Für jede bereitstellung gehosteter Agent müssen diese Azure Ressourcen ordnungsgemäß konfiguriert werden:

• Ein Foundry-Konto
  • Mit einer Rollenzuweisung kann die vom Projekt verwaltete Identität auf das Konto für den Modellzugriff zugreifen. Azure AI User ist die empfohlene integrierte Rolle.
• Eine Modellbereitstellung (im Konto)
• Ein Foundry-Projekt (im Konto)
  • Das Projekt verfügt über eine verwaltete Identität. Das Projekt erhält auch eine Agent-Blueprint- und Agent-Identität, wenn der erste Agent erstellt wird.
  • Eine Rollenzuweisung ermöglicht es der Agentidentität des gehosteten Agents, auf das Projekt für den Modellzugriff zuzugreifen. Azure AI User ist die empfohlene integrierte Rolle.
  • Rollenzuweisungen ermöglichen Es Clientbenutzern oder Prinzipale, zur Laufzeit mit Agents im Projekt zu interagieren. Azure AI User ist die empfohlene integrierte Rolle.
• Ein gehosteter Agent (im Projekt)
  • Der Agent ruft automatisch einen Agent-Blueprint und eine Agentidentität ab.
• Eine Agentversion (im gehosteten Agentobjekt)
• An Azure Container Registry (ACR)
  • Mit einer Rollenzuweisung kann die verwaltete Identität des Projekts Bilder aus der Registrierung abrufen. Containerregistrierungs-Repositoryleser ist die empfohlene integrierte Rolle.
  • Eine Rollenzuweisung ermöglicht einem Benutzer oder Dienstprinzipal, der den Agent zum Übertragen von Images in die Registrierung bereitstellt. Container Registry Repository Writer ist die empfohlene integrierte Rolle.
• Eine Application Insights-Komponente
• A Log Analytics Arbeitsbereich (verknüpft mit der Application Insights-Komponente)
  • Eine Rollenzuweisung ermöglicht es der verwalteten Identität des Projekts, Telemetrie für Auswertungen zu lesen. Log Analytics Data Reader ist die empfohlene integrierte Rolle.
• Mehrere Verbindungsressourcen (im Projekt):
  • Für die Azure Container Registry wird eine Verbindung erstellt, die das Projekt für das Ziehen von Bildern verwendet.
  • Für Application Insights wird eine Verbindung erstellt, mit der das Projekt Telemetriedaten für seine Agents ausgibt. Diese Verbindung verwendet standardmäßig keine Identität.

Einige Benutzer oder Prinzipale benötigen die Berechtigung zum Erstellen und Verwalten dieser Ressourcen. In diesem Artikel wird eine Konfiguration vorausgesetzt, bei der sich die Azure Ressourcen in derselben Ressourcengruppe befinden, und zeigt an, dass Schreibzugriff auf diese Ressourcengruppe gewährt wird. Dieser Ressourcengruppenansatz ist eine häufige Konfiguration für viele Teams, ihre spezifische Einrichtung kann jedoch variieren. Wenn Sie über eine andere Ressourcenorganisationsstrategie verfügen, müssen Sie möglicherweise Berechtigungen für die von Ihnen verwendeten Ressourcengruppen aufteilen.

Diese Liste enthält keine Netzwerkressourcen. Der Benutzer oder Dienstprinzipal, der die Azure Ressourcen bereitstellt, benötigt jedoch möglicherweise auch die Berechtigung zum Erstellen und Verwalten virtueller Netzwerke, Subnetze und privater Endpunkte, um die Ressourcen zu sichern.

Agent applications

Wenn Sie Agent-Anwendungen verwenden, enthält die Liste auch Folgendes:

• Eine Agentanwendung (im Projekt)
  • Die Agentanwendung ruft automatisch einen Agent-Blueprint und eine Agentidentität ab. Wiederholen Sie alle Rollenzuweisungen für die Agentidentität des gehosteten Agents mit der Agent-Identität der Agent-Anwendung.
• Eine Agentbereitstellung (in der Agentanwendung)

Azure Ressourcensetup

Setup des Foundry-Kontos

Das Erstellen eines Foundry-Kontos erfordert die Berechtigung Microsoft.CognitiveServices/accounts/write im Bereich der Ressourcengruppe.

Die verwaltete Identität des Projekts benötigt Zugriff auf das Foundry-Konto, um Modelleinschluss über den Projektendpunkt durchzuführen. Der Zugriff des Projekts wird durch die Rolle Azure AI User im Bereich des Foundry-Kontos abgedeckt. Diese Rollenzuweisung kann automatisch erstellt werden, wenn das Projekt erstellt wird, abhängig von den Berechtigungen des Benutzers oder des Dienstprinzipals, der das Projekt erstellt.

Möglicherweise sind weitere Rollenzuweisungen erforderlich, wenn Ihr Agentcode direkt auf den OpenAI-Endpunkt auf Kontoebene zugreift oder andere Funktionen auf Kontoebene, die nicht vom Projektendpunkt bereitgestellt werden. Weitere Informationen finden Sie unter Optionaler Kontozugriff.

Model deployment

Zum Erstellen einer Modellbereitstellung ist die Berechtigung Microsoft.CognitiveServices/accounts/deployments/write im Bereich des Foundry-Kontos erforderlich.

Project setup

Das Erstellen eines Foundry-Projekts erfordert die Berechtigung Microsoft.CognitiveServices/accounts/projects/write im Bereich des Foundry-Kontos.

Wenn der Ersteller des Projekts die Möglichkeit hat, die rolle Azure AI User im Bereich des Kontos zuzuweisen, erstellt das System automatisch zwei Rollenzuweisungen:

• Dem Projektersteller wird die Azure KI-Benutzerrolle im Bereich des Foundry-Kontos gewährt.
• Der verwalteten Identität des Projekts wird die Azure KI-Benutzerrolle im Bereich des Foundry-Kontos gewährt.

Eine ähnliche Rollenzuweisung ist für die Agentidentität über das Projekt erforderlich. Weitere Informationen finden Sie im Abschnitt " Agent Creation ".

Azure Container Registry-Setup

Das Erstellen eines Azure Container Registry erfordert die Berechtigung Microsoft.ContainerRegistry/registries/write im Bereich der Ressourcengruppe.

Die verwaltete Identität des Projekts benötigt Berechtigungen, um das Bild von ACR abzurufen. Für diesen Vorgang sind zwei integrierte Rollen geeignet, die dem ACR-Registrierungsressourcenbereich zugewiesen werden sollten:

• Containerregistrierungs-Repository-Reader (bevorzugt, da er den Pull als Datenaktion modelliert)
• AcrPull

Zum Erstellen dieser Rollenzuweisung ist die berechtigung Microsoft.Authorization/roleAssignments/write im Bereich der ACR-Registrierung erforderlich.

Ausführliche Informationen zum Zuweisen von Rollen in Azure finden Sie unter Create Azure rollen assignments.

¹ Diese Rollen verfügen über roleAssignments/write, sind jedoch darauf beschränkt, nur die rolle Azure AI User zuzuweisen, was keine ACR-Berechtigungen abdeckt.

Der Benutzer- oder Dienstprinzipal, der Bilder in die Registrierung überträgt, benötigt auch eine Rollenzuweisung. Weitere Informationen finden Sie im Abschnitt zur Bereitstellung des gehosteten Agents .

Einrichten von Application Insights und Log Analytics

Das Erstellen einer Application Insights-Ressource erfordert die Berechtigung Microsoft.Insights/components/write im Bereich der Ressourcengruppe.

Zum Erstellen eines Log Analytics Arbeitsbereichs ist die Berechtigung Microsoft.OperationalInsights/workspaces/write im Bereich der Ressourcengruppe erforderlich.

Wenn Sie die Auswertungsfunktion verwenden möchten, benötigt die verwaltete Identität des Projekts Berechtigungen zum Lesen aus dem Log Analytics Arbeitsbereich. Sie können diesen Zugriff aktivieren, indem Sie der rolle Log Analytics Data Reader die verwaltete Identität des Projekts im Bereich des Log Analytics Arbeitsbereichs gewähren.

Das Erstellen dieser Rollenzuweisung erfordert die Berechtigung Microsoft.Authorization/roleAssignments/write im Bereich des Log Analytics Arbeitsbereichs.

Ausführliche Informationen zum Zuweisen von Rollen in Azure finden Sie unter Create Azure rollen assignments.

¹ Diese Rollen verfügen über roleAssignments/write, sind jedoch darauf beschränkt, nur die rolle Azure AI User zuzuweisen, die nicht Log Analytics Berechtigungen abdeckt.

Connections setup

Zum Erstellen einer Verbindung ist die Berechtigung Microsoft.CognitiveServices/accounts/projects/connections/write im Bereich des Foundry-Projekts erforderlich.

Der Benutzer oder Dienstprinzipal, der die Verbindungen erstellt, benötigt auch die Verbindungsinformationen für die Application Insights-Komponente und die Containerregistrierung. Die Verbindungsdetails können vom Benutzer oder Dienstprinzipal bereitgestellt werden, der diese Ressourcen erstellt hat, oder durch Lesezugriff auf diese Ressourcen.

Agent applications

Wenn Sie Agent-Anwendungen verwenden, müssen Sie eine Agentanwendung im Foundry-Projekt erstellen. Zum Erstellen einer Agentanwendung ist die berechtigung Microsoft.CognitiveServices/accounts/projects/applications/write im Bereich des Foundry-Projekts erforderlich.

agentDeployment Objekte sind auch ARM-Ressourcen, aber sie werden als Teil des Bereitstellungsprozesses des gehosteten Agents erstellt. Weitere Informationen finden Sie unter Bereitstellung des gehosteten Agents.

Agent creation

Agents werden über einen Datenebenenvorgang erstellt. Das Erstellen eines Agents erfordert die Berechtigung Microsoft.CognitiveServices/accounts/AIServices/agents/write im Bereich des Foundry-Projekts.

Da die Agentidentität nach dem Erstellen des Agents möglicherweise nur verfügbar ist, können einige Rollenzuweisungen erst nach diesem Zeitpunkt erstellt werden. Zum Durchführen der Modellferencierung mit dem Projektendpunkt erfordert die Agentidentität die folgenden Berechtigungen im Bereich des Foundry-Projekts:

• Microsoft.CognitiveServices/accounts/AIServices/responses/*
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/read (verwenden Sie für benutzerdefinierte Definitionen Microsoft.CognitiveServices/accounts/AIServices/agents/*/read)
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/write (verwenden Sie für benutzerdefinierte Definitionen Microsoft.CognitiveServices/accounts/AIServices/agents/*/write)

Zum Erstellen dieser Rollenzuweisung ist die Berechtigung Microsoft.Authorization/roleAssignments/write im Bereich des Foundry-Projekts erforderlich.

Ausführliche Informationen zum Zuweisen von Rollen in Azure finden Sie unter Create Azure rollen assignments.

¹ Sowohl Azure AI Project Manager als auch Azure AI Account Owner weisen nur die Rolle Azure AI User zu. Wenn Sie beabsichtigen, eine benutzerdefinierte Rollendefinition für den Agent für den Zugriff auf die project zu verwenden, können Azure AI Project Manager und Azure AI Account Owner diese benutzerdefinierte Rolle nicht zuweisen.

Optionaler Kontozugriff

Wenn Sie das Foundry SDK und den Projektendpunkt für modellbasierte Ableitung verwenden, leitet die Projektproxys Aufrufe an die Bereitstellung auf Kontoebene mithilfe ihrer eigenen verwalteten Identität ab. Wenn Ihr Agentcode den Projektendpunkt jedoch umgeht und den OpenAI-Endpunkt auf Kontoebene direkt aufruft (z https://{account}.cognitiveservices.azure.com. B. ), benötigt die Identität des Agents eine der folgenden Rollen im Kontobereich:

• Cognitive Services OpenAI User - deckt nur OpenAI-Datenaktionen ab.
• Azure AI User – deckt alle CognitiveServices-Datenaktionen auf dem Konto ab.

Funktionen auf Kontoebene werden nicht vom Projektendpunkt proxiziert. Zu diesen Funktionen gehören Spracherkennung, Inhaltssicherheit, Maschinelles Sehen, Dokumentintelligenz, Sprache und Übersetzer. Sie erfordern eine Rollenzuweisung im Kontobereich, wenn Ihr Agent direkt darauf zugreift. Weisen Sie für diese Funktionen eine der folgenden Rollen im Kontobereich zu:

• Cognitive Services User - behandelt Spracherkennung, Vision, Sprache und andere Nicht-OpenAI-Funktionen.
• Azure AI User – umfasst alle CognitiveServices-Datenaktionen, einschließlich OpenAI und der zuvor aufgeführten Funktionen, mit einer einzigen Genehmigung.

Bereitstellung gehosteter Agent

Gehostete Agent-Bereitstellungsvorgänge sind Steuerungsebenenvorgänge. Eine schrittweise Bereitstellungsanleitung finden Sie unter Bereitstellen eines gehosteten Agents.

Übertragen eines Bilds in die Registrierung

Der Benutzer oder Dienstprinzipal, der den Agent bereitstellt, benötigt die Berechtigung, das Image an ACR zu übertragen. Für diesen Vorgang sind zwei integrierte Rollen geeignet, die dem ACR-Registrierungsressourcenbereich zugewiesen werden sollten:

• Containerregistrierungs-Repository Writer (bevorzugt, da sie den Push als Datenaktion modelliert)
• AcrPush

Erstellen einer neuen Agentversion

Das Erstellen eines Agents erfordert die Berechtigung Microsoft.CognitiveServices/accounts/AIServices/agents/write im Bereich des Foundry-Projekts.

Wenn Sie Agent-Anwendungen verwenden, müssen Sie auch ein agentDeployment Objekt erstellen, das auf eine neu bereitgestellte Agentversion verweist. Dies ist ein Verwaltungsebenenbetrieb. Das Erstellen eines agentDeployment-Objekts erfordert die Berechtigung Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments/write im Bereich der Agentanwendung.

Aktualisieren des Agents für die Verwendung der neuen Version

Wenn Sie den Agentendpunkt verwenden, wird die Versionsauswahl für das Agentobjekt konfiguriert. Das Aktualisieren des Agents für die Verwendung der neuen Version erfordert die Berechtigung Microsoft.CognitiveServices/accounts/AIServices/agents/write im Bereich des Foundry-Projekts.

Wenn Sie stattdessen die Agentanwendung verwenden, wird die Versionsauswahl für das Agentanwendungsobjekt konfiguriert. Das Aktualisieren der Agentanwendung für die Verwendung des neuen agentDeployment-Objekts erfordert die berechtigung Microsoft.CognitiveServices/accounts/projects/applications/write im Bereich der Agentanwendung.

Azure Bot Service Setup

Die Veröffentlichung Ihres Agents auf Microsoft Teams oder Microsoft 365 Copilot ist optional. Wenn Sie dies tun, führt der Veröffentlichungsablauf Steuerungsebenenvorgänge aus, um eine Azure Bot Service Ressource zu erstellen und seine Kanäle zu konfigurieren, aktualisiert dann entweder den Agent oder die Agentanwendung, um Anforderungen von Bot Service zuzulassen.

Erstellen des Botdiensts

Zum Erstellen der Botdienstressource ist die berechtigung Microsoft.BotService/botServices/write im Bereich der Ressourcengruppe erforderlich.

Configuring channels

Für die Konfiguration der Teams- und Microsoft 365-Erweiterungskanäle im Botdienst ist die Berechtigung Microsoft.BotService/botServices/channels/write im Bereich der Botdienstressource erforderlich.

Aktualisieren der Agent- oder Agentanwendung

Der Veröffentlichungsfluss legt Kanäle (Azure Bot Service) als Authentifizierungsmodus für die Agent- oder Agentanwendung fest. Das objekt, das aktualisiert wird, hängt von Ihrem Szenario ab:

• Agentanwendungsszenario: Das Agentanwendungsobjekt wird aktualisiert. Dies ist ein Steuerungsebenen-Schreibvorgang. Die gleichen Rollenanforderungen gelten wie in Agentanwendungen dokumentiert.
• Agentendpunktszenario: Das Agentobjekt wird aktualisiert. Dies ist ein Datenebenen-Schreibvorgang. Die gleichen Rollenanforderungen gelten wie in "Erstellen einer neuen Agentversion".

Eine schrittweise Anleitung zum Veröffentlichen in Teams oder M365-Copilot finden Sie unter Publish-Agents zum Microsoft 365 Copilot und Microsoft Teams.

Agent interaction

Für die Interaktion mit dem Agent muss der aufrufende Benutzer oder Dienstprinzipal über eine Berechtigung für die Datenebene verfügen. Um mit einer agent-Anwendung zu interagieren benötigen sie Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action im Bereich der Agentanwendung.

Agent observability

Anzeigen von Telemetriedaten

Für den Zugriff auf Agent-Telemetriedaten sind Leseberechtigungen für die Application Insights-Ressource erforderlich. Dazu gehören das Anzeigen von Ablaufverfolgungen, Protokollen und Metriken über das Azure Portal, das Foundry-Portal, APIs und Überwachungstools.

Weisen Sie den Überwachungsleser im Ressourcenbereich "Application Insights" zu. Die berechtigungen */read in dieser Rolle greifen auf die zugrunde liegenden Log Analytics Arbeitsbereichsdaten zu, ohne dass eine separate Arbeitsbereichszuweisung erforderlich ist.

Wenn Sie direkt mit dem Log Analytics Arbeitsbereich arbeiten müssen, weisen Sie auch Log Analytics Reader im Arbeitsbereichsbereich zu.

Kostenanzeige in Abrechnungswährung

Das Anzeigen von Kosten in Abrechnungswährung im Foundry-Portal erfordert die Berechtigung Microsoft.Billing/billingProperty/read. Für diese Berechtigung ist eine Abonnement- oder Abrechnungskontozuweisung erforderlich. Der Ressourcengruppenbereich deckt diese Berechtigung nicht ab.

Diese Berechtigung dient der Benutzerfreundlichkeit des Portals und ist nicht für gehostete Agent-Funktionen erforderlich. Sie können diese Berechtigung für die meisten Benutzer sicher weglassen.

Related content

• Gehostete Agents: Lernen Sie die Architektur und den Lebenszyklus des gehosteten Agents kennen.
• Role-basierte Zugriffssteuerung für Microsoft Foundry: Überprüfen sie integrierte Rollen, Bereiche und Zuordnungsmuster.
• Agentidentität: Verstehen, wie sich die vom Agent verwaltete Identität und die vom Projekt verwaltete Identität unterscheiden.