Referens för värdbaserade agentbehörigheter

När du arbetar med Hosted-agenter i Microsoft Foundry är det viktigt att du förstår de olika behörigheterna. Det finns flera behörighetsklasser som ingår i utveckling av värdbaserade agenter, som sträcker sig över Azure Resource Manager kontrollplanet och Foundry-dataplanet:

  • Behörigheter som beviljas användare eller huvudnamn som arbetar med Foundry-resurser
  • Behörigheter som beviljats till Foundry-projektet
  • Behörigheter som beviljats agenten

Den här artikeln är ett komplement till Role-baserad åtkomstkontroll för Microsoft Foundry, som introducerar rollbaserad åtkomstkontroll (RBAC) och inbyggda roller som är tillgängliga i Microsoft Foundry. Du bör bekanta dig med den artikeln innan du fortsätter. Den här artikeln beskriver de åtgärder som ingår i utveckling och distribution av värdbaserade agenter, de behörigheter som krävs för att utföra dessa åtgärder och vilka inbyggda roller som omfattar dessa behörigheter.

Information om distribution och livscykeluppgifter från slutpunkt till slutpunkt finns i Distribuera en värdbaserad agent och Hantera värdbaserad agentlivscykel. Information om identitetsspecifikt beteende finns i Agentidentitet.

Important

Följ alltid principen om lägsta behörighet när du tilldelar behörigheter. Bevilja endast de behörigheter som krävs för att användare och agenter ska kunna utföra sina uppgifter och regelbundet granska och uppdatera behörigheter efter behov.

Roller i den här artikeln

Azure AI Foundry behörigheter omfattar två plan: kontrollplanet Azure Resource Manager (ARM) och Foundry-dataplanet. Ägar- och deltagarroller har breda behörigheter för ARM-kontrollplan men inkluderar inte behörigheter för dataplanet. Dataplansåtgärder – till exempel att skapa agenter eller interagera med dem – kräver specifika Azure AI Foundry roller som Foundry User, Foundry Project Manager eller Foundry Owner.

Important

RbAC-rollerna för Foundry har nyligen bytt namn. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

Den här artikeln refererar till följande inbyggda roller. Information om anpassade rolldefinitioner finns i Azure anpassade roller.

Roll Syfte i distribution av värdbaserad agent
Ägare Fullständig behörighet för att skapa och hantera Azure resurser
Bidragsgivare Skapa och hantera Azure resurser
Ole-baserad Access Control administratör Skapa rolltilldelningar på Azure resurser
Foundry Agent-konsument Interagera med agentslutpunkter (minsta behörighetsroll för konsumenter)
Foundry-användare Skapa agenter, utföra modellinferens och interagera med agenter
Foundry-projektledare Hantera projekt, skapa agenter, utföra modellinferens, interagera med agenter och skapa rolltilldelningar
Foundry-kontoägare Skapa distributioner, hantera projekt och hantera resurser på kontonivå. Skapa rolltilldelningar endast för kontrollplansåtgärder. Det går inte att utföra dataplansåtgärder som att skapa eller interagera med agenter.
Foundry-ägare Behörigheter för fullständigt kontrollplan och dataplan över kontoresurser, men det går inte att skapa rolltilldelningar
Läsare av Containerregister Hämta containeravbildningar från registret
Behörighet: Skribent för Containerregisterarkiv Skicka containeravbildningar till registret
AcrPull Hämta containeravbildningar från registret
AcrPush Skicka containeravbildningar till registret
Log Analytics dataläsare Läsa telemetridata för utvärderingar
Cognitive Services OpenAI-användare Få åtkomst till OpenAI-slutpunkter på kontonivå direkt
Cognitive Services-användare Få åtkomst till funktioner på kontonivå (Speech, Vision, Language) direkt

Caution

Även om det kan låta som en lämplig roll för en utvecklare som arbetar med värdbaserade agenter, är den Azure AI Developer inbyggda rollen inte tillräcklig för scenarier med värdbaserad agent. Den här rollen är begränsad till Azure Machine Learning och Foundry-hubbar, inte till foundry-projektresurser som används av värdbaserade agenter, och den innehåller inte de resurshanteringsbehörigheter som krävs för distribution av värdbaserad agent.

Snabbdiagnos efter symptom

Använd de här länkarna om du vill gå direkt till avsnitt som hanterar vanliga behörighetsproblem:

Lösningsarkitektur för värdbaserad agent

En slutförd konfiguration av värdbaserad agent omfattar flera Azure resurser, identitetstilldelningar och anslutningar som fungerar tillsammans. Följande diagram visar nyckelkomponenterna och deras relationer:

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)

Diagrammet ovan visar hur resurser organiseras hierarkiskt och vilka rolltilldelningar som möjliggör kommunikation mellan dem. Följande avsnitt innehåller detaljerade konfigurationskrav för varje komponent.

Nödvändiga Azure resurser

Varje distribution av värdbaserad agent kräver att dessa Azure resurser konfigureras korrekt:

  • Ett Foundry-konto
    • Med en rolltilldelning kan projekthanterad identitet komma åt kontot för modellåtkomst. Foundry User är den rekommenderade inbyggda rollen för projektets hanterade identitet.
  • En modelldistribution (i kontot)
  • Ett Foundry-projekt (i kontot)
    • Projektet har en hanterad identitet. Projektet hämtar också en agentritning och agentidentitet när dess första agent skapas.
    • Rolltilldelningar gör det möjligt för klientanvändare eller huvudnamn att interagera med agenter i projektet vid körning. Foundry Agent Consumer är den rekommenderade inbyggda rollen för konsumenter som bara behöver interagera med agenter.
    • Vissa avancerade scenarier kan kräva explicita rolltilldelningar för agentidentiteten i projektet. Mer information finns i Explicit åtkomst på projektnivå.
  • En värdbaserad agent (i projektet)
    • Agenten hämtar automatiskt en agentritning och agentidentitet.
  • En agentversion (i hosted agent-objektet)
  • En Azure Container Registry (ACR)
    • Med en rolltilldelning kan projektets hanterade identitet hämta avbildningar från registret. Container Registry Repository Reader är den rekommenderade inbyggda rollen.
    • En rolltilldelning gör det möjligt för en användare eller tjänstens huvudnamn som distribuerar agenten att skicka avbildningar till registret. Container Registry Repository Writer är den rekommenderade inbyggda rollen.
  • En Application Insights-komponent
  • A Log Analytics arbetsyta (länkad till Application Insights-komponenten)
    • Med en rolltilldelning kan projektets hanterade identitet läsa telemetri för utvärderingar. Log Analytics Data Reader är den rekommenderade inbyggda rollen.
  • Flera anslutningsresurser (i projektet):
    • En anslutning skapas för Azure Container Registry, som projektet använder för bildhämtning.
    • En anslutning skapas för Application Insights, som projektet använder för att generera telemetri för sina agenter. Den här anslutningen använder inte identitet som standard.

Vissa användare eller huvudnamn behöver behörighet att skapa och hantera dessa resurser. Den här artikeln förutsätter en konfiguration där alla Azure resurser finns i samma resursgrupp och visar hur du beviljar skrivåtkomst över den resursgruppen. Den här resursgruppsmetoden är en vanlig konfiguration för många team, men din specifika konfiguration kan variera. Om du har en annan resursorganisationsstrategi kan du behöva dela upp behörigheter mellan de resursgrupper som du använder.

Den här listan innehåller inte nätverksresurser. Användaren eller tjänstens huvudnamn som etablerar Azure resurser kan dock också behöva behörighet att skapa och hantera virtuella nätverk, undernät och privata slutpunkter för att skydda resurserna.

Agentapplikationer

Om du använder agentprogram innehåller listan även:

  • Ett agentprogram (i projektet)
    • Agentprogrammet hämtar automatiskt en agentritning och agentidentitet. Om du konfigurerar explicita rolltilldelningar för den värdbaserade agentens agentidentitet (till exempel för avancerade scenarier) upprepar du dessa tilldelningar för agentprogrammets agentidentitet.
  • En agentdistribution (i agentprogrammet)

Azure resurskonfiguration

Konfiguration av Foundry-konto

För att skapa ett Foundry-konto krävs behörigheten Microsoft.CognitiveServices/accounts/write i resursgruppens omfång.

Fördefinierad roll Scope Kan tilldelningsmottagaren skapa ett Foundry-konto?
Ägare Resursgrupp ✔ Ja
Deltagare Resursgrupp ✔ Ja
Foundry-användare Resursgrupp ✗ Nej
Foundry-projektledare Resursgrupp ✗ Nej
Foundry-kontoägare Resursgrupp ✔ Ja
Foundry-ägare Resursgrupp ✔ Ja

Projektets hanterade identitet behöver åtkomst till Foundry-kontot för att utföra modellinferens via projektslutpunkten. Projektets åtkomst omfattas av rollen Foundry User i omfånget för Foundry-kontot. Den här rolltilldelningen kan skapas automatiskt när projektet skapas, beroende på behörigheterna för användaren eller tjänstens huvudnamn som skapar projektet.

Fler rolltilldelningar kan behövas om din agentkod kommer åt OpenAI-slutpunkten på kontonivå direkt eller andra funktioner på kontonivå som inte påverkas av projektslutpunkten. Mer information finns i Åtkomst på kontonivå.

Modellimplementering

För att skapa en modelldistribution krävs behörigheten Microsoft.CognitiveServices/accounts/deployments/write i omfånget för Foundry-kontot.

Fördefinierad roll Scope Kan tilldelningsmottagare distribuera en modell till ett Foundry-konto?
Ägare Foundry-konto ✔ Ja
Deltagare Foundry-konto ✔ Ja
Foundry-användare Foundry-konto ✗ Nej
Foundry-projektledare Foundry-konto ✗ Nej
Foundry-kontoägare Foundry-konto ✔ Ja
Foundry-ägare Foundry-konto ✔ Ja

Projektinställningar

För att skapa ett Foundry-projekt krävs behörigheten Microsoft.CognitiveServices/accounts/projects/write i foundry-kontots omfång.

Fördefinierad roll Scope Kan tilldelningsmottagaren skapa ett Foundry-projekt?
Ägare Foundry-konto ✔ Ja
Deltagare Foundry-konto ✔ Ja
Foundry-användare Foundry-konto ✗ Nej
Foundry-projektledare Foundry-konto ✔ Ja
Foundry-kontoägare Foundry-konto ✔ Ja
Foundry-ägare Foundry-konto ✔ Ja

Om projektets skapare har möjlighet att tilldela rollen Foundry User i kontots omfång skapar systemet automatiskt två rolltilldelningar:

  • Projektskapare beviljas rollen Foundry-användare i omfånget för Foundry-kontot.
  • Projektets hanterade identitet beviljas rollen Foundry-användare i omfånget för Foundry-kontot.

Azure Container Registry konfiguration

För att skapa en Azure Container Registry krävs behörigheten Microsoft.ContainerRegistry/registries/write i resursgruppens omfång.

Note

För värdbaserade agenter beror stöd för containerregistret bakom ett privat nätverk (privat slutpunkt med åtkomst till offentligt nätverk inaktiverad) på när Foundry-projektet skapades. Projekt som skapats efter den 25 juni 2026 stöder ett privat register. Projekt som skapades före det datumet kräver att registret kan nås via dess offentliga slutpunkt. Befintliga projekt påverkas inte. En fullständig lista över nätverksbegränsningar finns i Begränsningar.

Registrets azureADAuthenticationAsArmPolicy principstatus måste anges till enabled. Med den här inställningen kan ACR acceptera Microsoft Entra token som är begränsade till Azure Resource Manager. Om du vill kontrollera eller uppdatera statusen använder du az acr config authentication-as-arm.

Fördefinierad roll Scope Kan tilldelningsmottagaren skapa ett containerregister?
Ägare Resursgrupp ✔ Ja
Deltagare Resursgrupp ✔ Ja
Foundry-användare Resursgrupp ✗ Nej
Foundry-projektledare Resursgrupp ✗ Nej
Foundry-kontoägare Resursgrupp ✗ Nej
Foundry-ägare Resursgrupp ✗ Nej

Projektets hanterade identitet behöver behörighet att hämta avbildningen från ACR. Det finns två inbyggda roller som är lämpliga för den här uppgiften, som bör tilldelas i ACR-registrets resursomfång:

För att skapa rolltilldelningen krävs behörigheten Microsoft.Authorization/roleAssignments/write i omfånget för ACR-registret.

Mer information om hur du tilldelar roller i Azure finns i Skapa Azure rolltilldelningar.

Fördefinierad roll Scope Kan tilldelad skapa en rolltilldelning?
Ägare ACR-register ✔ Ja
Deltagare ACR-register ✗ Nej
Foundry-användare ACR-register ✗ Nej
Foundry-projektledare ACR-register ✗ Nr1
Foundry-kontoägare ACR-register ✗ Nr1
Foundry-ägare ACR-register ✗ Nej
Rollbaserad Access Control administratör ACR-register ✔ Ja

1 Dessa roller har roleAssignments/write men är begränsade till att endast tilldela rollen Foundry User, som inte omfattar ACR-behörigheter.

Användaren eller tjänstens huvudnamn som skickar avbildningar till registret behöver också en rolltilldelning. Mer information finns i avsnittet Distribution av värdbaserad agent .

Installation av Application Insights och Log Analytics

För att skapa en Application Insights-resurs krävs behörigheten Microsoft.Insights/components/write i resursgruppens omfång.

Fördefinierad roll Scope Kan tilldelad skapa en Application Insights-resurs?
Ägare Resursgrupp ✔ Ja
Deltagare Resursgrupp ✔ Ja
Foundry-användare Resursgrupp ✗ Nej
Foundry-projektledare Resursgrupp ✗ Nej
Foundry-kontoägare Resursgrupp ✗ Nej
Foundry-ägare Resursgrupp ✗ Nej

För att skapa en Log Analytics arbetsyta krävs behörigheten Microsoft.OperationalInsights/workspaces/write i resursgruppens omfång.

Fördefinierad roll Scope Kan tilldelad skapa en Log Analytics arbetsyta?
Ägare Resursgrupp ✔ Ja
Deltagare Resursgrupp ✔ Ja
Foundry-användare Resursgrupp ✗ Nej
Foundry-projektledare Resursgrupp ✗ Nej
Foundry-kontoägare Resursgrupp ✗ Nej
Foundry-ägare Resursgrupp ✗ Nej

Om du planerar att använda utvärderingsfunktionen behöver projektets hanterade identitet behörighet att läsa från Log Analytics arbetsytan. Du kan aktivera den här åtkomsten genom att bevilja rollen Log Analytics Data Reader till projektets hanterade identitet i omfånget för Log Analytics arbetsyta.

För att kunna skapa rolltilldelningen krävs behörigheten Microsoft.Authorization/roleAssignments/write i omfånget för Log Analytics arbetsyta.

Mer information om hur du tilldelar roller i Azure finns i Skapa Azure rolltilldelningar.

Fördefinierad roll Scope Kan tilldelad skapa en rolltilldelning?
Ägare Log Analytics arbetsyta ✔ Ja
Deltagare Log Analytics arbetsyta ✗ Nej
Foundry-användare Log Analytics arbetsyta ✗ Nej
Foundry-projektledare Log Analytics arbetsyta ✗ Nr1
Foundry-kontoägare Log Analytics arbetsyta ✗ Nr1
Foundry-ägare Log Analytics arbetsyta ✗ Nej
Rollbaserad Access Control administratör Log Analytics arbetsyta ✔ Ja

1 Dessa roller har roleAssignments/write men är begränsade till att endast tilldela rollen Foundry User, som inte omfattar Log Analytics behörigheter.

Konfiguration av anslutningar

För att skapa en anslutning krävs behörigheten Microsoft.CognitiveServices/accounts/projects/connections/write i omfånget för Foundry-projektet.

Fördefinierad roll Scope Kan tilldelningsmottagaren skapa en anslutning?
Ägare Gjuteri projekt ✔ Ja
Deltagare Gjuteri projekt ✔ Ja
Foundry-användare Gjuteri projekt ✗ Nej
Foundry-projektledare Gjuteri projekt ✔ Ja
Foundry-kontoägare Gjuteri projekt ✔ Ja
Foundry-ägare Gjuteri projekt ✔ Ja

Användaren eller tjänstens huvudnamn som skapar anslutningarna behöver också anslutningsinformation för Application Insights-komponenten och containerregistret. Anslutningsinformationen kan tillhandahållas av användaren eller tjänstens huvudnamn som skapade dessa resurser, eller genom att ha läsbehörighet över dessa resurser.

Note

Värdbaserade agenter använder ofta verktyg och anslutningar som är inriktade på mer Azure resurser. Dessa resurser kan kräva extra rolltilldelningar för den anropande identiteten eller agentidentiteten i målresursomfånget. Till exempel kräver verktyg som har åtkomst till Lagring, Azure AI-sökning, Key Vault eller databaser vanligtvis sina egna behörigheter för dataplanet utöver de grundläggande installationsbehörigheter som beskrivs i den här artikeln.

Agentapplikationer

Om du använder agentprogram måste du skapa ett agentprogram i Foundry-projektet. För att skapa ett agentprogram krävs behörigheten Microsoft.CognitiveServices/accounts/projects/applications/write i omfånget för Foundry-projektet.

Fördefinierad roll Scope Kan tilldelad skapa ett agentprogram?
Ägare Gjuteri projekt ✔ Ja
Deltagare Gjuteri projekt ✔ Ja
Foundry-användare Gjuteri projekt ✗ Nej
Foundry-projektledare Gjuteri projekt ✔ Ja
Foundry-kontoägare Gjuteri projekt ✔ Ja
Foundry-ägare Gjuteri projekt ✔ Ja

agentDeployment objekt är också ARM-resurser, men de skapas som en del av distributionsprocessen för värdbaserad agent. Mer information finns i Distribution av värdbaserad agent.

Skapa agent

Agenter skapas via en dataplansåtgärd. För att skapa en agent krävs behörigheten Microsoft.CognitiveServices/accounts/AIServices/agents/write i omfånget för Foundry-projektet.

Fördefinierad roll Scope Kan tilldelad skapa en agent?
Ägare Gjuteri projekt ✗ Nej
Deltagare Gjuteri projekt ✗ Nej
Foundry-användare Gjuteri projekt ✔ Ja
Foundry-projektledare Gjuteri projekt ✔ Ja
Foundry-kontoägare Gjuteri projekt ✗ Nej
Foundry-ägare Gjuteri projekt ✔ Ja

Agenten har implicit åtkomst till kärnfunktioner i sitt eget projekt, till exempel modellinferens. Ingen explicit rolltilldelning krävs för standardfallet. Avancerade scenarier som kräver explicit åtkomst finns i Agentåtkomst utöver standardvärden.

Distribution av värdbaserad agent

Distributionsåtgärder för värdbaserad agent är kontrollplansåtgärder. Stegvis distributionsvägledning finns i Distribuera en värdbaserad agent.

Skicka en avbildning till registret

Användaren eller tjänstens huvudnamn som distribuerar agenten behöver behörighet att skicka avbildningen till ACR. Det finns två inbyggda roller som är lämpliga för den här uppgiften, som bör tilldelas i ACR-registrets resursomfång:

Skapa en ny agentversion

För att skapa en agent krävs behörigheten Microsoft.CognitiveServices/accounts/AIServices/agents/write i omfånget för Foundry-projektet.

Fördefinierad roll Scope Kan tilldelningsmottagaren skapa en agentversion?
Ägare Gjuteri projekt ✗ Nej
Deltagare Gjuteri projekt ✗ Nej
Foundry-användare Gjuteri projekt ✔ Ja
Foundry-projektledare Gjuteri projekt ✔ Ja
Foundry-kontoägare Gjuteri projekt ✗ Nej
Foundry-ägare Gjuteri projekt ✔ Ja

Om du använder agentprogram måste du också skapa ett agentDeployment objekt som refererar till en nyligen distribuerad agentversion. Det här är en hanteringsplanåtgärd. För att skapa ett agentDeployment-objekt krävs behörigheten Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments/write i agentprogrammets omfång.

Fördefinierad roll Scope Kan tilldelare skapa ett agentDeployment objekt?
Ägare Foundry-konto ✔ Ja
Deltagare Foundry-konto ✔ Ja
Foundry-användare Foundry-konto ✗ Nej
Foundry-projektledare Foundry-konto ✔ Ja
Foundry-kontoägare Foundry-konto ✔ Ja
Foundry-ägare Foundry-konto ✔ Ja

Uppdatera agenten så att den nya versionen används

Om du använder agentslutpunkten konfigureras versionsval för agentobjektet. För att agenten ska kunna använda den nya versionen krävs behörigheten Microsoft.CognitiveServices/accounts/AIServices/agents/write i foundry-projektets omfång.

Fördefinierad roll Scope Kan tilldelningsmottagaren uppdatera agentversionen?
Ägare Gjuteri projekt ✗ Nej
Deltagare Gjuteri projekt ✗ Nej
Foundry-användare Gjuteri projekt ✔ Ja
Foundry-projektledare Gjuteri projekt ✔ Ja
Foundry-kontoägare Gjuteri projekt ✗ Nej
Foundry-ägare Gjuteri projekt ✔ Ja

Om du i stället använder agentprogrammet konfigureras versionsval på agentprogramobjektet. Om du uppdaterar agentprogrammet för att använda det nya agentDeployment-objektet krävs behörigheten Microsoft.CognitiveServices/accounts/projects/applications/write i agentprogrammets omfång.

Fördefinierad roll Scope Kan tilldelningsmottagaren uppdatera agentprogrammet?
Ägare Foundry-konto ✔ Ja
Deltagare Foundry-konto ✔ Ja
Foundry-användare Foundry-konto ✗ Nej
Foundry-projektledare Foundry-konto ✔ Ja
Foundry-kontoägare Foundry-konto ✔ Ja
Foundry-ägare Foundry-konto ✔ Ja

Azure Bot Service konfiguration

Det är valfritt att publicera din agent till Microsoft Teams eller Microsoft 365 Copilot. När du gör det utför publiceringsflödet kontrollplansåtgärder för att skapa en Azure Bot Service resurs och konfigurera dess kanaler och uppdaterar sedan antingen agenten eller agentprogrammet för att tillåta begäranden från Bot Service.

Skapa robottjänsten

För att skapa robottjänstresursen krävs behörigheten Microsoft.BotService/botServices/write i resursgruppens omfång.

Fördefinierad roll Scope Kan tilldelad skapa en robottjänst?
Ägare Resursgrupp ✔ Ja
Deltagare Resursgrupp ✔ Ja
Foundry-användare Resursgrupp ✗ Nej
Foundry-projektledare Resursgrupp ✗ Nej
Foundry-kontoägare Resursgrupp ✗ Nej
Foundry-ägare Resursgrupp ✗ Nej

Note

Azure Bot Service är en separat resurstyp från Foundry. Azure ai-begränsade inbyggda roller omfattar inte Microsoft.BotService/* behörigheter.

Konfigurera kanaler

För att konfigurera kanalerna Teams och Microsoft 365 Extensions i robottjänsten krävs behörigheten Microsoft.BotService/botServices/channels/write i omfånget för robottjänstresursen.

Fördefinierad roll Scope Kan tilldelningsmottagare konfigurera kanaler?
Ägare Robottjänst ✔ Ja
Deltagare Robottjänst ✔ Ja
Foundry-användare Robottjänst ✗ Nej
Foundry-projektledare Robottjänst ✗ Nej
Foundry-kontoägare Robottjänst ✗ Nej
Foundry-ägare Robottjänst ✗ Nej

Uppdatera agenten eller agentprogrammet

Publiceringsflödet anger Kanaler (Azure Bot Service) som autentiseringsläge i agent- eller agentprogrammet. Det objekt som uppdateras beror på ditt scenario:

  • Scenario för agentprogram: Agentprogramobjektet uppdateras. Det här är en skrivåtgärd för kontrollplanet. Samma rollkrav gäller som i agentprogram.
  • Agentslutpunktsscenario: Agentobjektet uppdateras. Det här är en skrivåtgärd för dataplanet. Samma rollkrav gäller som beskrivs i Skapa en ny agentversion.

Stegvisa anvisningar om hur du publicerar till Teams eller M365 Copilot finns i Publicera agenter för att Microsoft 365 Copilot och Microsoft Teams.

Agentinteraktion

För att interagera med agenten krävs att den anropande användaren eller tjänstens huvudnamn har behörighet för ett dataplan:

  • För att interagera med en agentslutpunkt behöver Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action de i omfånget för Foundry-projektet eller i omfånget för den specifika agenten. Den här behörigheten omfattar alla körningsinteraktioner med agenten, inklusive men inte begränsat till API-anrop för svar.
  • För att interagera med ett agentprogram behöver de Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action i agentprogrammets omfång.

Tip

Foundry Agent Consumer är den inbyggda rollen med minst privilegier för användare och tjänstens huvudnamn som interagerar med agentslutpunkter. Använd den här rollen i stället för Foundry User när huvudnamnet inte behöver skapa eller ändra agenter.

Fördefinierad roll Scope Kan tilldelad interagera med agentslutpunkter? Kan tilldelad interagera med agentprogram?
Ägare Gjuteri projekt ✗ Nej ✗ Nej
Deltagare Gjuteri projekt ✗ Nej ✗ Nej
Foundry Agent-konsument Foundry-projekt eller agent ✔ Ja ✗ Nej
Foundry-användare Gjuteri projekt ✔ Ja ✔ Ja
Foundry-projektledare Gjuteri projekt ✔ Ja ✔ Ja
Foundry-kontoägare Gjuteri projekt ✗ Nej ✗ Nej
Foundry-ägare Gjuteri projekt ✔ Ja ✔ Ja

Du kan också tilldela roller i omfånget för en specifik agent i stället för hela projektet. Mer information finns i Rolltilldelningar med agentomfattning.

Delegera slutanvändaridentiteten

En mellannivåtjänst som autentiserar x-ms-user-identity sina egna slutanvändare kan begränsa en session till en specifik slutanvändare genom att skicka rubriken. Om du vill skicka rubriken måste den anropande identiteten innehålla följande behörighet för dataplanet på agenten:

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

Den här dataåtgärden ingår inte i någon inbyggd roll. Roller som tidigare beviljat den via dataåtgärden Microsoft.CognitiveServices/* – inklusive Foundry-användare och Foundry-ägare – gör inte längre det. Om du vill bevilja den skapar du en anpassad roll som innehåller dataåtgärden och tilldelar rollen till din mellannivåtjänsts identitet i omfånget för Foundry-projektet eller den specifika agenten.

Följande anpassade rolldefinition beviljar endast personifieringsdataåtgärden:

{
  "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>"
  ]
}

Skapa rollen och tilldela den sedan till mellannivåidentiteten:

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>

En uppringare som skickar x-ms-user-identity utan den här behörigheten får en 403. Information om hur du använder delegerad identitet finns i Isolera värdbaserade agentsessioner per användare.

Agentobservabilitet

Visa telemetridata

Åtkomst till agenttelemetridata kräver läsbehörigheter för Application Insights-resursen. Detta omfattar visning av spårningar, loggar och mått via Azure-portalen, Foundry-portalen, API:er och övervakningsverktyg.

Tilldela övervakningsläsare i Application Insights-resursomfånget. Behörigheterna */read i den här rollen har åtkomst till underliggande Log Analytics arbetsytedata utan att kräva en separat tilldelning med arbetsyteomfattning.

Om du behöver arbeta direkt mot Log Analytics arbetsyta tilldelar du även Log Analytics Reader i arbetsytans omfång. Om arbetsytetabellerna är skyddade tilldelar du även Privileged Monitoring Data Reader för att läsa de skyddade tabellerna.

Fördefinierad roll Scope Kan tilldela åtkomstagentens telemetridata?
Ägare Application Insights ✔ Ja
Deltagare Application Insights ✔ Ja
Foundry-användare Application Insights ✗ Nej (ser mått, men inte spårningar)
Foundry-projektledare Application Insights ✗ Nej
Foundry-kontoägare Application Insights ✗ Nej (ser mått, men inte spårningar)
Foundry-ägare Application Insights ✗ Nej
Övervakningsläsare Application Insights ✔ Ja
Log Analytics Läsare Log Analytics arbetsyta ✔ Ja (direkt från arbetsytan)
Dataläsare för privilegierad övervakning Log Analytics arbetsyta ✔ Ja (krävs för skyddade tabeller)

Kostnadsvisning i faktureringsvaluta

För att visa kostnader i faktureringsvalutan i Foundry-portalen krävs behörigheten Microsoft.Billing/billingProperty/read. Den här behörigheten kräver en prenumeration eller tilldelning med faktureringskontoomfattning. Resursgruppsomfånget omfattar inte den här behörigheten.

Den här behörigheten är avsedd för portalens visnings bekvämlighet och krävs inte för funktioner för värdbaserad agent. Du kan på ett säkert sätt utelämna den här behörigheten för de flesta användare.

Fördefinierad roll Scope Kan tilldelningsmottagare visa kostnader i faktureringsvaluta?
Ägare Prenumeration ✔ Ja
Deltagare Prenumeration ✔ Ja
Cost Management-läsare Prenumeration ✔ Ja
Foundry-användare Prenumeration ✗ Nej

Agentåtkomst utöver standardvärden

Som standard har en agent implicit åtkomst till kärnfunktioner i sitt eget projekt. Ingen explicit rolltilldelning eller ytterligare konfiguration krävs för standardfallet. Implicit åtkomst omfattar:

  • Modellinferens via projektslutpunkten
  • Läs- och skrivbehörighet för sessionslagring

Ytterligare behörigheter kan behövas när en agent använder anslutna verktyg som har åtkomst till externa resurser, refererar till data utanför sitt eget projekt eller fungerar på kontonivå.

Explicit åtkomst på projektnivå

Vissa avancerade scenarier kan kräva explicita rolltilldelningar för agentidentiteten i Foundry-projektet. Det här avsnittet beskriver behörighetsbehoven som om agenten inte hade sin implicita åtkomst till projektet.

I avsaknad av implicit åtkomst skulle agentidentiteten behöva följande behörigheter i omfånget för Foundry-projektet för att utföra modellinferens med projektslutpunkten:

  • Microsoft.CognitiveServices/accounts/AIServices/responses/*
  • Microsoft.CognitiveServices/accounts/AIServices/agents/storage/read (för anpassade definitioner använder du Microsoft.CognitiveServices/accounts/AIServices/agents/*/read)
  • Microsoft.CognitiveServices/accounts/AIServices/agents/storage/write (för anpassade definitioner använder du Microsoft.CognitiveServices/accounts/AIServices/agents/*/write)
Fördefinierad roll Scope Kan tilldelad agent utföra modellinferens?
Ägare Gjuteri projekt ✗ Nej
Deltagare Gjuteri projekt ✗ Nej
Foundry-användare Gjuteri projekt ✔ Ja
Foundry-projektledare Gjuteri projekt ✔ Ja
Foundry-kontoägare Gjuteri projekt ✗ Nej
Foundry-ägare Gjuteri projekt ✔ Ja

Tip

Foundry User är den inbyggda rollen med minst privilegier som kan utföra modellinferens med projektslutpunkten. Den innehåller dock en bredare uppsättning behörigheter än vad som är absolut nödvändigt för den här åtgärden. Om du vill sänka behörigheten för din agent kan du skapa en anpassad roll med endast Microsoft.CognitiveServices/accounts/AIServices/responses/*, Microsoft.CognitiveServices/accounts/AIServices/agents/*/read och Microsoft.CognitiveServices/accounts/AIServices/agents/*/write. Kom ihåg att standardfallet inte kräver någon rolltilldelning, så du behöver bara lägga till detta i avancerade scenarier.

För att skapa rolltilldelningen krävs behörigheten Microsoft.Authorization/roleAssignments/write i omfånget för Foundry-projektet.

Mer information om hur du tilldelar roller i Azure finns i Skapa Azure rolltilldelningar.

Fördefinierad roll Scope Kan tilldelad skapa en rolltilldelning?
Ägare Gjuteri projekt ✔ Ja
Deltagare Gjuteri projekt ✗ Nej
Foundry-användare Gjuteri projekt ✗ Nej
Foundry-projektledare Gjuteri projekt ✔ Ja för Foundry User roll1
Foundry-kontoägare Gjuteri projekt ✔ Ja för Foundry User roll1
Foundry-ägare Gjuteri projekt ✗ Nej
Rollbaserad Access Control administratör Gjuteri projekt ✔ Ja

1 Både Foundry Project Manager och Foundry Account Owner har en begränsning som de bara kan tilldela rollen Foundry User. Om du planerar att använda en anpassad rolldefinition för agenten för att komma åt project kan Foundry Project Manager och Foundry Account Owner inte tilldela den anpassade rollen.

Note

Eftersom rolltilldelningen behövs mot agentidentiteten kan den inte skapas förrän agenten har skapats. Därför behöver den användare eller det huvudnamn som skapar agenten också behörighet att skapa rolltilldelningar. Foundry Project Manager i project omfånget är den rekommenderade rolltilldelningen för agentskapare i det här scenariot, eftersom rollen innehåller både nödvändiga behörigheter för dataplanet och möjligheten att tilldela rollen Foundry User.

Åtkomst på kontonivå

När du använder Foundry SDK och projektslutpunkten för modellinferens anropar projektproxyinferensen till kontonivådistributionen med sin egen hanterade identitet. Men om agentkoden kringgår projektslutpunkten och anropar OpenAI-slutpunkten på kontonivå direkt (till exempel https://{account}.cognitiveservices.azure.com), behöver agentens identitet någon av följande roller i kontoomfånget:

Funktionerna på kontonivå är inte proxied av projektslutpunkten. Dessa funktioner omfattar Speech, Content Safety, Visuellt innehåll, Document Intelligence, Language och Translator. De kräver en rolltilldelning i kontoomfånget om agenten kommer åt dem direkt. För de här funktionerna tilldelar du någon av följande roller i kontoomfånget:

  • Cognitive Services-användare – omfattar funktioner för tal, vision, språk och andra icke-OpenAI-funktioner.
  • Foundry User – omfattar alla CognitiveServices-dataåtgärder, inklusive OpenAI och de funktioner som angavs tidigare, med ett enda beviljande.

Relaterat innehåll

Länkdefinitioner
  • Last updated on