Справочник по разрешениям размещенного агента

При работе с агентами hosted в Microsoft Foundry важно понимать различные разрешения. Существует несколько классов разрешений, участвующих в разработке размещенных агентов, охватывающих плоскость управления Azure Resource Manager и плоскость данных Foundry:

• Разрешения, предоставленные пользователям или субъектам, работающим с ресурсами Foundry
• Разрешения, предоставленные проекту Foundry
• Разрешения, предоставленные агенту

Эта статья является компаньоном для управления доступом на основе Role для управления доступом Microsoft Foundry, которая представляет концепции управления доступом на основе ролей (RBAC) и встроенные роли, доступные в Microsoft Foundry. Прежде чем продолжить, ознакомьтесь с этой статьей. В этой статье рассматриваются операции, связанные с разработкой и развертыванием размещенного агента, разрешениями, необходимыми для выполнения этих операций, и встроенными ролями, охватывающим эти разрешения.

Сведения о комплексных задачах развертывания и жизненного цикла см. в разделе "Развертывание размещенного агента " и "Управление жизненным циклом размещенного агента". Сведения о поведении конкретного удостоверения см. в разделе " Удостоверение агента".

Роли в этой статье

Azure AI Foundry разрешения охватывают два плоскости: плоскость управления Azure Resource Manager (ARM) и плоскость данных Foundry. Роли владельца и участника имеют широкие разрешения уровня управления ARM, но не включают разрешения плоскости данных. Операции плоскости данных, такие как создание агентов или взаимодействие с ними, требуют определенных ролей Azure AI Foundry, таких как Azure ИИ User, Azure Ai Project Manager или Azure ИИ владельца.

В этой статье приведены следующие встроенные роли. Дополнительные сведения об определениях пользовательских ролей см. в разделе Azure.

Быстрая диагностика по симптомам

Используйте эти ссылки, чтобы перейти непосредственно к разделам, которые устраняют распространенные проблемы с разрешениями:

• Не удается создать агент: см. статью "Создание агента"
• Агент не может получить доступ к моделям: см. статью "Создание агента" и "Необязательный доступ к учетной записи"
• Deployment завершается ошибкой: см. раздел Hosted agent deployment и Реестр контейнеров Azure setup
• Agent не может извлекать образы во время выполнения: см. статью Реестр контейнеров Azure setup
• Сбой взаимодействия с агентом: см. сведения о взаимодействии агента
• Назначение ролей завершается ошибкой: см. разделы и настройка подключений. См. разделы и настройка ролей.
• Can't publish agent to Teams или M365 Copilot: См. раздел Azure Служба Bot установки

Архитектура решения размещенного агента

Завершенная настройка размещенного агента включает несколько Azure ресурсов, назначений удостоверений и подключений, работающих вместе. На следующей схеме показаны ключевые компоненты и их связи:

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

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

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

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

На схеме выше показано, как ресурсы упорядочены иерархически и какие назначения ролей обеспечивают обмен данными между ними. В следующих разделах приведены подробные требования к конфигурации для каждого компонента.

Необходимые ресурсы Azure

Для каждого развертывания размещенного агента требуется правильно настроить эти Azure ресурсы:

• Учетная запись Foundry
  • Назначение ролей позволяет управляемому удостоверению проекта получить доступ к учетной записи для доступа к модели. Azure AI User является рекомендуемой встроенной ролью.
• Развертывание модели (в учетной записи)
• Проект Foundry (в учетной записи)
  • Проект имеет управляемое удостоверение. Проект также получает схему агента и удостоверение агента при создании первого агента.
  • Назначение ролей позволяет удостоверению агента размещенного агента получить доступ к проекту для доступа к модели. Azure AI User является рекомендуемой встроенной ролью.
  • Назначения ролей позволяют пользователям или субъектам клиента взаимодействовать с агентами в проекте во время выполнения. Azure AI User является рекомендуемой встроенной ролью.
• Размещенный агент (в проекте)
  • Агент автоматически получает схему агента и удостоверение агента.
• Версия агента (в объекте размещенного агента)
• An Реестр контейнеров Azure (ACR)
  • Назначение ролей позволяет управляемому удостоверению проекта извлекать образы из реестра. Средство чтения репозитория контейнеров — это рекомендуемая встроенная роль.
  • Назначение роли позволяет пользователю или субъекту-службе развертывать агент для отправки образов в реестр. Модуль записи репозитория контейнеров — это рекомендуемая встроенная роль.
• Компонент Application Insights
• рабочую область Log Analytics A (связанную с компонентом Application Insights)
  • Назначение ролей позволяет управляемому удостоверению проекта считывать данные телеметрии для оценки. Log Analytics средство чтения данных является рекомендуемой встроенной ролью.
• Несколько ресурсов подключения (в проекте):
  • Для Реестр контейнеров Azure создается подключение, которое проект использует для извлечения изображений.
  • Для Application Insights создается подключение, которое проект использует для передачи данных телеметрии для своих агентов. Это подключение по умолчанию не использует удостоверение.

Некоторые пользователи или субъекты должны иметь разрешение на создание этих ресурсов и управление ими. В этой статье предполагается конфигурация, в которой Azure ресурсы находятся в одной группе ресурсов и предоставляют доступ на запись через эту группу ресурсов. Этот подход к группе ресурсов является распространенной конфигурацией для многих команд, но ваша конкретная настройка может отличаться. Если у вас есть другая стратегия организации ресурсов, может потребоваться разделить разрешения на группы ресурсов, которые вы используете.

Этот список не включает сетевые ресурсы. Однако пользователю или субъекту-службе, который подготавливает ресурсы Azure, также может потребоваться разрешение на создание виртуальных сетей, подсетей и частных конечных точек для защиты ресурсов.

Agent applications

Если вы используете приложения агента, список также включает:

• Приложение агента (в проекте)
  • Приложение агента автоматически получает схему агента и удостоверение агента. Повторите все назначения ролей для удостоверения агента размещенного агента с помощью удостоверения агента.
• Развертывание агента (в приложении агента)

настройка ресурсов Azure

Настройка учетной записи Foundry

Для создания учетной записи Foundry требуется разрешение Microsoft.CognitiveServices/accounts/write в области группы ресурсов.

Управляемое удостоверение проекта должно получить доступ к учетной записи Foundry для выполнения вывода модели через конечную точку проекта. Доступ проекта охватывается ролью Azure AI User в области учетной записи Foundry. Это назначение роли может быть создано автоматически при создании проекта в зависимости от разрешений пользователя или субъекта-службы, создающего проект.

Дополнительные назначения ролей могут потребоваться, если код агента обращается к конечной точке OpenAI уровня учетной записи напрямую или другим возможностям уровня учетной записи, не зависимой от конечной точки проекта. Дополнительные сведения см. в разделе "Необязательный доступ к учетной записи".

Model deployment

Для создания развертывания модели требуется разрешение Microsoft.CognitiveServices/accounts/deployments/write в области учетной записи Foundry.

Project setup

Для создания проекта Foundry требуется разрешение Microsoft.CognitiveServices/accounts/projects/write в области учетной записи Foundry.

Если создатель проекта имеет возможность назначить роль Azure AI User в области учетной записи, система автоматически создает два назначения ролей:

• Создатель проекта предоставляет роль пользователя ИИ Azure в области учетной записи Foundry.
• Управляемое удостоверение проекта предоставляется роль Azure пользователя ИИ в области учетной записи Foundry.

Для удостоверения агента по проекту требуется аналогичное назначение ролей. Дополнительные сведения см. в разделе создания агента .

настройка Реестр контейнеров Azure

Для создания Реестр контейнеров Azure требуется разрешение Microsoft.ContainerRegistry/registries/write в области группы ресурсов.

Управляемое удостоверение проекта должно иметь разрешения на извлечение образа из ACR. Для этой задачи подходят две встроенные роли, которые должны быть назначены в области ресурсов реестра ACR:

• Читатель репозитория контейнеров (предпочтительный, так как он моделирует извлечение как действие данных)
• AcrPull

Для создания этого назначения роли требуется разрешение Microsoft.Authorization/roleAssignments/write в области реестра ACR.

Дополнительные сведения о назначении ролей в Azure см. в статье Create Azure назначения ролей.

¹ Эти роли имеют roleAssignments/write, но ограничены только назначением роли Azure AI User, которая не охватывает разрешения ACR.

Пользователю или субъекту-службе, который отправляет образы в реестр, также требуется назначение роли. Дополнительные сведения см. в разделе развертывания размещенного агента .

Настройка Application Insights и Log Analytics

Для создания ресурса Application Insights требуется разрешение Microsoft.Insights/components/write в области группы ресурсов.

Для создания рабочей области Log Analytics требуется разрешение Microsoft.OperationalInsights/workspaces/write в области группы ресурсов.

Если вы планируете использовать функцию оценки, управляемому удостоверению проекта требуются разрешения для чтения из рабочей области Log Analytics. Этот доступ можно включить, предоставив роль Log Analytics Data Reader управляемому удостоверению проекта в области рабочей области Log Analytics.

Для создания этого назначения роли требуется разрешение Microsoft.Authorization/roleAssignments/write в области рабочей области Log Analytics.

Дополнительные сведения о назначении ролей в Azure см. в статье Create Azure назначения ролей.

¹ Эти роли имеют roleAssignments/write, но ограничены только назначением роли Azure AI User, которая не охватывает разрешения Log Analytics.

Connections setup

Для создания подключения требуется разрешение Microsoft.CognitiveServices/accounts/projects/connections/write в области проекта Foundry.

Пользователю или субъекту-службе, создав подключения, также требуются сведения о подключении для компонента Application Insights и реестра контейнеров. Сведения о подключении могут быть предоставлены пользователем или субъектом-службой, создающим эти ресурсы, или доступом на чтение по этим ресурсам.

Agent applications

При использовании приложений агента необходимо создать приложение агента в проекте Foundry. Для создания приложения агента требуется разрешение Microsoft.CognitiveServices/accounts/projects/applications/write в области проекта Foundry.

agentDeployment Объекты также являются ресурсами ARM, но они создаются в рамках процесса развертывания размещенного агента. Дополнительные сведения см. в разделе "Развертывание размещенного агента".

Agent creation

Агенты создаются с помощью операции плоскости данных. Для создания агента требуется разрешение Microsoft.CognitiveServices/accounts/AIServices/agents/write в области проекта Foundry.

Так как удостоверение агента может быть доступно только после создания агента, некоторые назначения ролей не могут быть созданы до этого момента. Чтобы выполнить вывод модели с конечной точкой проекта, удостоверение агента требует следующих разрешений в области проекта Foundry:

• Microsoft.CognitiveServices/accounts/AIServices/responses/*
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/read (для пользовательских определений используйте Microsoft.CognitiveServices/accounts/AIServices/agents/*/read)
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/write (для пользовательских определений используйте Microsoft.CognitiveServices/accounts/AIServices/agents/*/write)

Для создания этого назначения роли требуется разрешение Microsoft.Authorization/roleAssignments/write в области проекта Foundry.

Дополнительные сведения о назначении ролей в Azure см. в статье Create Azure назначения ролей.

¹ оба Azure AI Project Manager и Azure AI Account Owner имеют ограничение, которое можно назначить только роль Azure AI User. Если вы планируете использовать пользовательское определение роли для агента для доступа к project, Azure AI Project Manager и Azure AI Account Owner не сможет назначить эту пользовательскую роль.

Необязательный доступ к учетной записи

При использовании пакета SDK Foundry и конечной точки проекта для вывода модели прокси-серверы проекта вызывают развертывание на уровне учетной записи с помощью собственного управляемого удостоверения. Однако если код агента проходит конечную точку проекта и вызывает конечную точку OpenAI на уровне учетной записи напрямую (например, https://{account}.cognitiveservices.azure.com), удостоверение агента должно иметь одну из следующих ролей в области учетной записи:

• Пользователь OpenAI в Cognitive Services — охватывает только действия с данными OpenAI.
• Azure пользователь ИИ — охватывает все действия с данными CognitiveServices в учетной записи.

Возможности уровня учетной записи не поддерживаются конечной точкой проекта. К этим возможностям относятся речь, безопасность содержимого, Компьютерное зрение, аналитика документов, язык и переводчик. Они требуют назначения ролей в области учетной записи, если агент обращается к ним напрямую. Для этих возможностей назначьте одну из следующих ролей в области учетной записи:

• Пользователь Cognitive Services — охватывает функции распознавания речи, визуального распознавания, языка и других возможностей, отличных от OpenAI.
• Azure ИИ User — охватывает все действия с данными CognitiveServices, включая OpenAI и возможности, перечисленные ранее, с одним грантом.

Развертывание размещенного агента

Операции развертывания размещенного агента — это операции уровня управления. Пошаговые инструкции по развертыванию см. в разделе "Развертывание размещенного агента".

Отправка образа в реестр

Пользователю или субъекту-службе, развертывающего агент, требуется разрешение на отправку образа в ACR. Для этой задачи подходят две встроенные роли, которые должны быть назначены в области ресурсов реестра ACR:

• Модуль записи репозитория контейнеров (предпочтительный, так как он моделирует отправку как действие данных)
• AcrPush

Создание новой версии агента

Для создания агента требуется разрешение Microsoft.CognitiveServices/accounts/AIServices/agents/write в области проекта Foundry.

При использовании приложений агента также необходимо создать agentDeployment объект, ссылающийся на только что развернутую версию агента. Это операция плоскости управления. Для создания объекта agentDeployment требуется разрешение Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments/write в области приложения агента.

Обновление агента для использования новой версии

Если вы используете конечную точку агента, выбор версии настраивается в объекте агента. Для обновления агента для использования новой версии требуется разрешение Microsoft.CognitiveServices/accounts/AIServices/agents/write в области проекта Foundry.

Если вместо этого используется приложение агента, выбор версии настраивается в объекте приложения агента. Для обновления приложения агента для использования нового объекта agentDeployment требуется разрешение Microsoft.CognitiveServices/accounts/projects/applications/write в области приложения агента.

настройка Azure Служба Bot

Публикация агента в Microsoft Teams или Microsoft 365 Copilot является необязательным. При выполнении поток публикации выполняет операции уровня управления для создания ресурса Azure Служба Bot и настройки его каналов, а затем обновляет агент или приложение агента, чтобы разрешить запросы из Служба Bot.

Создание службы бота

Для создания ресурса службы бота требуется разрешение Microsoft.BotService/botServices/write в области группы ресурсов.

Configuring channels

Для настройки каналов расширений Teams и Microsoft 365 в службе ботов требуется разрешение Microsoft.BotService/botServices/channels/write в области ресурса службы бота.

Обновление агента или приложения агента

Поток публикации задает каналы (Azure Служба Bot) в качестве режима проверки подлинности в агенте или приложении агента. Обновленный объект зависит от вашего сценария:

• Сценарий приложения агента: объект приложения агента обновляется. Это операция записи плоскости управления. Те же требования к роли применяются, как описано в приложениях агента.
• Сценарий конечной точки агента: объект агента обновляется. Это операция записи плоскости данных. Те же требования к роли применяются, как описано в статье "Создание новой версии агента".

Пошаговые инструкции по публикации в Teams или M365 Copilot см. в статье Publish agent to Microsoft 365 Copilot and Microsoft Teams.

Agent interaction

Для взаимодействия с агентом требуется разрешение вызывающего пользователя или субъекта-службы. Чтобы взаимодействовать с приложением agent, им потребуется Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action в области приложения агента.

Agent observability

Просмотр данных телеметрии

Для доступа к данным телеметрии агента требуются разрешения на чтение ресурса Application Insights. Это включает просмотр трассировок, журналов и метрик с помощью портала Azure, портала Foundry, API и средств мониторинга.

Назначьте средство чтения мониторинга в области ресурсов Application Insights. Разрешения */read в этой роли получают доступ к базовым данным рабочей области Log Analytics, не требуя отдельного назначения рабочей области.

Если вы хотите работать непосредственно с рабочей областью Log Analytics, назначьте Log Analytics Читатель в области рабочей области.

Отображение затрат в валюте выставления счетов

Для просмотра затрат на валюту выставления счетов на портале Foundry требуется разрешение Microsoft.Billing/billingProperty/read. Для этого разрешения требуется назначение подписки или выставления счетов на уровне учетной записи. Область группы ресурсов не охватывает это разрешение.

Это разрешение предназначено для удобства отображения портала и не требуется для функций размещенного агента. Вы можете безопасно опустить это разрешение для большинства пользователей.

Related content

• Размещенные агенты: узнайте об архитектуре и жизненном цикле размещенного агента.
• Role на основе управления доступом для Microsoft Foundry: просмотрите встроенные роли, области и шаблоны назначений.
• Удостоверение агента. Узнайте, как отличаются удостоверения агента и управляемое удостоверение проекта.