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

La incorporación a Agente de Microsoft Entra ID implica varios pasos: crear un modelo de identidad del agente, configurar las credenciales, configurar los URI y ámbitos del identificador, crear entidades de seguridad del modelo y aprovisionar identidades de 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. Este archivo de instrucciones está disponible como aptitud y se puede acceder a él de varias maneras.

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 se instalan las herramientas necesarias y los módulos de 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. Esta administración de errores resulta especialmente valiosa para los problemas específicos de Agent ID, como los retrasos en la propagación de permisos y los requisitos de los encabezados 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

La configuración guiada por IA requiere un agente de codificación de IA con acceso terminal:

• Visual Studio Code con las extensiones GitHub Copilot y GitHub Copilot Chat instalados.
• La extensión GitHub Copilot para Azure, que proporciona la funcionalidad Agente de Microsoft Entra ID directamente en VS Code.

La habilidad admite dos vías de aprovisionamiento. Instale uno o ambos en función de sus preferencias:

• Ruta de acceso de PowerShell: PowerShell 7 o posterior con el SDK de PowerShell en Microsoft Graph. Realice la instalación mediante Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force.
• Ruta de Python: Python 3.8 o posterior con azure-identity y requests. Realice la instalación mediante pip install azure-identity requests.

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 modelo de identidad de agente puede crear una identidad de agente para ese modelo sin una función de Agent ID.
  • 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 del 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.

Comienza

La configuración guiada por IA usa una aptitud, que es un único archivo de instrucciones que contiene todos los pasos y comprobaciones de validación. Puede acceder a la aptitud de una de estas dos maneras:

• A través de la extensión GitHub Copilot para Azure (recomendada): Instale la extensión de GitHub Copilot para Azure de VS Code. La aptitud Agente de Microsoft Entra ID se activa automáticamente al preguntar sobre la configuración del identificador del agente en Copilot Chat.
• Directamente desde GitHub: use la habilidad independiente Agente de Microsoft Entra ID haciendo referencia a ella en la indicación de Copilot Chat.

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: Iniciar la configuración guiada

Si tiene instalada la extensión GitHub Copilot para Azure, pídale a Copilot que configure Agent ID. Por ejemplo:

@azure Use the Agent ID Skill to set up an agent identity blueprint and create agent identities for my project using Microsoft Entra Agent ID.

Si no tiene la extensión, haga referencia a la aptitud directamente desde GitHub:

Follow the steps in https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugin/skills/entra-agent-id/SKILL.md

El agente de inteligencia artificial lee la habilidad y comienza la configuración guiada. Sigue los pasos secuencialmente:

1. Validar los requisitos previos: comprueba los roles de Microsoft Entra y valida que las herramientas necesarias (PowerShell con el módulo Microsoft Graph, o Python con azure-identity) estén instaladas.
2. Autenticar: se conecta a Microsoft Graph con los permisos necesarios. Para PowerShell, la aptitud usa Connect-MgGraph con ámbitos delegados explícitos. Para Python, usa un registro de aplicación dedicado con credenciales de cliente.
3. Crear el plano de identidad del agente: recopila un nombre para mostrar, identifica al patrocinador (usted), crea el plano mediante el endpoint tipado (/applications/microsoft.graph.agentIdentityBlueprint) y registra el appId.
4. Configurar credenciales: agrega una credencial de identidad federada con identidad administrada (para producción) o un secreto de cliente (para desarrollo o pruebas locales) al plano técnico.
5. Configurar el URI del identificador y el ámbito: establece identifierUris en api://{appId} y crea un ámbito de permisos de OAuth 2.0 para la comunicación de agente a agente y de usuario a agente.
6. Crear la identidad del plano técnico: crea la entidad de servicio para el plano técnico mediante el punto de conexión tipado (la identidad no se crea automáticamente y debe crearse explícitamente).
7. Crear identidades de agente: Crea uno o varios principales de servicio de identidad de agente bajo el modelo.

A medida que el agente lee la habilidad, puede que se le pida que instale extensiones u otras herramientas. Siga las indicaciones para asegurarse de que el entorno está listo.

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 su modelo de identidad de agente (por ejemplo, "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 de Microsoft Entra con, como mínimo, un perfil de desarrollador de ID de agente.
2. Vaya a Entra ID>Agentes>Identidades de agente para ver su nuevo modelo de identidad de agente y cualquier identidad de agente creada 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 a la API de ID de agente requieren el encabezado OData-Version: 4.0. Si omite este encabezado, la API podría crear silenciosamente 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. La habilidad también usa puntos de conexión tipados (como /applications/microsoft.graph.agentIdentityBlueprint) en lugar de /applications sin procesar con propiedades @odata.type para reducir el riesgo de este problema.

El principal del modelo no se crea automáticamente

La creación de un modelo de identidad de agente (POST /applications) no crea automáticamente su principal de modelo (principal de servicio). Sin el principal del modelo, todas las creaciones posteriores de identidades de agente fallarán con el siguiente mensaje:

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 administra los cambios recientes en los permisos reintentando las 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 de agente son principales de servicio sin objetos de aplicación subyacentes. 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 identidades administradas (recomendado) o añada secretos/certificados al modelo, y las identidades de agente heredarán las credenciales mediante la suplantación de identidad.

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 credenciales de identidad federada para modelos

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 ruta /applications/{id}/federatedIdentityCredentials podría funcionar para los modelos de identidad de agente, pero no es compatible 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:

• Uso de CLI de Azure o DefaultAzureCredential tokens: los tokens de CLI de Azure incluyen Directory.AccessAsUser.All, que las API de identidad del agente rechazan de plano. Use Connect-MgGraph con ámbitos delegados explícitos o un registro de aplicación dedicado con client_credentials. Consulte la advertencia de autenticación en los requisitos previos.
• Retraso de propagación de permisos: espere entre 1 y 2 minutos después del consentimiento del administrador y vuelva a intentarlo. La configuración guiada por IA controla esto automáticamente con lógica de reintento.
• 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 modelo se realiza correctamente, pero devuelve una aplicación estándar

Este resultado se produce cuando falta el OData-Version: 4.0 encabezado. Use el endpoint tipado (/applications/microsoft.graph.agentIdentityBlueprint) en lugar de /applications sin procesar con @odata.type para evitar este problema.

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/v1.0/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