Configuração guiada por IA para ID do Agente Microsoft Entra

A integração do ID do Agente Microsoft Entra envolve múltiplos passos: criar um blueprint de identidade de agente, configurar credenciais, configurar URIs e âmbitos de identificadores, criar principais do blueprint e provisionar identidades de agentes. Cada etapa tem os seus próprios pré-requisitos, verificações de validação e pontos de decisão.

Esta configuração guiada por IA automatiza todo este fluxo de trabalho usando um agente de codificação por IA (como o GitHub Copilot no VS Code) para executar os passos em seu nome. Em vez de navegar entre várias páginas de documentação e executar comandos manualmente, fornece ao agente de IA um único ficheiro de instruções e ele guia-o pelo processo de forma interativa.

Benefícios

A configuração guiada por IA oferece várias vantagens em relação ao fluxo de trabalho manual:

• Ponto de entrada único: Um ficheiro de instruções substitui a necessidade de navegar entre várias páginas de documentação. O agente de IA segue os passos por ordem e gere as transições automaticamente.
• Validação automática de pré-requisitos: O agente de IA valida que tem os papéis de Microsoft Entra corretos, que o módulo beta Microsoft Graph está instalado e que as permissões necessárias são configuradas com consentimento do administrador antes de fazer qualquer chamada à API.
• Padrões inteligentes e deteção automática: O agente de IA consulta o seu inquilino para obter informações existentes do utilizador e detalhes de recursos, e depois usa esses valores como sugestões ao recolher entradas de configuração.
• Convenções de nomenclatura derivadas: Fornece um único nome de exibição para o seu agente, e o agente de IA deriva todos os nomes de recursos relacionados (blueprint, blueprint principal, identidades de agentes, URIs de identificadores) usando padrões consistentes.
• Gestão de erros inline: Quando um comando falha, o agente de IA analisa o erro, sugere uma correção e tenta novamente, em vez de exigir que procure na documentação de resolução de problemas. Este tratamento de erros é especialmente valioso para problemas específicos associados ao ID do Agente, como atrasos na propagação de permissões e requisitos de cabeçalhos OData.
• Operações idempotentes: O agente IA verifica se os recursos já existem antes de os criar, tornando seguro reexecutar a configuração caso uma tentativa anterior tenha sido interrompida.

Pré-requisitos

Antes de começar, certifique-se de que cumpre os seguintes pré-requisitos.

Ferramentas necessárias

• Visual Studio Code com as extensões GitHub Copilot e GitHub Copilot Chat instaladas. A configuração guiada por IA requer um agente de codificação de IA com acesso ao terminal.
• PowerShell 7 ou posterior é necessário para o módulo PowerShell Microsoft Graph.
• SDK do PowerShell nos Microsoft Graph (beta) instalado usando Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force.

Contas e permissões necessárias

• Acesso a um locatário Microsoft Entra com uma das seguintes funções:
  • Desenvolvedor de ID de Agente para criar identidades de agente e planos de identidade. Qualquer proprietário de um blueprint de identidade de agente pode criar uma identidade de agente para esse blueprint sem uma função de ID de Agente.
  • Administrador de ID de Agente para acesso administrativo total aos recursos de ID de Agente.

• Funções adicionais para concessão de autorizações:
  • Privileged Role Administrator para conceder permissões à aplicação Microsoft Graph.
  • Cloud Application Administrator ou Application Administrator para conceder permissões Microsoft Graph delegadas.

Permissões necessárias do Microsoft Graph

O cliente que utiliza (PowerShell ou um registo personalizado de uma aplicação) deve estar autorizado com as seguintes permissões delegadas:

Código de agente obrigatório (opcional)

Se já tiveres um projeto de agente funcional (Python, Node.jsou .NET) que precisa de uma identidade de ID de Agente, tem o diretório do projeto disponível. Se ainda não tiveres uma, ainda podes completar a configuração do blueprint de forma independente.

Obtenha o ficheiro de instruções de configuração

A configuração guiada por IA utiliza as instruções encontradas no repositório Microsoft Skills GitHub.

Executa a configuração guiada por IA

Siga estes passos para iniciar a configuração guiada por IA.

Passo 1: Abra o seu projeto em VS Code

Abra o diretório do seu projeto de agente (ou qualquer diretório funcional) no Visual Studio Code.

Passo 2: Abra o GitHub Copilot Chat em modo agente

Abra o painel de Copilot Chat do GitHub e mude para Agente. O modo Agente dá ao GitHub Copilot a capacidade de executar comandos de terminal, ler ficheiros e interagir com o seu ambiente, algo que a configuração guiada por IA exige.

Passo 3: Anexe o ficheiro de instruções e comece

Na entrada Copilot Chat, anexe o ficheiro agent-id-setup-instructions.md e envie-o com um pequeno prompt. Por exemplo:

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

O agente de IA lê o ficheiro de instruções e inicia a configuração guiada. Cria uma lista de tarefas e percorre os passos sequencialmente:

1. Validar pré-requisitos: Verifica Microsoft Entra funções, valida que o PowerShell 7+ e o módulo beta Microsoft Graph estão instalados.
2. Authorize and connect: Liga-se ao Microsoft Graph com as permissões necessárias e define o perfil como beta.
3. Crie o blueprint de identidade do agente: Identifica o patrocinador (você), recolhe um nome de exibição, cria o blueprint com os cabeçalhos @odata.type e OData-Version necessários e regista o appId.
4. Configurar credenciais: Adiciona uma identidade gerida (para produção) ou um certificado ou cliente secreto (para desenvolvimento/testes locais) ao blueprint.
5. Configure o URI e o âmbito do identificador: Define identifierUris para api://{appId}, cria um access_agent âmbito de permissões OAuth2 para comunicação agente-a-agente e utilizador-para-agente.
6. Criar o principal do blueprint: Cria o principal de serviço para o blueprint (o principal não é criado automaticamente e deve ser configurado explicitamente).
7. Criar identidades de agentes: Cria um ou mais princípios de serviço de identidade de agente sob o blueprint.

Passo 4: Responder aos sugestões

O agente IA faz uma pausa em pontos específicos para recolher informações tuas:

• Nome de exibição: O nome de exibição para o modelo de identidade do seu agente (por exemplo, "Contoso Budget Agent").
• Patrocinador: O utilizador ou grupo responsável pelo agente. Por defeito, utiliza o utilizador que está atualmente com sessão iniciada.
• Proprietário: O utilizador ou principal de serviço que pode fazer alterações técnicas ao blueprint. Opcional, mas recomendado.
• Tipo de credencial: Se deve usar uma identidade gerida (recomendada para produção) ou um certificado ou segredo do cliente (para desenvolvimento local).
• Contagem de identidade de agente: Quantas identidades de agente criar neste modelo.
• Confirmação de valor derivado: Revise nomes e URIs gerados automaticamente antes de os recursos serem criados.

Passo 5: Verificar no centro de administração do Microsoft Entra

Depois de concluída a configuração, o agente de IA fornece instruções sobre como verificar os recursos:

1. Inicia sessão no centro de administração Microsoft Entra pelo menos como um Agent ID Developer.
2. Navegue por Entra ID>Agentes>Identidades de Agentes para ver o seu novo modelo de identidade de agente e quaisquer identidades de agente criadas a partir dele.
3. Verifique se o blueprint tem as credenciais corretas, URI do identificador e o escopo configurados corretamente.

O que cobre a configuração guiada por IA

A configuração guiada por IA automatiza as seguintes etapas da integração do Agent ID:

Armadilhas comuns que a configuração guiada por IA resolve

As APIs do Agent ID têm vários requisitos que a configuração guiada por IA deteta e resolve automaticamente, mas não são requisitos óbvios. Compreender estas armadilhas pode ser útil se precisar de resolver problemas ou expandir a configuração.

O cabeçalho OData-Version é obrigatório

Todas as chamadas Agent ID API que usam @odata.type requerem o OData-Version: 4.0 cabeçalho. Se omitir este cabeçalho, o @odata.type campo é ignorado silenciosamente, fazendo com que a API crie uma aplicação padrão em vez de um blueprint de identidade de agente. A configuração guiada por IA inclui sempre este cabeçalho.

Blueprint principal não é auto-criado automaticamente

Criar um blueprint de identidade de agente (POST /applications) não cria automaticamente o seu principal de blueprint (principal de serviço). Sem o blueprint principal, toda a criação subsequente de identidade de agente falha com:

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

A configuração guiada por IA cria sempre o blueprint principal imediatamente após o blueprint. Também trata do caso dos idempotentes. Se uma execução anterior criou o blueprint, mas falhou antes de criar a entidade principal, o processo de configuração deteta esta situação e cria a entidade principal em falta.

São necessários patrocinadores

Os patrocinadores são obrigatórios e podem ser utilizadores, grupos com membros dinâmicos ou grupos unificados. Tanto a criação do blueprint quanto a da identidade do agente requerem um campo sponsors@odata.bind. Sem ela, você recebe:

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

A configuração guiada por IA só aceita objetos User para atribuição de patrocinadores e utiliza o formato de URL /users/{objectId} (não /directoryObjects/ ou /servicePrincipals/). A configuração resolve o ID de objeto do usuário atual e usa-o como patrocinador padrão. Para atribuir um grupo suportado como patrocinador de um blueprint, use a Microsoft Graph API diretamente.

A propagação de permissões demora entre 30 e 120+ segundos

Depois de conceder consentimento de administrador para permissões de ID de Agente, as permissões recém-concedidas não aparecem imediatamente nos tokens. O endpoint do token serve reivindicações em cache, e a propagação pode demorar entre 30 a 120 segundos ou mais.

A configuração guiada por IA gere alterações recentes de permissões ao tentar novamente operações com recuo exponencial quando um 403 é recebido. Se estiver a escrever isto manualmente, implemente lógica de tentar novamente:

# 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
        }
    }
}

As identidades dos agentes não podem ter credenciais de palavra-passe

As identidades dos agentes são princípios de serviço sem objetos de aplicação de suporte. Tentar adicionar um passwordCredential diretamente à identidade de um agente resulta em:

PropertyNotCompatibleWithAgentIdentity

As credenciais devem ser configuradas no blueprint, não nas identidades individuais dos agentes. Use federação de identidades gerida (recomendado) ou adicione segredos/certificados ao blueprint, e as identidades dos agentes herdam a credencial através da impersonação.

O URI do identificador deve ser definido explicitamente

O campo do identifierUris blueprint não está definido por padrão. Sem isso, o âmbito api://{appId}/.default OAuth2 não se resolve e a aquisição de tokens para o agente falha. A configuração guiada por IA sempre define este valor como parte da etapa de configuração do escopo.

Trajeto de credenciais de identidade federada para blueprints

Ao adicionar credenciais de identidade federada (FIC) para a federação de identidades geridas, deve utilizar o caminho da API específico do agente:

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

Usar o /applications/{id}/federatedIdentityCredentials path pode funcionar para blueprints de identidade de agente, mas não é suportado nem recomendado.

O emissor do token varia consoante a versão do endpoint

Ao validar tokens no backend do seu agente, esteja ciente das seguintes variações:

• Os tokens v1.0 usam o emissor https://sts.windows.net/{tenant-id}/
• Os tokens v2.0 usam o emissor https://login.microsoftonline.com/{tenant-id}/v2.0

Aceita ambos os formatos na tua lógica de validação de tokens.

Troubleshooting

O agente de IA não executa comandos de terminal

Se o agente de IA descrever comandos mas não os executar, certifique-se de que está a usar modo Agente no GitHub Copilot Chat. Os modos Ask e Edit não têm acesso ao terminal.

Agente de IA salta passos de validação

O ficheiro de instruções impõe uma ordenação rigorosa dos passos. Se o agente de IA parecer saltar um passo, lembre-o de seguir as instruções desde o início. Por exemplo:

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

Os comandos de grafo falham com 403 - Proibido

As causas mais comuns dos erros 403:

• Atraso na propagação de permissões: Espere 1–2 minutos após o consentimento do administrador e tente novamente.
• Consentimento de administrador em falta: Verifique se as permissões necessárias têm o consentimento do administrador concedido no Centro de Administração do Microsoft Entra, em Registos de Aplicações, para a sua aplicação cliente e >.

A criação do blueprint é bem-sucedida, mas retorna uma aplicação padrão

Este resultado ocorre quando falta o OData-Version: 4.0 cabeçalho ou a @odata.type propriedade é omitida. Verifique se ambos estão presentes no pedido. Se utilizar cmdlets do PowerShell, certifique-se de que está a utilizar o módulo beta e a passar a estrutura correta do corpo da mensagem.

A criação da identidade do agente falha com "Blueprint Principal não existe"

O princípio do blueprint deve ser criado como um passo separado após o blueprint. Executar:

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

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

Erros na política de duração da credencial

O seu inquilino pode ter políticas de ciclo de vida das credenciais que limitam a vida máxima dos segredos dos clientes. Se receber um erro sobre o prazo de validade da credencial ao adicionar uma palavra-passe, reduza o valor endDateTime para alinhar com a política da sua organização.

Os valores de configuração precisam de ser alterados

Se precisares de alterar os valores de configuração após a configuração, podes:

• Reexecute a configuração guiada por IA com valores atualizados. As verificações de idempotência ignoram recursos que já existem corretamente.
• Utilize o Microsoft Graph PowerShell para atualizar propriedades específicas com pedidos de PATCH.

Passos seguintes

• Criar e eliminar identidades de agentes
• Relações administrativas no ID do Agente (Proprietários, patrocinadores e gestores)
• Identidades de agentes, princípios de serviço e aplicações
• Conceitos de modelo de identidade de agente