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

A integração ao ID do agente Microsoft Entra envolve várias etapas: criar um blueprint de identidade do agente, configurar credenciais, configurar URIs e escopos do identificador, criar entidades de blueprint e provisionar identidades do agente. Cada etapa tem seus próprios pré-requisitos, verificações de validação e pontos de decisão.

Essa configuração orientada por IA automatiza todo esse fluxo de trabalho usando um agente de codificação de IA (como GitHub Copilot no VS Code) para executar as etapas em seu nome. Em vez de navegar entre várias páginas de documentação e executar comandos manualmente, você fornece ao agente de IA um único arquivo de instruções que te guia pelo processo de forma interativa. Este arquivo de instrução está disponível como uma Habilidade e pode ser acessado de mais de uma maneira.

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 arquivo de instrução substitui a necessidade de navegar entre várias páginas de documentação. O agente de IA segue os passos em ordem e lida com as transições automaticamente.
• Automated prerequisite validation: o agente de IA valida que você tem as funções de Microsoft Entra corretas, que as ferramentas necessárias e os módulos do Graph estão instalados e que as permissões necessárias são configuradas com consentimento do administrador antes de fazer chamadas à API.
• Padrões inteligentes e detecção automática: o agente de IA consulta seu locatário para obter informações do usuário existentes e detalhes do recurso e, em seguida, usa esses valores como sugestões ao coletar entradas de configuração.
• Convenções de nomenclatura derivadas: você fornece um único nome de exibição para o agente, e o agente de IA deriva todos os nomes de recursos relacionados (blueprint, entidade de blueprint, identidades do agente, URIs do identificador) usando padrões consistentes.
• Tratamento de erros embutidos: quando um comando falha, o agente de IA analisa o erro, sugere uma correção e tenta novamente em vez de exigir que você pesquise a documentação de solução de problemas. Esse tratamento de erros é especialmente valioso para armadilhas específicas do ID do agente, como atrasos de propagação de permissão e requisitos de cabeçalho OData.
• Operações idempotentes: o agente de IA verifica se os recursos já existem antes de criá-los, tornando seguro executar novamente a configuração se uma tentativa anterior foi interrompida.

Pré-requisitos

Antes de começar, verifique se você tem os pré-requisitos a seguir.

Ferramentas necessárias

A configuração orientada por IA requer um agente de codificação de IA com acesso ao terminal:

• Visual Studio Code com extensões GitHub Copilot e GitHub Copilot Chat instaladas.
• A extensão GitHub Copilot for Azure, que disponibiliza a habilidade ID do agente Microsoft Entra diretamente no VS Code.

A habilidade oferece suporte a dois caminhos de provisionamento. Instale um ou ambos dependendo de sua preferência:

• Caminho do PowerShell: PowerShell 7 ou versão posterior com o SDK do Microsoft Graph para PowerShell. Instale usando Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force.
• Python path: Python 3.8 ou posterior com azure-identity e requests. Instale usando pip install azure-identity requests.

Contas e permissões necessárias

• Acesso a um Microsoft Entra tenant com uma das seguintes funções:
  • Desenvolvedor de ID do agente para criar esquemas de identidade do agente e identidades dos agentes. Qualquer proprietário de um modelo de identidade de agente pode criar uma identidade de agente para esse modelo sem uma função de ID de agente.
  • Administrador de ID do agente para acesso administrativo completo aos recursos de ID do agente.

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

Permissões de Microsoft Graph necessárias

O cliente usado (PowerShell ou um registro de aplicativo personalizado) deve ser autorizado com as seguintes permissões delegadas:

Código do agente necessário (opcional)

Se você já tiver um projeto de agente de trabalho (Python, Node.jsou .NET) que precise de uma identidade de agente, tenha o diretório do projeto disponível. Se você ainda não tiver um, ainda poderá concluir a instalação do blueprint de forma independente.

Introdução

A instalação orientada por IA usa uma habilidade, que é um único arquivo de instrução que contém todas as etapas e verificações de validação. Você pode acessar a habilidade de duas maneiras:

• Pela extensão GitHub Copilot para Azure (recomendada): Instale a extensão do VS Code GitHub Copilot para Azure. A habilidade ID do agente Microsoft Entra é ativada automaticamente quando você pergunta sobre a configuração da ID do Agente no Copilot Chat.
• Diretamente do GitHub: Use a habilidade independente do ID do agente Microsoft Entra referenciando-a no prompt do Copilot Chat.

Etapa 1: Abrir seu projeto no VS Code

Abra o diretório do projeto do agente (ou qualquer diretório de trabalho) em Visual Studio Code.

Etapa 2: Abrir o GitHub Copilot Chat no modo de agente

Abra o painel Copilot Chat github e alterne para Agent mode. O modo de agente fornece GitHub Copilot a capacidade de executar comandos de terminal, ler arquivos e interagir com seu ambiente, o que a configuração orientada por IA requer.

Etapa 3: Iniciar a configuração guiada

Se você tiver o GitHub Copilot para Azure extensão instalada, peça a Copilot para configurar a ID do Agente. Por exemplo:

@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.

Se você não tiver a extensão, faça referência à habilidade diretamente de GitHub:

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

O agente de IA lê a habilidade e inicia a configuração guiada. Ele percorre as etapas sequencialmente:

1. Validar pré-requisitos: verifica as funções do Microsoft Entra e valida se as ferramentas necessárias (PowerShell com o módulo Microsoft Graph ou Python com azure-identity) estão instaladas.
2. Autenticar: conecta-se ao Microsoft Graph com os escopos necessários. Para o PowerShell, a habilidade usa Connect-MgGraph com escopos delegados explícitos. Para Python, ele usa um registro de aplicativo dedicado com credenciais de cliente.
3. Criar o modelo de identidade do agente: coleta um nome de exibição, identifica o patrocinador (você), cria o modelo usando o ponto de extremidade informado (/applications/microsoft.graph.agentIdentityBlueprint) e registra o appId.
4. Configurar credenciais: adiciona uma credencial de identidade federada com identidade gerenciada (para produção) ou um segredo do cliente (para desenvolvimento/teste local) ao blueprint.
5. Configurar o URI do identificador e o escopo: define identifierUris como api://{appId} e cria um escopo de permissão OAuth2 para comunicação entre agentes e entre usuário e agente.
6. Criar o principal do blueprint: cria o principal de serviço para o blueprint usando o endpoint tipado (o principal não é criado automaticamente e deve ser criado explicitamente).
7. Criar identidades de agente: cria uma ou mais entidades de serviço de identidade do agente no blueprint.

À medida que o agente lê a habilidade, você pode ser solicitado a instalar extensões ou outras ferramentas. Siga as instruções para garantir que seu ambiente esteja pronto.

Passo 4: Responda às solicitações

O agente IA pausa em pontos específicos para coletar informações suas:

• Nome de exibição: nome de exibição do blueprint de identidade do agente (por exemplo, "Agente de orçamento da Contoso").
• Patrocinador: o usuário ou grupo responsável pelo agente. O padrão é o usuário conectado no momento.
• Proprietário: o usuário ou a entidade de serviço que pode fazer alterações técnicas no blueprint. Opcional, mas recomendado.
• Tipo de credencial: se deve usar uma identidade gerenciada (recomendada para produção) ou um certificado ou segredo do cliente (para desenvolvimento local).
• Contagem de identidades de agente: quantas identidades de agente criar neste modelo.
• Confirmação de valor derivado: examine os nomes e URIs gerados automaticamente antes que os recursos sejam criados.

Etapa 5: verificar no centro de administração do Microsoft Entra

Após a conclusão da instalação, o agente de IA fornece instruções sobre como verificar os recursos:

1. Entre no Centro de administração do Microsoft Entra como, no mínimo, um Desenvolvedor de ID de agente.
2. Navegue até Entra ID>Agentes>Identidades de agente para ver o novo blueprint de identidade do agente e todas as identidades de agente criadas nele.
3. Verifique se o blueprint tem as credenciais corretas, o URI do identificador e o escopo configurado.

O que a configuração guiada por IA cobre

A instalação orientada por IA automatiza os seguintes estágios da integração da ID do Agente:

Armadilhas comuns que a configuração guiada por IA lida com

As APIs de ID do Agente têm vários requisitos que a instalação orientada por IA detecta e resolve automaticamente, mas não são requisitos óbvios. Entender essas armadilhas pode ser útil se você precisar depurar problemas ou estender a configuração.

O cabeçalho OData-Version é obrigatório

Todas as chamadas à API de ID do Agente exigem o cabeçalho OData-Version: 4.0. Se você omitir esse cabeçalho, a API poderá criar silenciosamente um aplicativo padrão em vez de um blueprint de identidade do agente. A configuração orientada por IA sempre inclui esse cabeçalho. A habilidade também usa endpoints tipados (como /applications/microsoft.graph.agentIdentityBlueprint) em vez de /applications brutos com propriedades @odata.type para reduzir o risco desse problema.

A entidade do blueprint não é criada automaticamente

A criação de um blueprint de identidade do agente (POST /applications) não cria automaticamente a entidade de blueprint (entidade de serviço). Sem a entidade de blueprint, toda a criação de identidades de agentes subsequentes falha com:

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

A configuração guiada por IA sempre cria a entidade imediatamente após o blueprint. Ele também lida com o caso idempotente. Se uma execução anterior criou o blueprint, mas falhou antes de criar a entidade, a configuração detectará esse evento e criará a entidade ausente.

Os patrocinadores são necessários

Os patrocinadores são necessários e podem ser usuários, grupos com associação dinâmica ou grupos unificados. Tanto o blueprint quanto a criação de identidade do agente exigem um sponsors@odata.bind campo. Sem ele, você receberá:

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

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

A propagação de permissão leva de 30 a 120+ segundos

Depois de conceder o consentimento do administrador para as permissões de ID do Agente, as permissões recém-concedidas não aparecem imediatamente nos tokens. O ponto de extremidade de token atende a declarações armazenadas em cache e a propagação pode levar de 30 a 120 segundos ou mais.

A configuração guiada por IA lida com alterações recentes de permissão ao repetir operações com retirada exponencial quando um erro 403 é recebido. Se você estiver fazendo o script manualmente, implemente a lógica de repetição:

# 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 do agente não podem ter credenciais de senha

As identidades do agente são entidades de serviço sem objetos de aplicativo subjacentes. A tentativa de adicionar um passwordCredential diretamente a uma identidade de agente resulta em:

PropertyNotCompatibleWithAgentIdentity

As credenciais devem ser configuradas no blueprint, não em identidades de agente individuais. Use a federação de identidade gerenciada (recomendada) ou adicione segredos/certificados ao blueprint e as identidades dos agentes herdam a credencial por meio de representação.

O URI do identificador deve ser definido explicitamente

O campo do identifierUris blueprint não é definido por padrão. Sem ele, o escopo api://{appId}/.default OAuth2 não será resolvido e a aquisição de token para o agente falhará. A configuração guiada por IA sempre configura esse valor como parte da etapa de configuração do escopo.

Caminho de credenciais de identidade federada para blueprints

Ao adicionar credenciais de identidade federadas (FIC) para federação de identidade gerenciada, você deve usar o caminho da API específica do agente:

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

O uso do caminho /applications/{id}/federatedIdentityCredentials pode funcionar para blueprints de identidade do agente, mas não tem suporte e não é recomendado.

O emissor do token depende da versão do endpoint.

Ao validar tokens no back-end do agente, lembre-se das seguintes variações:

• Emissor de uso de tokens v1.0 https://sts.windows.net/{tenant-id}/
• Emissor de uso de tokens v2.0 https://login.microsoftonline.com/{tenant-id}/v2.0

Aceite ambos os formatos em sua lógica de validação de token.

Solução de problemas

Agente de IA não executa comandos de terminal

Se o agente de IA descreve comandos, mas não os executa, verifique se você está usando o modo Agent no GitHub Copilot Chat. Os modos Perguntar e Editar não têm acesso ao terminal.

Agente de IA pula etapas de validação

O arquivo de instruções impõe uma ordenação rigorosa de passos. Se o agente de IA parecer pular uma etapa, 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 do Graph falham com o 403-Forbidden

As causas mais comuns de 403 erros:

• Usando a CLI do Azure ou tokens DefaultAzureCredential: os tokens da CLI do Azure incluem Directory.AccessAsUser.All, que as APIs de Identidade do Agente rejeitam imediatamente. Use Connect-MgGraph com escopos delegados explícitos ou um registro de aplicativo dedicado com client_credentials. Consulte o aviso de autenticação nos pré-requisitos.
• Atraso na propagação de permissão: aguarde de 1 a 2 minutos após o consentimento do administrador e tente novamente. A configuração guiada por IA cuida disso automaticamente com lógica de novas tentativas.
• Consentimento do administrador ausente: verifique se as permissões necessárias têm o consentimento do administrador concedido no centro de administração do Microsoft Entra em Registros de aplicativos> do seu aplicativo cliente >permissões de API.

A criação do blueprint é bem-sucedida, mas retorna um aplicativo padrão

Esse resultado ocorre quando o OData-Version: 4.0 cabeçalho está ausente. Use o endpoint tipado (/applications/microsoft.graph.agentIdentityBlueprint) em vez do /applications bruto com @odata.type para evitar esse problema.

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

A entidade do blueprint deve ser criada como uma etapa separada após o blueprint. Execute:

POST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

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

Erros de política de tempo de vida útil de credencial

Seu locatário pode ter políticas de ciclo de vida de credencial que restringem o tempo de vida máximo para segredos do cliente. Se você receber um erro sobre o tempo de vida da credencial ao adicionar uma senha, reduza o endDateTime valor para se alinhar à política da sua organização.

Os valores de configuração precisam ser alterados

Se você precisar alterar os valores de configuração após a instalação, poderá:

• Execute novamente a configuração guiada por IA com valores atualizados. As verificações idempotentes ignoram os recursos que já existem corretamente.
• Utilize o Microsoft Graph PowerShell para atualizar propriedades específicas com PATCH solicitações.

Próximas Etapas 

• Criar e excluir identidades do agente
• Relações administrativas no ID do agente (proprietários, patrocinadores e gerentes)
• Identidades de agente, identidade de serviço e aplicações
• Conceitos de blueprint de identidade do agente