Referenz zu gehosteten Agent-Berechtigungen

Beim Arbeiten mit gehosteten 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-Kontrollebene 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 Begleitartikel zur rollenbasierten Zugriffssteuerung für Microsoft Foundry, der rollenbasierte Zugriffssteuerungskonzepte (RBAC) und die in Microsoft Foundry verfügbaren integrierten Rollen einführt. 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 Azure Resource Manager (ARM)-Steuerungsebene und die Foundry-Datenebene. Besitzer - und Mitwirkenderrollen verfügen über umfassende Berechtigungen für die ARM-Steuerungsebene, enthalten jedoch keine Berechtigungen für die Datenebene. Vorgänge auf der Datenebene – z. B. das Erstellen von Agents oder die Interaktion mit ihnen – erfordern bestimmte Azure AI Foundry-Rollen wie Azure AI-Benutzer, Azure AI-Projektmanager oder Azure AI-Besitzer.

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

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
• Bereitstellung schlägt fehl: Siehe Bereitstellung des gehosteten Agents und Einrichten der Azure-Containerregistrierung
• Agent kann zur Laufzeit keine Images abrufen: Siehe Einrichten der Azure-Containerregistrierung
• Agentinteraktion schlägt fehl: Anzeigen der Agent-Interaktion
• Fehler bei der Rollenzuweisung: Siehe Erstellen dieser Rollenzuweisung erfordert Abschnitte und Das Setup von Connections
• Agent kann nicht in Teams oder M365 Copilot veröffentlicht werden: Siehe Azure Bot Service-Setup

Architektur der gehosteten Agent-Lösung

Eine abgeschlossene Einrichtung eines 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)
• Eine Azure-Containerregistrierung (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
• Ein 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-Containerregistrierung wird eine Verbindung erstellt, die das Projekt für das Abrufen 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 alle innerhalb 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.

Agentanwendungen

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

Zum Erstellen eines Foundry-Kontos ist die Microsoft.CognitiveServices/accounts/write Berechtigung im Bereich der Ressourcengruppe erforderlich.

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 Azure AI User Rolle 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.

Modellimplementierung

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

Projektkonfiguration

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

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

• Dem Projektersteller wird die Azure AI-Benutzerrolle im Bereich des Foundry-Kontos gewährt.
• Die verwaltete Identität des Projekts wird der Azure AI-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 ".

Einrichten der Azure-Containerregistrierung

Zum Erstellen einer Azure-Containerregistrierung ist die Microsoft.ContainerRegistry/registries/write Berechtigung im Bereich der Ressourcengruppe erforderlich.

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

Das Erstellen dieser Rollenzuweisung erfordert die Microsoft.Authorization/roleAssignments/write Berechtigung im Bereich der ACR-Registrierung.

Ausführliche Informationen zum Zuweisen von Rollen in Azure finden Sie unter Erstellen von Azure-Rollenzuweisungen.

¹ Diese Rollen weisen roleAssignments/write jedoch nur die Azure AI User Rolle zu, 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 .

Setup von Application Insights und Log Analytics

Zum Erstellen einer Application Insights-Ressource ist die Microsoft.Insights/components/write Berechtigung im Bereich der Ressourcengruppe erforderlich.

Zum Erstellen eines Log Analytics-Arbeitsbereichs ist die Microsoft.OperationalInsights/workspaces/write Berechtigung 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 verwalteten Identität des Projekts im Bereich des Log Analytics-Arbeitsbereichs die Log Analytics Data Reader Rolle gewähren.

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

Ausführliche Informationen zum Zuweisen von Rollen in Azure finden Sie unter Erstellen von Azure-Rollenzuweisungen.

¹ Diese Rollen sind roleAssignments/write jedoch darauf beschränkt, nur die Azure AI User Rolle zuzuweisen, was keine Log Analytics-Berechtigungen abdeckt.

Setup von Verbindungen

Zum Erstellen einer Verbindung ist die Microsoft.CognitiveServices/accounts/projects/connections/write Berechtigung 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.

Agentanwendungen

Wenn Sie Agent-Anwendungen verwenden, müssen Sie eine Agentanwendung im Foundry-Projekt erstellen. Zum Erstellen einer Agentanwendung ist die Microsoft.CognitiveServices/accounts/projects/applications/write Berechtigung 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-Erstellung

Agents werden über einen Datenebenenvorgang erstellt. Das Erstellen eines Agents erfordert die Microsoft.CognitiveServices/accounts/AIServices/agents/write Berechtigung 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. Um modellbezogene Ableitungen mit dem Projektendpunkt durchzuführen, benötigt die Agentidentität die Microsoft.CognitiveServices/accounts/AIServices/responses/* Berechtigung im Bereich des Foundry-Projekts.

Das Erstellen dieser Rollenzuweisung erfordert die Microsoft.Authorization/roleAssignments/write Berechtigung im Bereich des Foundry-Projekts.

Ausführliche Informationen zum Zuweisen von Rollen in Azure finden Sie unter Erstellen von Azure-Rollenzuweisungen.

¹ Beide und Azure AI Project ManagerAzure AI Account Owner eine Einschränkung haben, die sie nur der Azure AI User Rolle zuweisen können. Wenn Sie eine benutzerdefinierte Rollendefinition für den Agent für den Zugriff auf das Projekt Azure AI Project Manager verwenden möchten und Azure AI Account Owner diese benutzerdefinierte Rolle nicht zuweisen können.

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-Benutzer – deckt alle CognitiveServices-Datenaktionen auf dem Konto ab.

Funktionen auf Kontoebene werden nicht vom Projektendpunkt proxiziert. Zu diesen Funktionen gehören Spracherkennung, Inhaltssicherheit, Computer vision, 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-Benutzer – deckt alle CognitiveServices-Datenaktionen ab, einschließlich OpenAI und der zuvor aufgeführten Funktionen mit einer einzigen Gewährung.

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 Microsoft.CognitiveServices/accounts/AIServices/agents/write Berechtigung 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. Zum Erstellen eines agentDeployment Objekts ist die Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments/write Berechtigung im Bereich der Agentanwendung erforderlich.

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 Microsoft.CognitiveServices/accounts/AIServices/agents/write Berechtigung 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 Microsoft.CognitiveServices/accounts/projects/applications/write Berechtigung im Bereich der Agentanwendung.

Einrichten des Azure Bot-Diensts

Die Veröffentlichung Ihres Agents an 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 Microsoft.BotService/botServices/write Berechtigung im Bereich der Ressourcengruppe erforderlich.

Konfigurieren von Kanälen

Das Konfigurieren der Teams- und Microsoft 365-Erweiterungskanäle für den Botdienst erfordert die Microsoft.BotService/botServices/channels/write Berechtigung im Bereich der Botdienstressource.

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 Veröffentlichen von Agents in Microsoft 365 Copilot und Microsoft Teams.

Agentinteraktion

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 Agentanwendung zu interagieren, benötigen Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action sie im Bereich der Agentanwendung.

Verwandte Inhalte

• Gehostete Agents: Lernen Sie die Architektur und den Lebenszyklus des gehosteten Agents kennen.
• Rollenbasierte 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.