Naslaginformatie over gehoste agentmachtigingen

Wanneer u werkt met Hosted-agents in Microsoft Foundry, is het belangrijk om de verschillende betrokken machtigingen te begrijpen. Er zijn verschillende klassen machtigingen betrokken bij het ontwikkelen van gehoste agents, die betrekking hebben op het Azure Resource Manager besturingsvlak en het gegevensvlak Foundry:

  • Machtigingen verleend aan gebruikers of principals die werken met Foundry-resources
  • Machtigingen verleend aan het Foundry-project
  • Machtigingen verleend aan de agent

Dit artikel is een aanvulling op Toegangsbeheer op basis van rollen voor Microsoft Foundry, waarin op rollen gebaseerd toegangsbeheer (RBAC) en de ingebouwde rollen worden geïntroduceerd die beschikbaar zijn in Microsoft Foundry. U moet vertrouwd raken met dat artikel voordat u doorgaat. In dit artikel worden de bewerkingen behandeld die betrokken zijn bij het ontwikkelen en implementeren van gehoste agents, de machtigingen die nodig zijn om deze bewerkingen uit te voeren en welke ingebouwde rollen deze machtigingen omvatten.

Zie Een gehoste agent implementeren en de levenscyclus van gehoste agents beheren voor end-to-end-implementatie- en levenscyclustaken. Zie Agent-identiteit voor specifiek gedrag.

Important

Houd altijd aan het principe van minimale bevoegdheden bij het toewijzen van machtigingen. Wijs alleen de machtigingen toe die nodig zijn voor gebruikers en agents om hun taken uit te voeren en regelmatig machtigingen te controleren en bij te werken.

Als u een coderingsagent zoals GitHub Copilot gebruikt, kan de Microsoft Foundry Skill helpen bij het toewijzen van vereiste rollen en machtigingen voor implementatie- en beheertaken in uw eigen Foundry-project.

Rollen in dit artikel

Azure AI Foundry machtigingen omvatten twee vlakken: het Azure Resource Manager -besturingsvlak (ARM) en het gegevensvlak Foundry. De rollen Eigenaar en Inzender hebben uitgebreide ARM-besturingsvlakmachtigingen, maar bevatten geen machtigingen voor het gegevensvlak. Gegevensvlakbewerkingen, zoals het maken van agents of interactie met deze agents, vereisen specifieke Azure AI Foundry rollen zoals Foundry User, Foundry Project Manager of Foundry Owner.

Important

De rollen Foundry RBAC zijn onlangs hernoemd. Foundry User, Foundry Owner, Foundry Account Owner en Foundry Project Manager zijn eerder benoemd Azure AI-gebruiker, Azure AI-eigenaar Azure AI-accounteigenaar en Azure AI Project Manager. Mogelijk ziet u nog steeds de vorige namen op sommige plaatsen terwijl de naam van de naam wordt uitgerold. De rol-id's en kernmachtigingen worden ongewijzigd door de naam.

Dit artikel verwijst naar de volgende ingebouwde rollen. Zie Azure aangepaste rollen voor meer informatie over aangepaste roldefinities.

Rol Doel bij implementatie van gehoste agent
Owner Volledige machtigingen voor het maken en beheren van Azure resources
Contributor Azure-resources maken en beheren
Op rollen gebaseerd toegangsbeheerbeheerder Roltoewijzingen maken voor Azure resources
Foundry Agent Consumer Interactie met agenteindpunten (rol met minimale bevoegdheden voor consumenten)
Foundry-gebruiker Agents maken, modeldeductie uitvoeren en communiceren met agents
Foundry Project Manager Projecten beheren, agents maken, modeldeductie uitvoeren, communiceren met agents en roltoewijzingen maken
Eigenaar van foundry-account Implementaties maken, projecten beheren en resources op accountniveau verwerken. Maak alleen roltoewijzingen voor besturingsvlakbewerkingen. Kan geen gegevensvlakbewerkingen uitvoeren, zoals het maken of gebruiken van agents.
Eigenaar van foundry Machtigingen voor het volledige besturingsvlak en gegevensvlak voor accountbronnen, maar kunnen geen roltoewijzingen maken
Lezer containerregisteropslagplaats Containerinstallatiekopieën ophalen uit het register
Schrijver van Container Registry Repository Containerinstallatiekopieën naar het register pushen
AcrPull Containerinstallatiekopieën ophalen uit het register
AcrPush Containerinstallatiekopieën naar het register pushen
Log Analytics Gegevenslezer Telemetriegegevens lezen voor evaluaties
Cognitive Services OpenAI-gebruiker OpenAI-eindpunten op accountniveau rechtstreeks openen
Cognitive Services-gebruiker Toegang tot mogelijkheden op accountniveau (Speech, Vision, Language) rechtstreeks

Caution

Hoewel het kan lijken op een geschikte rol voor een ontwikkelaar die met gehoste agents werkt, is de ingebouwde rol Azure AI Developer onvoldoende voor scenario's met gehoste agents. Deze rol is gericht op Azure Machine Learning- en Foundry-hubs, niet op de Foundry-projectresources die worden gebruikt door gehoste agents en bevat niet de resourcebeheermachtigingen die zijn vereist voor de implementatie van een gehoste agent.

Snelle diagnose per symptoom

Gebruik deze koppelingen om rechtstreeks naar secties te gaan waarmee veelvoorkomende machtigingsproblemen worden opgelost:

Architectuur van gehoste agentoplossing

Een voltooide installatie van een gehoste agent omvat meerdere Azure resources, identiteitstoewijzingen en verbindingen die samenwerken. In het volgende diagram ziet u de belangrijkste onderdelen en de bijbehorende relaties:

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 → Foundry User role on Foundry Account
• 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)

In het bovenstaande diagram ziet u hoe resources hiërarchisch worden georganiseerd en welke roltoewijzingen communicatie tussen deze resources mogelijk maken. De volgende secties bevatten gedetailleerde configuratievereisten voor elk onderdeel.

Vereiste Azure resources

Voor elke implementatie van een gehoste agent moeten deze Azure resources correct worden geconfigureerd:

  • Een Foundry-account
    • Met een roltoewijzing kan de door het project beheerde identiteit toegang krijgen tot het account voor modeltoegang. Foundry User is de aanbevolen ingebouwde rol voor de door het project beheerde identiteit.
  • Een modelimplementatie (in het account)
  • Een Foundry-project (in het account)
    • Het project heeft een beheerde identiteit. Het project krijgt ook een blauwdruk en agentidentiteit van een agent wanneer de eerste agent wordt gemaakt.
    • Met roltoewijzingen kunnen clientgebruikers of principals tijdens runtime communiceren met agents in het project. Foundry Agent Consumer is de aanbevolen ingebouwde rol voor consumenten die alleen met agents hoeven te communiceren.
    • Voor sommige geavanceerde scenario's zijn mogelijk expliciete roltoewijzingen vereist voor de agentidentiteit in het project. Zie Expliciete toegang op projectniveau voor meer informatie.
  • Een gehoste agent (in het project)
    • De agent haalt automatisch een blauwdruk en agentidentiteit van een agent op.
  • Een agentversie (in het object Hosted Agent)
  • Een Azure Container Registry (ACR)
    • Met een roltoewijzing kan de beheerde identiteit van het project installatiekopieën ophalen uit het register. Container Registry Repository Reader is de aanbevolen ingebouwde rol.
    • Met een roltoewijzing kan een gebruiker of service-principal die de agent implementeert, installatiekopieën naar het register pushen. Container Registry Repository Writer is de aanbevolen ingebouwde rol.
  • Een Application Insights-onderdeel
  • A Log Analytics werkruimte (gekoppeld aan het Application Insights-onderdeel)
    • Met een roltoewijzing kan de beheerde identiteit van het project telemetrie voor evaluaties lezen. Log Analytics Gegevenslezer is de aanbevolen ingebouwde rol.
  • Verschillende verbindingsbronnen (in het project):
    • Er wordt een verbinding gemaakt voor de Azure Container Registry, die door het project wordt gebruikt voor het ophalen van installatiekopieën.
    • Er wordt een verbinding gemaakt voor Application Insights, die door het project wordt gebruikt voor het verzenden van telemetriegegevens voor de agents. Deze verbinding maakt niet standaard gebruik van identiteit.

Sommige gebruikers of principals hebben toestemming nodig om deze resources te maken en te beheren. In dit artikel wordt uitgegaan van een configuratie waarbij de Azure resources zich allemaal binnen dezelfde resourcegroep bevinden en laat zien hoe u schrijftoegang verleent voor die resourcegroep. Deze resourcegroepbenadering is een algemene configuratie voor veel teams, maar uw specifieke configuratie kan variëren. Als u een andere strategie voor de organisatie van resources hebt, moet u mogelijk machtigingen opsplitsen over de resourcegroepen die u gebruikt.

Deze lijst bevat geen netwerkresources. De gebruiker of service-principal die de Azure resources in richt, heeft echter mogelijk ook toestemming nodig om virtuele netwerken, subnetten en privé-eindpunten te maken en te beheren om de resources te beveiligen.

Agenttoepassingen

Als u agenttoepassingen gebruikt, bevat de lijst ook:

  • Een agenttoepassing (in het project)
    • De agenttoepassing haalt automatisch een blauwdruk en agentidentiteit van een agent op. Als u expliciete roltoewijzingen configureert voor de agentidentiteit van de gehoste agent (zoals voor geavanceerde scenario's), herhaalt u deze toewijzingen voor de agent-id van de agenttoepassing.
  • Een agentimplementatie (in de agenttoepassing)

Azure-resource instellen

Instellingen van Foundry-account

Voor het maken van een Foundry-account is de machtiging Microsoft.CognitiveServices/accounts/write vereist voor het bereik van de resourcegroep.

Ingebouwde rol Scope Kan de toegewezen gebruiker een Foundry-account maken?
Eigenaar Resourcegroep ✔ Ja
Donateur Resourcegroep ✔ Ja
Foundry-gebruiker Resourcegroep ✗ Nee
Foundry Projectmanager Resourcegroep ✗ Nee
Eigenaar van foundry-account Resourcegroep ✔ Ja
Eigenaar van foundry Resourcegroep ✔ Ja

De beheerde identiteit van het project heeft toegang nodig tot het Foundry-account om modeldeductie uit te voeren via het projecteindpunt. De toegang van het project wordt gedekt door de rol Foundry User binnen het bereik van het Foundry-account. Deze roltoewijzing kan automatisch worden gemaakt wanneer het project wordt gemaakt, afhankelijk van de machtigingen van de gebruiker of service-principal die het project maakt.

Er zijn mogelijk meer roltoewijzingen nodig als uw agentcode rechtstreeks toegang heeft tot het OpenAI-eindpunt op accountniveau of andere mogelijkheden op accountniveau die niet door het projecteindpunt worden geproxied. Zie Toegang op accountniveau voor meer informatie.

Modellenimplementatie

Voor het maken van een modelimplementatie is de machtiging Microsoft.CognitiveServices/accounts/deployments/write vereist voor het bereik van het Foundry-account.

Ingebouwde rol Scope Kan een toegewezen gebruiker een model implementeren in een Foundry-account?
Eigenaar Foundry-account ✔ Ja
Donateur Foundry-account ✔ Ja
Foundry-gebruiker Foundry-account ✗ Nee
Foundry Projectmanager Foundry-account ✗ Nee
Eigenaar van foundry-account Foundry-account ✔ Ja
Eigenaar van foundry Foundry-account ✔ Ja

Projectopstelling

Voor het maken van een Foundry-project is de machtiging Microsoft.CognitiveServices/accounts/projects/write vereist voor het bereik van het Foundry-account.

Ingebouwde rol Scope Kan de toegewezen gebruiker een Foundry-project maken?
Eigenaar Foundry-account ✔ Ja
Donateur Foundry-account ✔ Ja
Foundry-gebruiker Foundry-account ✗ Nee
Foundry Projectmanager Foundry-account ✔ Ja
Eigenaar van foundry-account Foundry-account ✔ Ja
Eigenaar van foundry Foundry-account ✔ Ja

Als de maker van het project de mogelijkheid heeft om de rol Foundry User toe te wijzen aan het bereik van het account, worden automatisch twee roltoewijzingen gemaakt:

  • De maker van het project krijgt de rol Foundry User op het bereik van het Foundry-account.
  • Aan de beheerde identiteit van het project wordt de rol Foundry-gebruiker verleend binnen het bereik van het Foundry-account.

Azure Container Registry instellen

Voor het maken van een Azure Container Registry is de machtiging Microsoft.ContainerRegistry/registries/write vereist voor het bereik van de resourcegroep.

Note

Voor gehoste agents is ondersteuning voor het containerregister achter een particulier netwerk (privé-eindpunt met openbare netwerktoegang uitgeschakeld) afhankelijk van wanneer het Foundry-project is gemaakt. Projecten die zijn gemaakt na 25 juni 2026 ondersteunen een privéregister. Voor projecten die vóór die datum zijn gemaakt, moet het register bereikbaar zijn via het openbare eindpunt. Bestaande projecten worden niet beïnvloed. Zie Beperkingen voor de volledige lijst met netwerkbeperkingen.

De beleidsstatus van azureADAuthenticationAsArmPolicy het register moet worden ingesteld op enabled. Met deze instelling kan ACR Microsoft Entra tokens accepteren die zijn gericht op Azure Resource Manager. Als u de status wilt controleren of bijwerken, gebruikt u az acr config authentication-as-arm.

Ingebouwde rol Scope Kan de toegewezen gebruiker een containerregister maken?
Eigenaar Resourcegroep ✔ Ja
Donateur Resourcegroep ✔ Ja
Foundry-gebruiker Resourcegroep ✗ Nee
Foundry Projectmanager Resourcegroep ✗ Nee
Eigenaar van foundry-account Resourcegroep ✗ Nee
Eigenaar van foundry Resourcegroep ✗ Nee

De beheerde identiteit van het project heeft machtigingen nodig om de installatiekopie op te halen uit ACR. Er zijn twee ingebouwde rollen die geschikt zijn voor deze taak, die moeten worden toegewezen aan het resourcebereik van het ACR-register:

Voor het maken van deze roltoewijzing is de machtiging Microsoft.Authorization/roleAssignments/write vereist voor het bereik van het ACR-register.

Zie Create Azure role assignments voor meer informatie over het toewijzen van rollen in Azure.

Ingebouwde rol Scope Kan de toegewezen gebruiker een roltoewijzing maken?
Eigenaar ACR-register ✔ Ja
Donateur ACR-register ✗ Nee
Foundry-gebruiker ACR-register ✗ Nee
Foundry Projectmanager ACR-register ✗ Geen1
Eigenaar van foundry-account ACR-register ✗ Geen1
Eigenaar van foundry ACR-register ✗ Nee
Beheerder op basis van rollen Access Control ACR-register ✔ Ja

1 Deze rollen hebben roleAssignments/write, maar zijn beperkt om alleen de rol Foundry User toe te wijzen, die geen betrekking heeft op ACR-machtigingen.

De gebruiker of service-principal die installatiekopieën naar het register pusht, heeft ook een roltoewijzing nodig. Zie de sectie Gehoste agentimplementatie voor meer informatie.

Application Insights en Log Analytics instellen

Voor het maken van een Application Insights-resource is de machtiging Microsoft.Insights/components/write vereist voor het bereik van de resourcegroep.

Ingebouwde rol Scope Kan de toegewezen gebruiker een Application Insights-resource maken?
Eigenaar Resourcegroep ✔ Ja
Donateur Resourcegroep ✔ Ja
Foundry-gebruiker Resourcegroep ✗ Nee
Foundry Projectmanager Resourcegroep ✗ Nee
Eigenaar van foundry-account Resourcegroep ✗ Nee
Eigenaar van foundry Resourcegroep ✗ Nee

Voor het maken van een Log Analytics werkruimte is de machtiging Microsoft.OperationalInsights/workspaces/write vereist voor het bereik van de resourcegroep.

Ingebouwde rol Scope Kan de toegewezen gebruiker een Log Analytics werkruimte maken?
Eigenaar Resourcegroep ✔ Ja
Donateur Resourcegroep ✔ Ja
Foundry-gebruiker Resourcegroep ✗ Nee
Foundry Projectmanager Resourcegroep ✗ Nee
Eigenaar van foundry-account Resourcegroep ✗ Nee
Eigenaar van foundry Resourcegroep ✗ Nee

Als u van plan bent om de evaluatiefunctie te gebruiken, heeft de beheerde identiteit van het project machtigingen nodig om te lezen uit de Log Analytics werkruimte. U kunt deze toegang inschakelen door de rol Log Analytics Data Reader toe te kennen aan de beheerde identiteit van het project op het bereik van de Log Analytics werkruimte.

Voor het maken van deze roltoewijzing is de machtiging Microsoft.Authorization/roleAssignments/write vereist voor het bereik van de Log Analytics werkruimte.

Zie Create Azure role assignments voor meer informatie over het toewijzen van rollen in Azure.

Ingebouwde rol Scope Kan de toegewezen gebruiker een roltoewijzing maken?
Eigenaar Log Analytics werkruimte ✔ Ja
Donateur Log Analytics werkruimte ✗ Nee
Foundry-gebruiker Log Analytics werkruimte ✗ Nee
Foundry Projectmanager Log Analytics werkruimte ✗ Geen1
Eigenaar van foundry-account Log Analytics werkruimte ✗ Geen1
Eigenaar van foundry Log Analytics werkruimte ✗ Nee
Beheerder op basis van rollen Access Control Log Analytics werkruimte ✔ Ja

1 Deze rollen hebben roleAssignments/write, maar zijn beperkt om alleen de rol Foundry User toe te wijzen, die geen betrekking heeft op Log Analytics machtigingen.

Installatie van verbindingen

Voor het maken van een verbinding is de machtiging Microsoft.CognitiveServices/accounts/projects/connections/write vereist voor het bereik van het Foundry-project.

Ingebouwde rol Scope Kan de toegewezen gebruiker een verbinding maken?
Eigenaar Gieterijproject ✔ Ja
Donateur Gieterijproject ✔ Ja
Foundry-gebruiker Gieterijproject ✗ Nee
Foundry Projectmanager Gieterijproject ✔ Ja
Eigenaar van foundry-account Gieterijproject ✔ Ja
Eigenaar van foundry Gieterijproject ✔ Ja

De gebruiker of service-principal die de verbindingen maakt, heeft ook de verbindingsgegevens nodig voor het Application Insights-onderdeel en het containerregister. De verbindingsgegevens kunnen worden verstrekt door de gebruiker of service-principal die deze resources heeft gemaakt of door leestoegang te hebben tot deze resources.

Note

Gehoste agents maken vaak gebruik van hulpprogramma's en verbindingen die gericht zijn op meer Azure resources. Voor deze resources zijn mogelijk extra roltoewijzingen vereist voor de aanroepende identiteit of de agentidentiteit in het doelresourcebereik. Hulpprogramma's die bijvoorbeeld toegang hebben tot Storage, Azure AI Zoeken, Key Vault of databases, vereisen doorgaans hun eigen machtigingen voor het gegevensvlak, naast de basisinstellingen die in dit artikel worden beschreven.

Agenttoepassingen

Als u agenttoepassingen gebruikt, moet u een agenttoepassing maken in het Foundry-project. Voor het maken van een agenttoepassing is de machtiging Microsoft.CognitiveServices/accounts/projects/applications/write vereist voor het bereik van het Foundry-project.

Ingebouwde rol Scope Kan de toegewezen gebruiker een agenttoepassing maken?
Eigenaar Gieterijproject ✔ Ja
Donateur Gieterijproject ✔ Ja
Foundry-gebruiker Gieterijproject ✗ Nee
Foundry Projectmanager Gieterijproject ✔ Ja
Eigenaar van foundry-account Gieterijproject ✔ Ja
Eigenaar van foundry Gieterijproject ✔ Ja

agentDeployment objecten zijn ook ARM-resources, maar ze worden gemaakt als onderdeel van het implementatieproces van de gehoste agent. Zie Gehoste agentimplementatie voor meer informatie.

Agent maken

Agents worden gemaakt via een gegevensvlakbewerking. Voor het maken van een agent is de machtiging Microsoft.CognitiveServices/accounts/AIServices/agents/write vereist voor het bereik van het Foundry-project.

Ingebouwde rol Scope Kan de toegewezen gebruiker een agent maken?
Eigenaar Gieterijproject ✗ Nee
Donateur Gieterijproject ✗ Nee
Foundry-gebruiker Gieterijproject ✔ Ja
Foundry Projectmanager Gieterijproject ✔ Ja
Eigenaar van foundry-account Gieterijproject ✗ Nee
Eigenaar van foundry Gieterijproject ✔ Ja

De agent heeft impliciete toegang tot kernmogelijkheden binnen een eigen project, zoals modeldeductie. Er is geen expliciete roltoewijzing nodig voor de standaardcase. Zie Agenttoegang buiten de standaardinstellingen voor geavanceerde scenario's waarvoor expliciete toegang is vereist.

Implementatie van gehoste agent

Gehoste agentimplementatiebewerkingen zijn besturingsvlakbewerkingen. Zie Een gehoste agent implementeren voor stapsgewijze instructies.

Een installatiekopieën naar het register pushen

De gebruiker of service-principal die de agent implementeert, moet zijn gemachtigd om de installatiekopieën naar ACR te pushen. Er zijn twee ingebouwde rollen die geschikt zijn voor deze taak, die moeten worden toegewezen aan het resourcebereik van het ACR-register:

Een nieuwe agentversie maken

Voor het maken van een agent is de machtiging Microsoft.CognitiveServices/accounts/AIServices/agents/write vereist voor het bereik van het Foundry-project.

Ingebouwde rol Scope Kan de toegewezen gebruiker een agentversie maken?
Eigenaar Gieterijproject ✗ Nee
Donateur Gieterijproject ✗ Nee
Foundry-gebruiker Gieterijproject ✔ Ja
Foundry Projectmanager Gieterijproject ✔ Ja
Eigenaar van foundry-account Gieterijproject ✗ Nee
Eigenaar van foundry Gieterijproject ✔ Ja

Als u agenttoepassingen gebruikt, moet u ook een agentDeployment object maken dat verwijst naar een nieuw geïmplementeerde agentversie. Dit is een beheervlakbewerking. Voor het maken van een agentDeployment-object is de machtiging Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments/write vereist voor het bereik van de agenttoepassing.

Ingebouwde rol Scope Kan de toegewezen gebruiker een agentDeployment object maken?
Eigenaar Foundry-account ✔ Ja
Donateur Foundry-account ✔ Ja
Foundry-gebruiker Foundry-account ✗ Nee
Foundry Projectmanager Foundry-account ✔ Ja
Eigenaar van foundry-account Foundry-account ✔ Ja
Eigenaar van foundry Foundry-account ✔ Ja

De agent bijwerken om de nieuwe versie te gebruiken

Als u het agenteindpunt gebruikt, wordt versieselectie geconfigureerd op het agentobject. Voor het bijwerken van de agent voor het gebruik van de nieuwe versie is de machtiging Microsoft.CognitiveServices/accounts/AIServices/agents/write vereist voor het bereik van het Foundry-project.

Ingebouwde rol Scope Kan de agentversie worden bijgewerkt door de toegewezen gebruiker?
Eigenaar Gieterijproject ✗ Nee
Donateur Gieterijproject ✗ Nee
Foundry-gebruiker Gieterijproject ✔ Ja
Foundry Projectmanager Gieterijproject ✔ Ja
Eigenaar van foundry-account Gieterijproject ✗ Nee
Eigenaar van foundry Gieterijproject ✔ Ja

Als u in plaats daarvan de agenttoepassing gebruikt, wordt versieselectie geconfigureerd op het toepassingsobject van de agent. Voor het bijwerken van de agenttoepassing voor het gebruik van het nieuwe agentDeployment-object is de machtiging Microsoft.CognitiveServices/accounts/projects/applications/write vereist voor het bereik van de agenttoepassing.

Ingebouwde rol Scope Kan de toegewezen gebruiker de agenttoepassing bijwerken?
Eigenaar Foundry-account ✔ Ja
Donateur Foundry-account ✔ Ja
Foundry-gebruiker Foundry-account ✗ Nee
Foundry Projectmanager Foundry-account ✔ Ja
Eigenaar van foundry-account Foundry-account ✔ Ja
Eigenaar van foundry Foundry-account ✔ Ja

Azure Bot Service instellen

Het publiceren van uw agent naar Microsoft Teams of Microsoft 365 Copilot is optioneel. Wanneer u dit doet, voert de publicatiestroom besturingsvlakbewerkingen uit om een Azure Bot Service resource te maken en de kanalen te configureren, waarna de agent of de agenttoepassing wordt bijgewerkt om aanvragen van Bot Service toe te staan.

De botservice maken

Voor het maken van de botserviceresource is de machtiging Microsoft.BotService/botServices/write vereist voor het bereik van de resourcegroep.

Ingebouwde rol Scope Kan de toegewezen gebruiker een botservice maken?
Eigenaar Resourcegroep ✔ Ja
Donateur Resourcegroep ✔ Ja
Foundry-gebruiker Resourcegroep ✗ Nee
Foundry Projectmanager Resourcegroep ✗ Nee
Eigenaar van foundry-account Resourcegroep ✗ Nee
Eigenaar van foundry Resourcegroep ✗ Nee

Note

Azure Bot Service is een afzonderlijk resourcetype van Foundry. Azure ingebouwde AI-rollen bevatten geen Microsoft.BotService/* machtigingen.

Kanalen configureren

Voor het configureren van de teams- en Microsoft 365-uitbreidingskanalen op de botservice is de machtiging Microsoft.BotService/botServices/channels/write vereist voor het bereik van de botserviceresource.

Ingebouwde rol Scope Kan de toegewezen gebruiker kanalen configureren?
Eigenaar Botservice ✔ Ja
Donateur Botservice ✔ Ja
Foundry-gebruiker Botservice ✗ Nee
Foundry Projectmanager Botservice ✗ Nee
Eigenaar van foundry-account Botservice ✗ Nee
Eigenaar van foundry Botservice ✗ Nee

De agent- of agenttoepassing bijwerken

De publicatiestroom stelt kanalen (Azure Bot Service) in als de verificatiemodus op de agent- of agenttoepassing. Het object dat wordt bijgewerkt, is afhankelijk van uw scenario:

  • Scenario van agenttoepassing: het agenttoepassingsobject wordt bijgewerkt. Dit is een schrijfbewerking voor het besturingsvlak. Dezelfde rolvereisten zijn van toepassing zoals beschreven in Agent-toepassingen.
  • Scenario van agenteindpunt: het agentobject wordt bijgewerkt. Dit is een schrijfbewerking voor het gegevensvlak. Dezelfde rolvereisten zijn van toepassing zoals beschreven in Een nieuwe agentversie maken.

Zie Agents publiceren naar Microsoft 365 Copilot en Microsoft Teams voor stapsgewijze instructies voor het publiceren naar Teams of M365 Copilot.

Agentinteractie

Voor interactie met de agent moet de aanroepende gebruiker of service-principal een machtiging voor het gegevensvlak hebben:

  • Voor interactie met een agenteindpunt hebben ze het bereik van het Foundry-project of het bereik van de specifieke agent nodig Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action . Deze machtiging omvat alle runtime-interacties met de agent, inclusief maar niet beperkt tot API-aanroepen voor antwoorden.
  • Voor interactie met een agenttoepassing hebben ze Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action nodig binnen het bereik van de agenttoepassing.

Tip

Foundry Agent Consumer is de ingebouwde rol met minimale bevoegdheden voor gebruikers en service-principals die communiceren met agenteindpunten. Gebruik deze rol in plaats van Foundry User wanneer de principal geen agents hoeft te maken of te wijzigen.

Ingebouwde rol Scope Kan de toegewezen gebruiker communiceren met agenteindpunten? Kan de toegewezen gebruiker communiceren met agenttoepassingen?
Eigenaar Gieterijproject ✗ Nee ✗ Nee
Donateur Gieterijproject ✗ Nee ✗ Nee
Foundry Agent Consumer Foundry-project of -agent ✔ Ja ✗ Nee
Foundry-gebruiker Gieterijproject ✔ Ja ✔ Ja
Foundry Projectmanager Gieterijproject ✔ Ja ✔ Ja
Eigenaar van foundry-account Gieterijproject ✗ Nee ✗ Nee
Eigenaar van foundry Gieterijproject ✔ Ja ✔ Ja

U kunt ook rollen toewijzen aan het bereik van een specifieke agent in plaats van aan het hele project. Zie Roltoewijzingen voor agentbereik voor meer informatie.

De identiteit van de eindgebruiker delegeren

Een service in de middelste laag die zijn eigen eindgebruikers verifieert, kan een sessie beperken tot een specifieke eindgebruiker door de x-ms-user-identity header te verzenden. Als u deze header wilt verzenden, moet de aanroepende identiteit de volgende machtiging voor het gegevensvlak van de agent bevatten:

Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action

Deze gegevensactie is niet opgenomen in een ingebouwde rol. Rollen die deze eerder hebben verleend via de Microsoft.CognitiveServices/* gegevensactie, waaronder Foundry User en Foundry Owner , doen dit niet meer. Als u deze wilt verlenen, maakt u een aangepaste rol die de gegevensactie bevat en wijst u die rol toe aan de identiteit van de service in de middelste laag op het bereik van het Foundry-project of de specifieke agent.

De volgende aangepaste roldefinitie verleent alleen de actie imitatiegegevens:

{
  "Name": "Foundry Agent User Identity Impersonation",
  "IsCustom": true,
  "Description": "Lets a trusted middle-tier service delegate the end-user identity to a hosted agent via the x-ms-user-identity header.",
  "Actions": [],
  "NotActions": [],
  "DataActions": [
    "Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>"
  ]
}

Maak de rol en wijs deze vervolgens toe aan de identiteit in de middelste laag:

az role definition create --role-definition custom-impersonation-role.json

az role assignment create \
  --assignee <middle-tier-identity-object-id> \
  --role "Foundry Agent User Identity Impersonation" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>

Een beller die zonder deze machtiging wordt verzonden x-ms-user-identity , ontvangt een 403. Zie Gehoste agentsessies per gebruiker isoleren voor meer informatie over het gebruik van gedelegeerde identiteiten.

Waarneembaarheid van agent

Telemetriegegevens weergeven

Voor toegang tot telemetriegegevens van agents zijn leesmachtigingen vereist voor de Application Insights-resource. Dit omvat het weergeven van traceringen, logboeken en metrische gegevens via de Azure-portal, Foundry-portal, API's en bewakingshulpprogramma's.

Wijs bewakingslezer toe aan het resourcebereik van Application Insights. De */read-machtigingen in deze rol hebben toegang tot de onderliggende Log Analytics werkruimtegegevens zonder dat hiervoor een afzonderlijke toewijzing met werkruimtebereik is vereist.

Als u rechtstreeks wilt werken met de Log Analytics werkruimte, wijst u ook Log Analytics Reader toe aan het werkruimtebereik. Als de werkruimtetabellen zijn beveiligd, wijst u ook Privileged Monitoring Data Reader toe om de beveiligde tabellen te lezen.

Ingebouwde rol Scope Kunnen toegewezen toegangsagenttelemetriegegevens?
Eigenaar Application Insights ✔ Ja
Donateur Application Insights ✔ Ja
Foundry-gebruiker Application Insights ✗ Nee (zie metrische gegevens, maar geen traceringen)
Foundry Projectmanager Application Insights ✗ Nee
Eigenaar van foundry-account Application Insights ✗ Nee (zie metrische gegevens, maar geen traceringen)
Eigenaar van foundry Application Insights ✗ Nee
Monitoringslezer Application Insights ✔ Ja
Log Analytics Lezer Log Analytics werkruimte ✔ Ja (rechtstreeks vanuit werkruimte)
Bevoorrechte lezer van bewakingsgegevens Log Analytics werkruimte ✔ Ja (vereist voor beveiligde tabellen)

Kosten worden weergegeven in factureringsvaluta

Voor het weergeven van kosten in factureringsvaluta in de Foundry-portal is de machtiging Microsoft.Billing/billingProperty/read vereist. Voor deze machtiging is een abonnements- of factureringsaccounttoewijzing vereist. Het bereik van de resourcegroep heeft geen betrekking op deze machtiging.

Deze machtiging is voor het gemak van de portalweergave en is niet vereist voor de functionaliteit van de hostende agent. U kunt deze machtiging veilig weglaten voor de meeste gebruikers.

Ingebouwde rol Scope Kunnen toegewezen kosten weergeven in factureringsvaluta?
Eigenaar Subscription ✔ Ja
Donateur Subscription ✔ Ja
Kostenbeheerlezer Subscription ✔ Ja
Foundry-gebruiker Subscription ✗ Nee

Agenttoegang buiten de standaardinstellingen

Standaard heeft een agent impliciete toegang tot kernmogelijkheden binnen een eigen project. Er is geen expliciete roltoewijzing of aanvullende configuratie nodig voor de standaardcase. Impliciete toegang omvat:

  • Modeldeductie via het projecteindpunt
  • Lees- en schrijfbewerkingen voor sessieopslag

Er zijn mogelijk extra machtigingen nodig wanneer een agent verbonden hulpprogramma's gebruikt die toegang hebben tot externe resources, verwijst naar gegevens buiten een eigen project of werkt op accountniveau.

Expliciete toegang op projectniveau

Voor sommige geavanceerde scenario's zijn mogelijk expliciete roltoewijzingen vereist voor de agentidentiteit in het Foundry-project. In deze sectie wordt een overzicht gegeven van de machtigingsbehoeften alsof de agent geen impliciete toegang tot het project heeft.

Als er geen impliciete toegang is, heeft de agentidentiteit de volgende machtigingen nodig voor het bereik van het Foundry-project om modeldeductie uit te voeren met het projecteindpunt:

  • Microsoft.CognitiveServices/accounts/AIServices/responses/*
  • Microsoft.CognitiveServices/accounts/AIServices/agents/storage/read (voor aangepaste definities gebruikt u Microsoft.CognitiveServices/accounts/AIServices/agents/*/read)
  • Microsoft.CognitiveServices/accounts/AIServices/agents/storage/write (voor aangepaste definities gebruikt u Microsoft.CognitiveServices/accounts/AIServices/agents/*/write)
Ingebouwde rol Scope Kan de toegewezen agent modeldeductie uitvoeren?
Eigenaar Gieterijproject ✗ Nee
Donateur Gieterijproject ✗ Nee
Foundry-gebruiker Gieterijproject ✔ Ja
Foundry Projectmanager Gieterijproject ✔ Ja
Eigenaar van foundry-account Gieterijproject ✗ Nee
Eigenaar van foundry Gieterijproject ✔ Ja

Tip

Foundry User is de ingebouwde rol met minimale bevoegdheden waarmee modeldeductie met het projecteindpunt kan worden uitgevoerd. Het bevat echter een bredere set machtigingen dan strikt noodzakelijk is voor deze bewerking. Als u de bevoegdheden voor uw agent wilt verlagen, kunt u een aangepaste rol maken met alleen Microsoft.CognitiveServices/accounts/AIServices/responses/*, Microsoft.CognitiveServices/accounts/AIServices/agents/*/read en Microsoft.CognitiveServices/accounts/AIServices/agents/*/write. Houd er rekening mee dat voor de standaardcase geen roltoewijzing is vereist, dus u hoeft dit alleen toe te voegen in geavanceerde scenario's.

Voor het maken van deze roltoewijzing is de machtiging Microsoft.Authorization/roleAssignments/write vereist voor het bereik van het Foundry-project.

Zie Create Azure role assignments voor meer informatie over het toewijzen van rollen in Azure.

Ingebouwde rol Scope Kan de toegewezen gebruiker een roltoewijzing maken?
Eigenaar Gieterijproject ✔ Ja
Donateur Gieterijproject ✗ Nee
Foundry-gebruiker Gieterijproject ✗ Nee
Foundry Projectmanager Gieterijproject ✔ Ja voor Foundry User rol1
Eigenaar van foundry-account Gieterijproject ✔ Ja voor Foundry User rol1
Eigenaar van foundry Gieterijproject ✗ Nee
Beheerder op basis van rollen Access Control Gieterijproject ✔ Ja

1 Zowel Foundry Project Manager als Foundry Account Owner hebben een beperking dat ze alleen de rol Foundry User kunnen toewijzen. Als u van plan bent om een aangepaste roldefinitie voor de agent te gebruiken voor toegang tot de project, kan Foundry Project Manager en Foundry Account Owner die aangepaste rol niet toewijzen.

Note

Omdat de roltoewijzing nodig is voor de agentidentiteit, kan deze pas worden gemaakt nadat de agent is gemaakt. Daarom heeft de gebruiker of principal die de agent maakt, ook machtigingen nodig om roltoewijzingen te maken. Foundry Project Manager in het project bereik is de aanbevolen roltoewijzing voor makers van agents in dit scenario, omdat deze rol zowel de vereiste machtigingen voor het gegevensvlak als de mogelijkheid om de rol Foundry User toe te wijzen.

Toegang op accountniveau

Wanneer u de Foundry SDK en het projecteindpunt gebruikt voor modeldeductie, roept de projectproxy's deductie aan naar de implementatie op accountniveau met behulp van een eigen beheerde identiteit. Als uw agentcode echter het projecteindpunt omzeilt en het OpenAI-eindpunt op accountniveau rechtstreeks aanroept (bijvoorbeeld https://{account}.cognitiveservices.azure.com), heeft de identiteit van de agent een van de volgende rollen nodig voor het accountbereik:

Mogelijkheden op accountniveau worden niet geproxied door het projecteindpunt. Deze mogelijkheden zijn onder andere Spraak, Inhoudsveiligheid, Computer Vision, Document Intelligence, Taal en Translator. Ze hebben een roltoewijzing in accountbereik nodig als uw agent deze rechtstreeks opent. Wijs voor deze mogelijkheden een van de volgende rollen toe voor accountbereik:

  • Cognitive Services-gebruiker : behandelt spraak-, vision-, taal- en andere niet-OpenAI-mogelijkheden.
  • Foundry User : behandelt alle CognitiveServices-gegevensacties, waaronder OpenAI en de eerder vermelde mogelijkheden, met één subsidie.

Verwante inhoud

Koppelingsdefinities
  • Last updated on