Migrar agentes de Copilot Studio a Agente de Microsoft Entra ID

Este artículo describe cómo migrar opcionalmente los agentes existentes de Copilot Studio desde la identidad de registro de la aplicación heredada a un Agente de Microsoft Entra ID antes de la migración automática.

Utiliza la recomendación en el centro de administración de Power Platform para identificar agentes elegibles, planificar lotes de migración y migrar uno o más agentes. Esta experiencia basada en Advisor es el método recomendado de migración manual. También puedes usar los endpoints de la API de Power Platform para crear tu propio proceso de migración.

Cuando migras un agente a Agente de Microsoft Entra ID, obtienes:

• Una identidad de agente de primera clase que los administradores pueden ver y gobernar en Microsoft Entra.
• Acceso condicional y otras políticas de acceso diseñadas para cargas de trabajo agenticas y asignadas a agentes en lugar de heredadas de los registros de aplicaciones.
• Un modelo de identidad coherente en todos los servicios que trabajan con tus agentes.

Infózcate más sobre identidades de agentes y autenticación para Copilot Studio.

Acerca de la migración de identidad del agente

La migración convierte in situ la identidad de registro de aplicación existente del agente. El agente mantiene su ID de aplicación (cliente), por lo que las configuraciones posteriores que usan ese ID, como registros de canal y conectores, continúan resolviéndose al mismo identificador. El agente también obtiene un Agente de Microsoft Entra ID que los administradores pueden gestionar.

La migración es una operación controlada y voluntaria. Ustedes pueden:

• Migra un agente.
• Selecciona varios agentes y mígralos en lote.
• Migra lotes adicionales a tu propio ritmo.
• Restaurar un agente a su identidad anterior si no supera la validación.

Prerequisites

• Debes ser Administrador de Power Platform, Administrador de Dynamics 365 o Administrador Global.
• El inventario de Power Platform debe estar habilitado para tu inquilino para que Advisor pueda identificar a los agentes elegibles.
• Coordina una ventana de validación con los creadores que poseen los agentes que planeas migrar.

Planifica tus lotes de migración

La migración de identidades de agentes afecta a los agentes activos y puede interrumpir la autenticación, los conectores y las integraciones si no planificas bien la migración. Utiliza el siguiente enfoque por etapas:

1. Empieza con un piloto: selecciona un pequeño conjunto de agentes no críticos que represente los canales, modos de autenticación, conectores, flujos e integraciones que necesitas validar.
2. Coordina con los fabricantes: Notifique a los fabricantes afectados y acuerde una ventana de validación. Los creadores deberían estar disponibles para probar sus agentes cuando finalice un lote de migración.
3. Migrar de forma incremental: migrar agentes individualmente o en pequeños lotes. No migres toda la finca de una vez.
4. Validar de principio a fin: Confirma que cada agente migrado funciona a través de sus canales configurados, acciones, conectores, flujos de autenticación e integraciones.
5. Monitoriza y amplía: Revisa los registros de inicio de sesión de Microsoft Entra, incluidos los resultados de Acceso Condicional, antes de migrar un lote mayor.

Migrar agentes en el centro de administración de Power Platform

Utiliza la recomendación del Advisor en el centro de administración de Power Platform para revisar los agentes elegibles y migrar uno o más agentes.

1. Inicie sesión en el Centro de administración de Power Platform.

2. En el panel de navegación izquierdo, selecciona Acciones.

3. En Acciones, selecciona Recomendaciones.

4. En la pestaña de Recomendaciones , selecciona Activo.

5. Busca y selecciona Migrar agentes de Copilot Studio a Agente de Microsoft Entra ID para mejorar la gobernanza de agentes.

   

6. En el panel de recomendaciones, amplía ¿Por qué es esto importante? y revisa la guía de migración.

7. Revisa los agentes elegibles. Utiliza el orden de migración sugerido y las notas de migración para elegir un piloto inicial o el siguiente lote de migración. La tabla también proporciona información como entorno, tipo de entorno, propietario, actividad reciente y método de autenticación.

8. Selecciona la casilla junto a cada agente que quieras migrar. Puedes seleccionar un agente o varios agentes elegibles.

   El botón de Migrar queda disponible y la barra de acciones muestra el número de agentes seleccionados.

   

9. Selecciona Migrar, revisa la confirmación y confirma la migración.

10. Revise las columnas de Acción, estado de la acción y fecha de acción de cada agente seleccionado. Para revisar acciones entre las recomendaciones, seleccione la pestaña historial de acciones .

Repite estos pasos para cada lote planificado solo después de que el lote anterior haya pasado la validación.

Validar agentes migrados

Antes de migrar otro lote, coordina con los creadores de los agentes y confirma que cada agente migrado:

• Responde correctamente en todos los canales donde está publicado.
• Ejecuta sus acciones, conectores, flujos e integraciones con éxito.
• Se autentica como se espera, incluyendo autenticación personalizada.
• Funciona como se espera con las políticas de acceso a agentes y políticas de acceso condicional aplicables.

Revisa los registros de inicio de sesión de los agentes migrados en el centro de administración de Centro de administración Microsoft Entra. Confirma la autenticación exitosa e investiga fallos o resultados inesperados de Acceso Condicional.

Si un agente no pasa la validación, detén el despliegue por lotes y revierte ese agente antes de continuar.

Opcional: operaciones de API para migración de ID de agente

Si prefieres desarrollar tu propia automatización, puedes invocar los puntos de conexión de la API de Power Platform para migrar o revertir (rollback) agentes. Ambas operaciones son solicitudes HTTP POST autorizadas con un token portador para el servicio Power Platform.

Más información en:

• API y los SDK de Power Platform: del enfoque en la experiencia de usuario al enfoque en la API (Blog) (Blog para desarrolladores de Power Platform)
• Información general sobre la programación y la extensibilidad (documentación de Power Platform)
• Empieza con la API de Power Platform (documentación de Power Platform)
• Documentación de referencia de la API de operaciones de Copilot Studio

Obtenga un token portador OAuth2 para la API de Power Platform

Todas las operaciones aquí listadas requieren un token portador OAuth2 para https://api.powerplatform.com. Incluye este token en tu solicitud bajo un Authorization encabezado. El token debe provenir de Microsoft Entra ID OAuth2 y estar asociado a una cuenta de usuario que tenga uno de los roles de administrador listados en los requisitos previos.

Por ejemplo, usa el módulo de PowerShell de Az para obtener el token y almacenarlo como $token para su uso en solicitudes de API:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

Migrar la identidad del agente a Agente de Microsoft Entra ID

Migra un agente del ID de registro de la app al ID del Agente de Entra ID enviando una solicitud POST al endpoint de migración con los datos del agente:

• Punto de conexión:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Autenticación: Incluye un token portador OAuth válido para la API de Power Platform en la Authorization cabecera. La API de Power Platform requiere un token portador de Microsoft Entra ID.
• Cuerpo: No es necesario
• Propósito: Migrar un agente del ID de registro de la app al ID de Agente de Entra ID
• Respuesta: Devuelve un AgentIdentityMigrationResult objeto JSON con un status valor para la migración del ID del agente:
  • Migrated
  • AlreadyMigrated

Por ejemplo, el siguiente script recibe un token de autorización y luego llama al endpoint de migración para un agente específico (<BotId>) en un entorno específico (<EnvironmentId>) con esa autorización:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

$environmentId = "<EnvironmentId>"
$botId = "<BotId>"

$uri = "https://api.powerplatform.com/copilotstudio/environments/$environmentId/bots/$botId/api/agentidentitymigration/migrate?api-version=2024-10-01"
Invoke-RestMethod `
    -Method Post `
    -Uri $uri `
    -Headers @{
        Authorization = "Bearer $token"
    }

La siguiente respuesta de ejemplo muestra una migración exitosa:

{
  "status": "Migrated",
  "cdsBotId": "<bot-id>",
  "environmentId": "<environment-id>",
  "tenantId": "<tenant-id>",
  "agentIdentityId": "<agent-identity-id>",
  "applicationId": "<application-client-id>",
  "servicePrincipalObjectId": "<service-principal-object-id>",
  "managedIdentityId": "<managed-identity-id>",
  "completedAtUtc": "2026-08-21T12:00:00Z"
}

Revertir o restablecer la identidad del agente al identificador de registro de la aplicación

Para revertir a un agente, envía una solicitud POST al endpoint de revertir con los datos del agente:

• Punto de conexión:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Autenticación: Incluye un token portador OAuth válido para la API de Power Platform en la Authorization cabecera. La API de Power Platform requiere un token portador de Microsoft Entra ID.
• Cuerpo: No es necesario
• Propósito: Restablecer (revertir) el ID de un agente de un identificador de Entra ID a un identificador de registro de aplicaciones
• Respuesta: Devuelve un AgentIdentityRollbackResult objeto JSON con un valor de estado terminal para la migración del ID del agente:
  • NotMigrated
  • RolledBack

Por ejemplo, el siguiente script recibe un token y luego llama al endpoint de revert para un agente específico (<BotId>) en un entorno específico (<EnvironmentId>) con esa autorización:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

$environmentId = "<EnvironmentId>"
$botId = "<BotId>"

$uri = "https://api.powerplatform.com/copilotstudio/environments/$environmentId/bots/$botId/api/agentidentitymigration/rollback?api-version=2024-10-01"
Invoke-RestMethod `
    -Method Post `
    -Uri $uri `
    -Headers @{
        Authorization = "Bearer $token"
    }

El siguiente ejemplo de respuesta muestra una reversión exitosa:

{
  "status": "RolledBack",
  "cdsBotId": "<bot-id>",
  "environmentId": "<environment-id>",
  "tenantId": "<tenant-id>",
  "completedAtUtc": "2026-08-21T12:05:00Z"
}

Troubleshooting

La siguiente tabla enumera los problemas comunes y cómo resolverlos:

Contenido relacionado

• Consultas de ejemplo para el inventario de Power Platform
• Inventario de agentes de Copilot Studio