Cómo inventariar y gobernar agentes de Copilot Studio con Power Platform Inventory API

Inventario, identidad y control para el gobierno de agentes de Copilot Studio

El inventario de agentes dejó de ser solamente una lista administrativa. La Power Platform Inventory API permite consultar de forma estructurada los agentes de Copilot Studio existentes en un tenant y transformar sus metadatos en una línea base de gobierno: propietarios, entornos, publicación, autenticación, identidad, conexiones, canales, capacidades y uso compartido.

Microsoft proporciona la API y el esquema oficial. Como implementación práctica, Mikko Koskinen publicó PPX – Agent Admin Tools for Power Platform, un proyecto comunitario en PowerShell cuya primera versión incluye un informe denominado Agent Governance Baseline. La herramienta no es un producto oficial de Microsoft y debe validarse antes de utilizarla como control corporativo.

¿Qué problema resuelve?

Cuando los agentes se distribuyen entre varios entornos, la revisión individual desde Power Platform Admin Center resulta útil para investigar un recurso, pero insuficiente para ejecutar controles repetibles. Las preguntas iniciales suelen ser las mismas:

¿Cuántos agentes existen y en qué entornos están?
¿Quién es responsable de cada uno?
¿Cuándo se publicaron por última vez?
¿Qué modelo de autenticación e identidad utilizan?
¿Qué conectores, canales, herramientas y fuentes de conocimiento tienen configurados?
¿Cuáles están compartidos ampliamente, en cuarentena o fuera de una solución administrada?

La propuesta de PPX convierte esos datos en un CSV normalizado, con una fila por agente y campos calculados para facilitar análisis de ciclo de vida y gobierno. El objetivo no es reemplazar PPAC, sino complementar su experiencia con un proceso que pueda repetirse y compararse.

La base oficial: Power Platform Inventory API

La Power Platform Inventory API ejecuta consultas estructuradas sobre Azure Resource Graph. El cuerpo de la solicitud no contiene una cadena KQL libre: utiliza cláusulas como where, project, extend, join y orderby, que el servicio traduce a Kusto Query Language.

POST https://api.powerplatform.com/resourcequery/resources/query?api-version=2024-10-01

La tabla principal es PowerPlatformResources. De acuerdo con el esquema oficial, contiene recursos como aplicaciones, flujos, agentes de Copilot Studio, conectores y entornos. Para los agentes, el tipo consultado es:

microsoft.copilotstudio/agents

Microsoft también documenta un inventario específico para agentes de Copilot Studio. Incluye agentes publicados y no publicados, aunque la estructura detallada refleja la versión publicada; los cambios suelen aparecer en aproximadamente 20 minutos.

Arquitectura de la implementación comunitaria

PowerShell y Az.Accounts
        ↓ autenticación delegada
Power Platform Inventory API
        ├── agentes de Copilot Studio
        └── entornos de Power Platform
        ↓ combinación por Environment ID
Normalización de datos
        ↓
CSV de gobierno + archivo de limitaciones

PPX consulta agentes y entornos por separado y realiza la combinación en PowerShell. Esta decisión evita depender de un join de servidor durante la paginación y permite enriquecer cada agente con el nombre, tipo, región y estado administrado de su entorno.

El informe propuesto contiene 43 columnas. Algunas provienen directamente de la API y otras son derivadas por el script. Entre los grupos de información disponibles se encuentran:

Identificación: nombre, identificador, entorno y región.
Ciclo de vida: creación, última publicación, antigüedad y cuarentena.
Responsabilidad: creador y propietario actual.
Identidad: modo de autenticación, Entra App ID, Entra Agent ID y Agent Blueprint ID cuando correspondan.
Construcción: superficie de creación, modelo, tipo de orquestación y pertenencia a solución administrada.
Capacidades: conectores, operaciones, canales, flujos, temas, herramientas, conocimiento y agentes conectados.
Uso compartido: usuarios, grupos y disponibilidad para todo el tenant.

Qué controles de negocio pueden derivarse

El valor aparece cuando el inventario se convierte en reglas verificables. Una primera línea base podría identificar:

Agentes sin propietario vigente o con responsabilidad poco clara.
Agentes de producción que nunca se publicaron o no se actualizan desde el período definido.
Recursos compartidos con todo el tenant que requieren revisión.
Agentes sin autenticación o con un modelo diferente al estándar aprobado.
Identidades heredadas que deban evaluarse para Microsoft Entra Agent ID.
Uso de conectores, operaciones o conocimiento que requieran revisión de seguridad y DLP.
Agentes en cuarentena o fuera de soluciones administradas.
Diferencias de gobierno entre entornos administrados y no administrados.

Para profundizar en la evolución de identidad, puede consultarse nuestra alerta técnica sobre la migración de agentes a Microsoft Entra Agent ID.

Prerrequisitos y ejecución inicial

La versión publicada del acelerador utiliza PowerShell 5.1 o PowerShell 7, el módulo Az.Accounts y autenticación delegada. Se requiere una identidad con un rol administrativo admitido por Power Platform Inventory y acceso previo a Power Platform Admin Center. Antes de automatizarlo conviene revisar la documentación oficial de autenticación de la API.

git clone https://github.com/MikkoKoskinen/ppx-agent-admin-tools.git
cd ppx-agent-admin-tools
Install-Module Az.Accounts -Scope CurrentUser
Copy-Item ppx.settings.example.psd1 ppx.settings.psd1

. ./tools/agent-governance-baseline/Get-PPXAgentGovernanceBaseline.ps1
Get-PPXAgentGovernanceBaseline

El archivo local de configuración permite indicar el tenant y parámetros como tamaño de página, cantidad máxima de páginas y ubicación del informe. Debe excluirse del control de versiones cuando contenga información particular del entorno.

Procedimiento recomendado para un piloto

Fijar la versión v0.1.0 o un commit previamente revisado.
Analizar los scripts, dependencias y permisos antes de ejecutarlos.
Utilizar inicialmente un tenant o conjunto de entornos controlado.
Ejecutar una sola página mediante el parámetro de límite disponible.
Comparar cantidad y muestra de agentes contra PPAC.
Ejecutar el inventario completo y conservar el archivo de limitaciones generado.
Conciliar propietarios, publicación, autenticación, identidad, conectores, cuarentena y uso compartido.
Definir criterios de aceptación para completitud, campos nulos y tiempos de actualización.
Proteger la exportación y establecer una retención acorde con su sensibilidad.
Solo después de la conciliación, evaluar una ejecución periódica y un tablero histórico.

Seguridad y tratamiento de datos

Aunque el acelerador es de solo lectura, el resultado contiene metadatos administrativos sensibles: identificadores de propietarios, identidades de agentes, conexiones, canales, capacidades y relaciones entre recursos. El CSV no debería distribuirse como un informe general ni almacenarse en ubicaciones abiertas.

También debe aplicarse mínimo privilegio. Una automatización desatendida mediante una aplicación registrada constituye una decisión diferente a la ejecución delegada y requiere revisar permisos, almacenamiento de secretos, rotación, registros y separación de funciones.

Limitaciones que deben quedar visibles

El proyecto es independiente y comunitario; Microsoft no proporciona soporte sobre el script.
Varios campos del inventario de agentes y conectores permanecen en preview.
Los agentes clásicos V1 no forman parte del inventario moderno.
Los cambios no publicados no aparecen en la estructura detallada hasta publicar el agente.
Algunas propiedades pueden ser nulas según el tipo y la configuración del agente.
Microsoft limita a 200 los recursos detallados de cada tipo por agente.
La API pagina los resultados y debe validarse cuidadosamente en tenants con más de 1.000 registros.
El autor documenta un comportamiento inesperado con skipToken en pruebas de alto volumen y utiliza desplazamiento mediante Skip; esta observación no debe tratarse como garantía oficial de Microsoft.
La versión actual todavía no calcula completamente cobertura DLP ni cantidad de conectores premium.
El CSV representa una fotografía puntual; para auditoría histórica se necesita conservar ejecuciones fechadas y controlar cambios de esquema.

Conclusión

La recomendación es probar el acelerador como una línea base de solo lectura y conciliar sus resultados con PPAC. La combinación de Inventory API, PowerShell y un formato tabular facilita iniciar gobierno a escala sin construir inmediatamente una aplicación administrativa. Sin embargo, la dependencia de campos preview, las particularidades de paginación y el carácter comunitario de PPX hacen necesario validar completitud antes de convertir el informe en un control formal.