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

A integração do 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.

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

• Visual Studio Code com 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 Microsoft Graph PowerShell.
• SDK do PowerShell do Microsoft Graph (beta) instalado usando Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force.

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.

Acesse o arquivo de instruções de configuração

A instalação orientada por IA usa as instruções encontradas no repositório Microsoft Skills GitHub.

Execute a configuração guiada por IA

Siga estas etapas para iniciar a configuração guiada por IA.

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.

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

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

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

O agente de IA lê o arquivo de instruções e inicia a configuração guiada. Ele cria uma lista de tarefas e funciona por meio das etapas sequencialmente:

1. Validar pré-requisitos: verifica as funções do Microsoft Entra, valida que o PowerShell 7+ e o módulo beta do Microsoft Graph estão instalados.
2. Autorizar e conectar: conecta-se ao Microsoft Graph com os escopos necessários e define o perfil como beta.
3. Criar o blueprint de identidade do agente: coleta um nome de exibição, identifica o patrocinador (você), cria o blueprint com os cabeçalhos @odata.type e OData-Version necessários e registra o appId.
4. Configurar credenciais: adiciona uma identidade gerenciada (para produção) ou um certificado ou segredo do cliente (para desenvolvimento/teste local) ao blueprint.
5. Configure o URI do identificador e o escopo: Define identifierUris como api://{appId}, cria um access_agent escopo de permissão OAuth2 para comunicação de agente para agente e usuário para agente.
6. Criar a entidade de blueprint: cria a entidade de serviço para o blueprint (a entidade não é criada automaticamente e deve ser feita explicitamente).
7. Criar identidades de agente: cria uma ou mais entidades de serviço de identidade do agente no blueprint.

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 que usam @odata.type exigem o cabeçalho OData-Version: 4.0. Se você omitir esse cabeçalho, o @odata.type campo será silenciosamente ignorado, fazendo com que a API crie 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 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:

• Atraso na propagação de permissão: aguarde de 1 a 2 minutos após o consentimento do administrador e tente novamente.
• 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 ou a @odata.type propriedade é omitida. Verifique se ambos estão presentes na solicitação. Se estiver usando cmdlets do PowerShell, verifique se está usando o módulo beta e passando a estrutura de corpo correta.

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/beta/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