Referencia de permisos del agente hospedado

Al trabajar con agentes Hosted en Microsoft Foundry, es importante comprender los distintos permisos implicados. Hay varias clases de permisos implicados en el desarrollo del agente hospedado, que abarcan el plano de control de Azure Resource Manager y el plano de datos Foundry:

• Permisos concedidos a usuarios o entidades de seguridad que trabajan con recursos de Foundry
• Permisos concedidos al proyecto Foundry
• Permisos concedidos al agente

Este artículo es un complemento del control de acceso basado en Role para Microsoft Foundry, que presenta conceptos de control de acceso basado en rol (RBAC) y los roles integrados disponibles en Microsoft Foundry. Debe familiarizarse con ese artículo antes de continuar. En este artículo se tratan las operaciones implicadas en el desarrollo y la implementación del agente hospedado, los permisos necesarios para realizar esas operaciones y qué roles integrados cubren esos permisos.

Para ver las tareas de implementación y ciclo de vida de un extremo a otro, consulte Implementación de un agente hospedado y Administración del ciclo de vida del agente hospedado. Para conocer el comportamiento específico de la identidad, consulte Identidad del agente.

Roles de este artículo

Fundición de IA de Azure permisos abarcan dos planos: el plano de control de Azure Resource Manager (ARM) y el plano de datos Foundry. Los roles Propietario y Colaborador tienen permisos amplios del plano de control arm, pero no incluyen permisos de plano de datos. Las operaciones del plano de datos, como crear agentes o interactuar con ellos, requieren roles de Fundición de IA de Azure específicos como Foundry User, Foundry Project Manager o Foundry Owner.

En este artículo se hace referencia a los siguientes roles integrados. Para obtener información sobre las definiciones de roles personalizados, consulte Azure roles personalizados.

Diagnóstico rápido por síntoma

Use estos vínculos para saltar directamente a las secciones que abordan problemas comunes de permisos:

• No se puede crear el agente: consulte Creación del agente.
• El agente no puede acceder a los modelos: consulte Acceso del agente más allá de los valores predeterminados.
• error Deployment: consulte Implementación del agente hospedado y Azure Container Registry setup
• Agent no puede extraer imágenes en tiempo de ejecución: consulte Azure Container Registry setup
• Error en la interacción del agente: consulte Interacción del agente.
• Error en la asignación de roles: consulte Creación de esa asignación de roles que requiere secciones y configuración de conexiones.
• No publicar el agente en Teams ni en Microsoft 365 Copilot: consulte configuración de Azure Bot Service

Arquitectura de la solución del agente hospedado

Una configuración completada del agente hospedado implica varios recursos de Azure, asignaciones de identidad y conexiones que funcionan conjuntamente. En el diagrama siguiente se muestran los componentes clave y sus relaciones:

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)

En el diagrama anterior se muestra cómo se organizan los recursos jerárquicamente y qué asignaciones de roles permiten la comunicación entre ellos. En las secciones siguientes se proporcionan requisitos de configuración detallados para cada componente.

Recursos de Azure necesarios

Cada implementación del agente hospedado requiere que estos recursos Azure estén configurados correctamente:

• Una cuenta de Foundry
  • Una asignación de roles permite que la identidad administrada del proyecto acceda a la cuenta para el acceso al modelo. Foundry User es el rol integrado recomendado.
• Implementación de un modelo (en la cuenta)
• Un proyecto Foundry (en la cuenta)
  • El proyecto tiene una identidad administrada. El proyecto también obtiene un plano técnico del agente y una identidad del agente cuando se crea su primer agente.
  • Las asignaciones de roles permiten a los usuarios o entidades de seguridad cliente interactuar con agentes en el proyecto en tiempo de ejecución. Foundry User es el rol integrado recomendado.
  • Algunos escenarios avanzados pueden requerir asignaciones de roles explícitas para la identidad del agente en el proyecto. Para obtener más información, consulte Acceso explícito a nivel de proyecto.
• Un agente hospedado (en el proyecto)
  • El agente obtiene automáticamente un plano técnico del agente y una identidad del agente.
• Una versión del agente (en el objeto Agente hospedado)
• Un Azure Container Registry (ACR)
  • Una asignación de roles permite que la identidad administrada del proyecto extraiga imágenes del registro. Lector del repositorio de Container Registry es el rol integrado recomendado.
  • Una asignación de roles permite que un usuario o una entidad de servicio que implemente el agente para insertar imágenes en el registro. Container Registry Repository Writer es el rol integrado recomendado.
• Un componente de Application Insights
• A área de trabajo de Log Analytics (vinculada al componente de Application Insights)
  • Una asignación de roles permite que la identidad administrada del proyecto lea la telemetría de las evaluaciones. Log Analytics Lector de datos es el rol integrado recomendado.
• Varios recursos de conexión (en el proyecto):
  • Se crea una conexión para el Azure Container Registry, que usa el proyecto para la extracción de imágenes.
  • Se crea una conexión para Application Insights, que el proyecto usa para emitir telemetría para sus agentes. Esta conexión no usa la identidad de forma predeterminada.

Algunos conjuntos de usuarios o entidades de seguridad necesitan permiso para crear y administrar estos recursos. En este artículo se presupone una configuración en la que los recursos de Azure están todos dentro del mismo grupo de recursos y muestra la concesión de acceso de escritura a través de ese grupo de recursos. Este enfoque de grupo de recursos es una configuración común para muchos equipos, pero la configuración específica puede variar. Si tiene una estrategia de organización de recursos diferente, es posible que tenga que dividir los permisos entre los grupos de recursos que use.

Esta lista no incluye recursos de red. Sin embargo, el usuario o la entidad de servicio que aprovisiona los recursos de Azure también pueden necesitar permiso para crear y administrar redes virtuales, subredes y puntos de conexión privados para proteger los recursos.

Aplicaciones de agentes

Si usa aplicaciones de agente, la lista también incluye:

• Una aplicación de agente (en el proyecto)
  • La aplicación del agente obtiene automáticamente un plano técnico del agente y una identidad del agente. Si configura asignaciones de roles explícitas para la identidad del agente hospedado (por ejemplo, para escenarios avanzados), repita esas asignaciones para la identidad del agente de la aplicación del agente.
• Una implementación de agente (en la aplicación del agente)

configuración de recursos de Azure

Configuración de la cuenta de Foundry

La creación de una cuenta de Foundry requiere el permiso Microsoft.CognitiveServices/accounts/write en el ámbito del grupo de recursos.

La identidad administrada del proyecto necesita acceso a la cuenta de Foundry para realizar la inferencia del modelo a través del punto de conexión del proyecto. El acceso del proyecto está cubierto por el rol Foundry User en el ámbito de la cuenta de Foundry. Esta asignación de roles se puede crear automáticamente cuando se crea el proyecto, en función de los permisos del usuario o la entidad de servicio que cree el proyecto.

Es posible que se necesiten más asignaciones de roles si el código del agente accede directamente al punto de conexión de OpenAI de nivel de cuenta u otras funcionalidades de nivel de cuenta que el punto de conexión del proyecto no realiza el proxy. Para obtener más información, consulte Acceso de nivel de cuenta.

Implementación de modelos

La creación de una implementación de modelo requiere el permiso Microsoft.CognitiveServices/accounts/deployments/write en el ámbito de la cuenta de Foundry.

Configuración del proyecto

La creación de un proyecto foundry requiere el permiso Microsoft.CognitiveServices/accounts/projects/write en el ámbito de la cuenta de Foundry.

Si el creador del proyecto tiene la capacidad de asignar el rol Foundry User en el ámbito de la cuenta, el sistema crea automáticamente dos asignaciones de roles:

• Al creador del proyecto se le concede el rol Foundry User en el ámbito de la cuenta de Foundry.
• A la identidad administrada del proyecto se le concede el rol De usuario de Foundry en el ámbito de la cuenta de Foundry.

configuración de Azure Container Registry

La creación de un Azure Container Registry requiere el permiso Microsoft.ContainerRegistry/registries/write en el ámbito del grupo de recursos.

La identidad administrada del proyecto necesita permisos para extraer la imagen de ACR. Hay dos roles integrados adecuados para esta tarea, que se deben asignar en el ámbito de recursos del registro de ACR:

• Lector del repositorio de Container Registry (preferido porque modela la extracción como una acción de datos)
• AcrPull

La creación de esa asignación de roles requiere el permiso Microsoft.Authorization/roleAssignments/write en el ámbito del registro de ACR.

Para obtener más información sobre cómo asignar roles en Azure, consulte Crear asignaciones de roles Azure.

¹ Estos roles tienen roleAssignments/write, pero solo están restringidos para asignar el rol de Foundry User, que no cubre los permisos de ACR.

El usuario o la entidad de servicio que inserta imágenes en el registro también necesitan una asignación de roles. Para más información, consulte la sección Implementación del agente hospedado .

Configuración de Application Insights y Log Analytics

La creación de un recurso de Application Insights requiere el permiso Microsoft.Insights/components/write en el ámbito del grupo de recursos.

La creación de un área de trabajo de Log Analytics requiere el permiso Microsoft.OperationalInsights/workspaces/write en el ámbito del grupo de recursos.

Si tiene previsto usar la característica de evaluaciones, la identidad administrada del proyecto necesita permisos para leer desde el área de trabajo de Log Analytics. Para habilitar este acceso, conceda el rol Log Analytics Data Reader a la identidad administrada del proyecto en el ámbito del área de trabajo de Log Analytics.

La creación de esa asignación de roles requiere el permiso Microsoft.Authorization/roleAssignments/write en el ámbito del área de trabajo de Log Analytics.

Para obtener más información sobre cómo asignar roles en Azure, consulte Crear asignaciones de roles Azure.

¹ Estos roles tienen roleAssignments/write, pero solo están restringidos para asignar el rol Foundry User, que no cubre los permisos de Log Analytics.

Configuración de conexiones

La creación de una conexión requiere el permiso Microsoft.CognitiveServices/accounts/projects/connections/write en el ámbito del proyecto Foundry.

El usuario o la entidad de servicio que crean las conexiones también necesitan la información de conexión para el componente de Application Insights y el registro de contenedor. El usuario o la entidad de servicio pueden proporcionar los detalles de conexión que crearon esos recursos o tener acceso de lectura a esos recursos.

Aplicaciones de agentes

Si usa aplicaciones de agente, debe crear una aplicación de agente en el proyecto Foundry. La creación de una aplicación de agente requiere el permiso Microsoft.CognitiveServices/accounts/projects/applications/write en el ámbito del proyecto Foundry.

agentDeployment Los objetos también son recursos de ARM, pero se crean como parte del proceso de implementación del agente hospedado. Para más información, consulte Implementación del agente hospedado.

Creación de agentes

Los agentes se crean a través de una operación de plano de datos. La creación de un agente requiere el permiso Microsoft.CognitiveServices/accounts/AIServices/agents/write en el ámbito del proyecto Foundry.

El agente tiene acceso implícito a las funcionalidades principales dentro de su propio proyecto, como la inferencia de modelos. No se necesita ninguna asignación de roles explícita para el caso estándar. Para escenarios avanzados que requieren acceso explícito, consulte Acceso al agente más allá de los valores predeterminados.

Implementación del agente hospedado

Las operaciones de implementación del agente hospedado son operaciones del plano de control. Para obtener instrucciones paso a paso sobre la implementación, consulte Implementación de un agente hospedado.

Inserción de una imagen en el registro

El usuario o la entidad de servicio que implementa el agente necesita permiso para insertar la imagen en ACR. Hay dos roles integrados adecuados para esta tarea, que se deben asignar en el ámbito de recursos del registro de ACR:

• Escritor de repositorios de Container Registry (preferido porque modela la inserción como una acción de datos)
• AcrPush

Creación de una nueva versión del agente

La creación de un agente requiere el permiso Microsoft.CognitiveServices/accounts/AIServices/agents/write en el ámbito del proyecto Foundry.

Si usa aplicaciones de agente, también debe crear un agentDeployment objeto que haga referencia a una versión del agente recién implementada. Se trata de una operación del plano de administración. La creación de un objeto />

Actualización del agente para usar la nueva versión

Si usa el punto de conexión del agente, la selección de versión se configura en el objeto del agente. La actualización del agente para usar la nueva versión requiere el permiso Microsoft.CognitiveServices/accounts/AIServices/agents/write en el ámbito del proyecto Foundry.

Si en su lugar usa la aplicación del agente, la selección de versión se configura en el objeto de aplicación del agente. La actualización de la aplicación del agente para usar el nuevo objeto agentDeployment requiere el permiso Microsoft.CognitiveServices/accounts/projects/applications/write en el ámbito de la aplicación del agente.

configuración de Azure Bot Service

La publicación del agente en Microsoft Teams o Microsoft 365 Copilot es opcional. Al hacerlo, el flujo de publicación realiza operaciones del plano de control para crear un recurso de Azure Bot Service y configurar sus canales y, a continuación, actualiza el agente o la aplicación del agente para permitir solicitudes de Bot Service.

Creación del servicio de bots

La creación del recurso de bot service requiere el permiso Microsoft.BotService/botServices/write en el ámbito del grupo de recursos.

Configuración de canales

La configuración de los canales Teams y extensiones de Microsoft 365 en el servicio de bot requiere el permiso Microsoft.BotService/botServices/channels/write en el ámbito del recurso de bot service.

Actualización del agente o la aplicación del agente

El flujo de publicación establece Canales (Azure Bot Service) como modo de autenticación en el agente o la aplicación del agente. El objeto que se actualiza depende del escenario:

• Escenario de aplicación del agente: el objeto de aplicación del agente se actualiza. Se trata de una operación de escritura del plano de control. Se aplican los mismos requisitos de rol que se documentan en las aplicaciones del agente.
• Escenario de punto de conexión del agente: el objeto del agente se actualiza. Se trata de una operación de escritura del plano de datos. Se aplican los mismos requisitos de rol que se documentan en Creación de una nueva versión del agente.

Para obtener instrucciones paso a paso sobre la publicación en Teams o Copilot M365, consulte Publish agents to Microsoft 365 Copilot and Microsoft Teams.

Interacción del agente

La interacción con el agente requiere que el usuario o la entidad de servicio que llama tengan un permiso de plano de datos. Para interactuar con una aplicación agent, necesitan Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action en el ámbito de la aplicación del agente.

Observabilidad del agente

Visualización de datos de telemetría

El acceso a los datos de telemetría del agente requiere permisos de lectura en el recurso de Application Insights. Esto incluye la visualización de seguimientos, registros y métricas a través del portal de Azure, el portal foundry, las API y las herramientas de supervisión.

Asigne lector de supervisión en el ámbito del recurso de Application Insights. Los permisos */read de este rol acceden a los datos del área de trabajo de Log Analytics subyacentes sin necesidad de una asignación de ámbito de área de trabajo independiente.

Si necesita trabajar directamente en el área de trabajo de Log Analytics, asigne también Log Analytics Reader en el ámbito del área de trabajo. Si las tablas del área de trabajo están protegidas, asigne también lector de datos de supervisión con privilegios para leer las tablas protegidas.

Presentación de costos en moneda de facturación

La visualización de los costos en la moneda de facturación en el portal de Foundry requiere el permiso Microsoft.Billing/billingProperty/read. Este permiso requiere una asignación con ámbito de cuenta de facturación o suscripción. El ámbito del grupo de recursos no cubre este permiso.

Este permiso es para la comodidad de visualización del portal y no es necesario para la funcionalidad del agente hospedado. Puede omitir este permiso de forma segura para la mayoría de los usuarios.

Acceso del agente más allá de los valores predeterminados

De forma predeterminada, un agente tiene acceso implícito a las funcionalidades principales dentro de su propio proyecto. No se necesita ninguna asignación de roles explícita ni configuración adicional para el caso estándar. Cubre el acceso implícito:

• Inferencia de modelos a través del punto de conexión del proyecto
• Lectura y escritura del almacenamiento de sesión

Es posible que se necesiten permisos adicionales cuando un agente usa herramientas conectadas que acceden a recursos externos, hacen referencia a datos fuera de su propio proyecto o funcionan en el ámbito de nivel de cuenta.

Acceso explícito a nivel de proyecto

Algunos escenarios avanzados pueden requerir asignaciones de roles explícitas para la identidad del agente en el proyecto Foundry. En esta sección se describen las necesidades de permisos como si el agente no tuviera acceso implícito al proyecto.

En ausencia del acceso implícito, la identidad del agente necesitaría los siguientes permisos en el ámbito del proyecto Foundry para realizar la inferencia de modelos con el punto de conexión del proyecto:

• Microsoft.CognitiveServices/accounts/AIServices/responses/*
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/read (para definiciones personalizadas, use Microsoft.CognitiveServices/accounts/AIServices/agents/*/read)
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/write (para definiciones personalizadas, use Microsoft.CognitiveServices/accounts/AIServices/agents/*/write)

La creación de esa asignación de roles requiere el permiso Microsoft.Authorization/roleAssignments/write en el ámbito del proyecto Foundry.

Para obtener más información sobre cómo asignar roles en Azure, consulte Crear asignaciones de roles Azure.

¹ Ambos Foundry Project Manager y Foundry Account Owner tienen una restricción que solo pueden asignar el rol Foundry User. Si tiene previsto usar una definición de rol personalizada para que el agente acceda al project, Foundry Project Manager y Foundry Account Owner no podrá asignar ese rol personalizado.

Acceso de nivel de cuenta

Cuando se usa foundry SDK y el punto de conexión del proyecto para la inferencia del modelo, el proyecto realiza llamadas de inferencia a la implementación de nivel de cuenta mediante su propia identidad administrada. Sin embargo, si el código del agente omite el punto de conexión del proyecto y llama directamente al punto de conexión de OpenAI de nivel de cuenta (por ejemplo, https://{account}.cognitiveservices.azure.com), la identidad del agente necesita uno de los siguientes roles en el ámbito de la cuenta:

• Usuario de OpenAI de Cognitive Services : solo cubre las acciones de datos de OpenAI.
• Usuario de Foundry : cubre todas las acciones de datos de CognitiveServices en la cuenta.

El punto de conexión del proyecto no realiza el proxy de las funcionalidades de nivel de cuenta. Estas funcionalidades incluyen Speech, Content Safety, Computer Vision, Document Intelligence, Language y Translator. Requieren una asignación de roles en el ámbito de la cuenta si el agente los accede directamente. Para estas funcionalidades, asigne uno de los siguientes roles en el ámbito de la cuenta:

• Usuario de Cognitive Services : trata las funcionalidades voz, visión, lenguaje y otras funcionalidades que no son de OpenAI.
• Usuario de Foundry : cubre todas las acciones de datos de CognitiveServices, incluidas OpenAI y las funcionalidades enumeradas anteriormente, con una única concesión.

Contenido relacionado

• Agentes hospedados: obtenga información sobre la arquitectura y el ciclo de vida del agente hospedado.
• Control de acceso basado en Microsoft Foundry: Revise los roles, ámbitos y patrones de asignación integrados.
• Identidad del agente: comprenda cómo difieren la identidad del agente y la identidad administrada del proyecto.