La configuración guiada por IA para Agente de Microsoft Entra ID

La integración de Agente de Microsoft Entra ID implica varios pasos: creación de un modelo de identidad del agente, configuración de credenciales, configuración de URI e identificadores de ámbito, creación de principales de modelo y aprovechamiento de identidades del agente. Cada paso tiene sus propios requisitos previos, comprobaciones de validación y puntos de decisión.

Esta configuración guiada por IA automatiza todo este flujo de trabajo mediante un agente de codificación de IA (como GitHub Copilot en VS Code) para ejecutar los pasos en su nombre. En lugar de navegar entre varias páginas de documentación y ejecutar comandos manualmente, proporcionas al agente de IA un único archivo de instrucciones que te guía por el proceso de forma interactiva.

Beneficios

La configuración guiada por IA ofrece varias ventajas frente al flujo de trabajo manual:

• Punto de entrada único: un archivo de instrucciones reemplaza la necesidad de navegar entre varias páginas de documentación. El agente de IA sigue los pasos en orden y gestiona las transiciones automáticamente.
• Validación de requisitos previos automática: el agente de IA valida que tiene los roles de Microsoft Entra correctos, que está instalado el módulo beta de Microsoft Graph y que los permisos necesarios se configuran con el consentimiento del administrador antes de realizar llamadas API.
• Valores predeterminados inteligentes y detección automática: el agente de IA consulta el inquilino para obtener información de usuario y detalles de recursos existentes y, a continuación, usa esos valores como sugerencias al recopilar entradas de configuración.
• Convenciones de nombres derivadas: Proporcionas un único nombre visible para tu agente, y el agente de IA deriva todos los nombres de recursos relacionados (blueprint, principal del plano, identidades de agente, URI de identificadores) mediante patrones coherentes.
• Control de errores en línea: cuando se produce un error en un comando, el agente de IA analiza el error, sugiere una corrección y reintenta en lugar de requerir que busque en la documentación de solución de problemas. Este manejo de errores es especialmente útil para los problemas específicos del ID del agente, como los retrasos de propagación de permisos y los requisitos de encabezado de OData.
• Operaciones idempotentes: el agente de IA comprueba si los recursos ya existen antes de crearlos, lo que hace que sea seguro volver a ejecutar la configuración si se interrumpió un intento anterior.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene los siguientes requisitos previos.

Herramientas necesarias

• Visual Studio Code con las extensiones GitHub Copilot y GitHub Copilot Chat instalados. La configuración guiada por IA requiere un agente de codificación de IA con acceso a terminal.
• PowerShell 7 o posterior es necesario para el módulo de PowerShell de Microsoft Graph.
• SDK de PowerShell en Microsoft Graph (beta) instalado mediante Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force.

Cuentas y permisos requeridos

• Acceso a un inquilino de Microsoft Entra con uno de los siguientes roles:
  • Desarrollador de identificación de agentes para crear planos de identidad de agentes e identidades de agentes. Cualquier propietario de un plano técnico de identidad del agente puede crear una identidad de agente para ese plano técnico sin un rol de id. de agente.
  • Administrador de ID de Agente para obtener acceso administrativo completo a los recursos de ID de Agente.

• Roles adicionales para la concesión de permisos:
  • Privileged Role Administrator para conceder permisos de la aplicación de Microsoft Graph.
  • Cloud Application Administrator o Application Administrator para conceder permisos delegados Microsoft Graph.

Permisos de Microsoft Graph necesarios

El cliente que use (PowerShell o un registro de aplicaciones personalizado) debe estar autorizado con los siguientes permisos delegados:

Código de agente necesario (opcional)

Si ya tiene un proyecto de agente de trabajo (Python, Node.jso .NET) que necesita una identidad de id. de agente, haga que el directorio del proyecto esté disponible. Si aún no tiene una, puede completar la configuración del plano técnico de forma independiente.

Descarga el archivo de instrucciones de configuración

La configuración guiada por IA usa las instrucciones que se encuentran en el repositorio de Microsoft Skills GitHub.

Ejecuta la configuración guiada por IA

Siga estos pasos para iniciar la configuración asistida por IA.

Paso 1: Abrir el proyecto en VS Code

Abra el directorio del proyecto del agente (o cualquier directorio de trabajo) en Visual Studio Code.

Paso 2: Abrir gitHub Copilot Chat en modo de agente

Abra el panel Copilot Chat de GitHub y cambie a modo Agent. El modo de agente ofrece GitHub Copilot la capacidad de ejecutar comandos de terminal, leer archivos e interactuar con su entorno, que requiere la configuración guiada por IA.

Paso 3: Adjunta el archivo de instrucciones y comienza

En la entrada de Copilot Chat, adjunte el archivo agent-id-setup-instructions.md y envíelo con una sugerencia corta. Por ejemplo:

Follow the steps in #file:agent-id-setup-instructions.md

El agente de IA lee el archivo de instrucciones y comienza la configuración guiada. Crea una lista de tareas y funciona mediante los pasos secuencialmente:

1. Validar requisitos previos: verifica los roles de Microsoft Entra y comprueba que están instalados PowerShell 7+ y el módulo beta de Microsoft Graph.
2. Authorize and connect: se conecta a Microsoft Graph con los ámbitos necesarios y establece el perfil en beta.
3. Crear el plano de identidad del agente: recopila un nombre para mostrar, identifica al patrocinador (usted), crea el plano con los encabezados necesarios @odata.type y OData-Version, y registra el appId.
4. Configurar credenciales: agrega una identidad administrada (para producción) o un certificado o secreto de cliente (para desarrollo o pruebas locales) al plano técnico.
5. Configurar el URI y el ámbito del identificador: establece identifierUris en api://{appId} y crea un ámbito de permisos OAuth2 para la comunicación de agente a agente y de usuario a agente.
6. Crear el principal del plano: crea el principal de servicio para el plano (el principal no se crea automáticamente y se debe realizar explícitamente).
7. Crear identidades de agente: crea una o varias entidades principales de servicio de identidad del agente en el esquema.

Paso 4: Responder a las preguntas

El agente de IA se detiene en puntos específicos para recoger tu información:

• Nombre para mostrar: el nombre para mostrar de la plantilla de identidad del agente (ej., "Agente de presupuesto de Contoso").
• Patrocinador: el usuario o grupo responsable del agente. El valor predeterminado es el usuario que ha iniciado sesión actualmente.
• Propietario: el usuario o la entidad de servicio que puede realizar cambios técnicos en el plano. Opcional, pero recomendado.
• Tipo de credencial: indica si se debe usar una identidad administrada (recomendada para producción) o un certificado o un secreto de cliente (para el desarrollo local).
• Recuento de identidades del agente: número de identidades de agente a crear según este plan.
• Confirmación del valor derivado: revise los nombres y los URI generados automáticamente antes de crear los recursos.

Paso 5: Comprobar en el Centro de administración Microsoft Entra

Una vez completada la configuración, el agente de IA proporciona instrucciones sobre cómo comprobar los recursos:

1. Inicie sesión en el Centro de administración Microsoft Entra como al menos un desarrollador de ID de agente.
2. Navegue a Entra ID>Agents>Identidades de agentes para ver su nuevo modelo de identidad del agente y las identidades de agente creadas bajo él.
3. Compruebe que el plano técnico tiene configuradas las credenciales, el URI de identificador y el ámbito correctos.

Lo que cubre la configuración guiada por IA

La configuración guiada por IA automatiza las siguientes fases de la integración del identificador del agente:

Problemas comunes que maneja la configuración guiada por IA

Las API de ID de agente tienen varios requisitos que la configuración guiada por IA detecta y resuelve automáticamente, pero no son requisitos obvios. Comprender estos problemas puede resultar útil si necesita depurar problemas o ampliar la configuración.

Se requiere el encabezado OData-Version

Todas las llamadas API de ID del agente que usan @odata.type requieren el encabezado OData-Version: 4.0. Si omite este encabezado, el @odata.type campo se omite silenciosamente, lo que hace que la API cree una aplicación estándar en lugar de un plano técnico de identidad del agente. La configuración guiada por IA siempre incluye este encabezado.

El principal de blueprint no se crea automáticamente

La creación de un plano técnico de identidad del agente (POST /applications) no crea automáticamente su entidad de plano técnico (entidad de servicio). Sin el principal del plano, la creación subsiguiente de identidades de agentes falla con:

400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

La configuración guiada por IA siempre crea el plano principal inmediatamente después del plano. También controla el caso idempotente. Si una ejecución anterior generó el plano técnico pero se bloqueó antes de crear la entidad principal, el instalador detecta este evento y crea la entidad principal que falta.

Se requieren patrocinadores

Los patrocinadores son necesarios y pueden ser usuarios, grupos con pertenencia dinámica o grupos unificados. Tanto el plano técnico como la creación de identidades del agente requieren un sponsors@odata.bind campo. Sin ella, recibes:

400: No sponsor specified. Please provide at least one sponsor.

La configuración guiada por IA solo acepta objetos user para la asignación de patrocinador y usa el formato de dirección /users/{objectId} URL (no /directoryObjects/ o /servicePrincipals/). La configuración resuelve el identificador de objeto del usuario actual y lo usa como patrocinador predeterminado. Para asignar un grupo soportado como patrocinador de una plantilla, use Microsoft Graph API directamente.

La propagación de permisos tarda entre 30 y más de 120 segundos

Después de conceder el consentimiento del administrador para los permisos de ID de agente, los permisos recién concedidos no aparecen inmediatamente en los tokens. El punto de conexión del token sirve notificaciones almacenadas en caché y la propagación puede tardar entre 30 y 120 segundos o más.

La configuración guiada por IA gestiona los cambios recientes en los permisos mediante el reintento de operaciones con retroceso exponencial cuando se recibe un 403. Si va a crear estos scripts manualmente, implemente la lógica de reintento:

# Example: Retry with backoff after admin consent
$maxRetries = 5
for ($i = 0; $i -lt $maxRetries; $i++) {
    try {
        # Attempt the operation
        $result = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 403 -and $i -lt $maxRetries - 1) {
            $wait = 20 * ($i + 1)
            Write-Host "Permission not yet propagated. Retrying in $wait seconds..."
            Start-Sleep -Seconds $wait
            # Disconnect and reconnect to force a fresh token
            Disconnect-MgGraph
            Connect-MgGraph -Scopes $scopes
        } else {
            throw
        }
    }
}

Las identidades del agente no pueden tener credenciales de contraseña

Las identidades del agente son entidades de servicio sin respaldo de objetos de aplicación. Si se intenta agregar un passwordCredential elemento directamente a una identidad del agente, se produce lo siguiente:

PropertyNotCompatibleWithAgentIdentity

Las credenciales deben configurarse en el plano técnico, no en identidades de agente individuales. Utilice la federación de identidad administrada (recomendada) o agregue secretos o certificados al blueprint, y las identidades de agente heredan la credencial a través de la impersonación.

El identificador URI debe establecerse explícitamente

El campo del plano básico identifierUris no se establece de forma predeterminada. Sin él, el ámbito api://{appId}/.default de OAuth2 no se resolverá y se producirá un error en la adquisición de tokens para el agente. La configuración guiada por IA siempre configura este valor como parte del paso de configuración del ámbito.

Ruta de acceso de credenciales de identidad federada para planos técnicos

Al agregar credenciales de identidad federada (FIC) para la federación de identidad administrada, debe usar la ruta de acceso de API específica del agente:

POST /applications/{blueprint-obj-id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials

El uso de la /applications/{id}/federatedIdentityCredentials ruta de acceso puede funcionar para los planos técnicos de identidad del agente, pero no se admite y no se recomienda.

El emisor de tokens varía según la versión del punto de conexión.

Al validar tokens en el back-end del agente, tenga en cuenta las siguientes variaciones:

• Los tokens de la versión 1.0 usan el emisor https://sts.windows.net/{tenant-id}/
• Los tokens v2.0 usan el emisor https://login.microsoftonline.com/{tenant-id}/v2.0

Acepte ambos formatos en la lógica de validación de tokens.

Solución de problemas

El agente de IA no ejecuta comandos de terminal

Si el agente de IA describe los comandos, pero no los ejecuta, asegúrese de que usa ModoAgent en GitHub Copilot Chat. Los modos Preguntar y Editar no tienen acceso al terminal.

El agente de IA salta los pasos de validación

El archivo de instrucciones impone un orden estricto de pasos. Si el agente de IA parece saltarse un paso, recuérdale que siga las instrucciones desde el principio. Por ejemplo:

Please start from Step 1 in the setup instructions and work through each step in order.

Se produce un error en los comandos de Graph con 403-Forbidden

Las causas más comunes de errores 403:

• Retraso de propagación de permisos: espere entre 1 y 2 minutos después del consentimiento del administrador y vuelva a intentarlo.
• Falta el consentimiento del administrador: Verifique que los permisos necesarios tienen el consentimiento del administrador concedido en el centro de administración de Microsoft Entra en Registros de aplicaciones> su aplicación cliente >Permisos de API.

La creación del plano técnico se realiza correctamente, pero devuelve una aplicación estándar.

Este resultado se produce cuando falta el OData-Version: 4.0 encabezado o se omite la @odata.type propiedad . Compruebe que ambos están presentes en la solicitud. Si usa cmdlets de PowerShell, asegúrese de que esté usando el módulo beta y de pasar la estructura de datos correcta.

Se produce un error en la creación de la identidad del agente con "Blueprint Principal no existe".

La plantilla principal debe crearse como un paso independiente después de la plantilla. ¡Corre!

POST https://graph.microsoft.com/beta/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

{
  "appId": "<your-blueprint-app-id>"
}

Errores de directiva de vigencia de credenciales

Es posible que el arrendatario tenga políticas del ciclo de vida de las credenciales que restrinjan la duración máxima de los secretos de cliente. Si recibe un error sobre la duración de las credenciales al agregar una contraseña, reduzca el valor endDateTime para alinearlo con la directiva de su organización.

Los valores de configuración deben cambiar

Si necesita cambiar los valores de configuración después de la instalación, puede hacer lo siguiente:

• Vuelva a ejecutar la configuración guiada por IA con valores actualizados. Las comprobaciones idempotentes omiten los recursos que ya existen correctamente.
• Utilice Microsoft Graph PowerShell con solicitudes de PATCH para actualizar propiedades específicas.

Pasos siguientes

• Creación y eliminación de identidades de agente
• Relaciones administrativas en el identificador del agente (propietarios, patrocinadores y administradores)
• Identidades de agente, entidades de servicio y aplicaciones
• Conceptos del plano técnico de identidad del agente