Blueprint de Configuração do Agente

O blueprint do agente define a identidade, permissões e requisitos de infraestrutura do seu agente. Crie cada instância de agente a partir deste modelo de agente.

Para mais informações sobre a Identidade do Agente 365, veja Identidade do Agente 365.

Pré-requisitos

Antes de começar, verifique se você tem os seguintes pré-requisitos:

1. CLI do Agente 365 - Veja instalação do CLI do Agente 365.

2. Permissões necessárias:

   • Usuário válido do inquilino com uma das seguintes funções:
     • Administrador Global
     • Administrador de ID de Agente
     • Desenvolvedor de Agente ID
   • Acesso a uma assinatura Azure com permissões para criar recursos

3. Arquivo válido a365.config.json no seu diretório de trabalho, configurado por esta etapa: Configuração do Agente 365.

Criar projeto de agente

Use o comando para criar recursos do Azure e registrar o seu blueprint do agente . O blueprint define a identidade do seu agente, permissões e requisitos de infraestrutura. Esta etapa estabelece a base para implantar e executar seu agente no Azure.

Executar a instalação

Execute o comando de configuração:

a365 setup -h

O comando tem várias opções. Você pode completar toda a configuração em um único comando usando a365 setup all ou escolhendo opções mais detalhadas.

Todo o processo de configuração realiza estas operações:

1. Cria Azure infraestrutura (se ainda não existir):

   • Grupo de recursos
   • Plano de Serviço de Aplicativos com SKU especificado
   • Azure Aplicativo Web com identidade gerenciada habilitada

2. Projeto do agente de registros:

   • Cria o blueprint do agente em seu locatário Microsoft Entra
   • Cria os registros de aplicativos do Microsoft Entra
   • Configura a identidade do agente com as permissões necessárias

3. Configurar permissões de API:

   • Configura os escopos do Microsoft Graph API
   • Configura permissões da API do Bot de Mensagens
   • Aplica permissões herdadas para instâncias de agente

4. Atualizar arquivo de configuração

   • Salva IDs e endpoints gerados em um novo arquivo no seu diretório de trabalho chamado a365.generated.config.json
   • Registros de identidade gerenciada e informações de recursos

Verificar configuração

Depois que a configuração termina, você vê um resumo que mostra todos os passos concluídos. Verifique os recursos criados:

1. Verifique a configuração gerada:

   a365 config display -g
   

   A produção esperada inclui estes valores críticos:

   {
   "managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "agentBlueprintClientSecretProtected": true,
   "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMessagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   Campos principais a verificar:

   Campo	Propósito	O que verificar
   managedIdentityPrincipalId	Autenticação de identidade gerenciada do Azure	Deve ser um GUID válido
   agentBlueprintId	Identificador único do seu agente	Usado no Portal de Desenvolvedores e no centro de administração
   agentBlueprintObjectId	Microsoft Entra ID do Blueprint
   botMessagingEndpoint	Roteamento de mensagem	Onde o Teams/Outlook envia mensagens para o seu agente
   agentBlueprintClientSecret	Segredo de autenticação	Deveria existir (o valor é mascarado)
   resourceConsents	Permissões da API	Deve conter recursos como Microsoft Graph, Ferramentas do Agente 365, API do Bot de Mensagens, API de Observabilidade
   completed	Status de configuração	Deveria ser true

2. Verifique recursos do Azure em Azure Portal:

   Ou usar o az resource list comando PowerShell.

   # List all resources in your resource group
   az resource list --resource-group <your-resource-group> --output table
   

   Verifique se os seguintes recursos foram criados:

   • Grupo de Recursos.

     • Vá para Grupos de Recursos> Selecione seu grupo de recursos
     • Verifique se ele contém seu Plano de Serviço de Aplicativos e Web App

   • Plano do Serviço de Aplicativo

     • Vá para Serviços de Aplicativos>Planos de Serviço de Aplicativo
     • Encontre seu plano e verifique se o preço corresponde ao seu SKU de configuração

   • Aplicativo Web

     • Vá para App Services>Web Apps
     • Encontre seu aplicativo web e vá até Configurações>Sistema de Identidade>Atribuído
     • Verifique se o status está Ligado
     • Note que o ID do Objeto (principal) é igual a managedIdentityPrincipalId.

3. Verifique aplicações do Microsoft Entra no Azure Portal:

   Vá para Azure Active Directory>App registrations>Todos aplicativos:

   • Faça uma busca pelo seu blueprint de agente pelo agentBlueprintId

   • Abra o aplicativo e selecione Permissões de API

   • Permissões de verificação são concedidas com marcas verdes:

     • Microsoft Graph (permissões delegadas e de aplicativo)
     • Permissões da API de bots de mensagens

   • Todas as permissões mostram "Concedidas para [Seu Inquilino]"

4. Verificar o arquivo de configuração gerado criado:

   Deveria haver um arquivo nomeado a365.generated.config.json que contenha todos os dados de configuração.

   Você pode testar se ele existe usando o comando PowerShell Test-Path .

   # Check file exists
   Test-Path a365.generated.config.json
   # Should return: True
   

   Importante

   Salve ambos a365.config.json e a365.generated.config.json arquivos. Você precisa desses valores para implantação e solução de problemas.

5. O aplicativo Verify Web habilitou identidade gerenciada:

   Use o az webapp identity show comando para verificar se a identidade gerenciada está ativada.

   az webapp identity show --name <your-web-app> --resource-group <your-resource-group>
   

   Esperado:

   {
   "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "type": "SystemAssigned"
   }
   

6. Verifique o modelo do agente registrado no Entra:

   No centro de administração do Microsoft Entra, pesquise seu agentBlueprintId ou pesquise pelo nome.

   Verifique se:

   ✅ Registro de Aplicativos e Aplicativo Empresarial são exibidos
   ✅ No blueprint de registro do app, a aba de permissões da API mostra todas as permissões
   ✅ O status mostra "Concedido para [Seu Inquilino]"

Para mais ajuda, veja:

• Problemas de configuração
• Problemas com aplicativos clientes personalizados

Próximas etapas

Implante o código do seu agente na nuvem:

Resolução de problemas

Esta seção descreve problemas comuns ao configurar planos de agentes.

Esses problemas às vezes ocorrem durante o registro:

• Erro de permissões insuficientes
• Autenticação do Azure CLI ausente
• O recurso já existe
• Consentimento do administrador não concluído
• Arquivos de configuração ausentes ou inválidos
• A configuração terminou, mas os recursos não foram criados
• Modelo do agente não registrado em Entra
• Permissões da API não concedidas
• Identidade gerenciada não habilitada
• A configuração demora muito ou trava

Erro de permissões insuficientes

Sintoma: Erro de permissões insuficientes durante a a365 setup execução do comando .

Você precisa de uma das seguintes funções em seu locatário Microsoft Entra:

• Administrador Global
• Administrador de ID de Agente
• Desenvolvedor de Agente ID

Acesso de colaborador ou proprietário da assinatura do Azure.

Solução: Verifique se você tem as permissões necessárias no Entra.

• Acesse: Microsoft Entra centro de administração> Seu perfil > funções atribuídas
• Verificar o acesso à assinatura do Azure usando o comando az account show PowerShell

Falta autenticação da Azure CLI

Sintoma: A configuração falha com erros de autenticação.

Solution: Verifique se você está conectado ao Azure e verifique sua conta e assinatura.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

O recurso já existe

Sintoma: A configuração falha com Resource already exists erro para grupo de recursos, plano de serviços de aplicativos ou aplicativo web.

Soluções: Escolha uma das seguintes soluções

• Uso dos recursos existentes

  Se existem recursos e você quiser usá-los, certifique-se de que eles correspondam à sua configuração. Use o comando az resource list PowerShell.

  az resource list --resource-group <your-resource-group>
  

• Exclua recursos conflitantes

  Exclua o grupo de recursos ou renomeie seus recursos em a365.config.json e execute a configuração novamente.

  Você pode usar o az group delete comando PowerShell para excluir um grupo de recursos.

  # WARNING: This command deletes all resources in it
  az group delete --name <your-resource-group>
  

• Use o comando de limpeza para recomeçar do zero

  Use o cleanup comando para remover todos os recursos do Agente 365, depois o a365 setup all comando para reiniciar a configuração.

  Aviso

  Executar a365 cleanup é destrutivo

  a365 cleanup
  a365 setup all
  

Consentimento do administrador não concluído

Sintoma: Janelas do navegador abrem durante a configuração, mas você as fechou sem completar o consentimento.

Solução: Execute o a365 setup all comando. A CLI resolicita o consentimento do administrador:

Complete todos os fluxos de consentimento nas janelas do navegador que aparecem.

Arquivos de configuração ausentes ou inválidos

Sintoma: A configuração falha com "Configuração não encontrada" ou erros de validação.

Solution:

1. Verifique se o a365.config.json arquivo existe.
2. Exiba a configuração atual usando o comando a365 config display.
3. Se estiver ausente ou inválido, reinicialize usando o comando a365 config init.

# Verify a365.config.json exists
Test-Path a365.config.json

# Display current configuration
a365 config display

# If missing or invalid, re-initialize
a365 config init

A configuração terminou, mas os recursos não foram criados

O comando de configuração é bem-sucedido, mas os recursos do Azure não existem.

Solution:

1. Verifique os recursos criados usando o a365 config display -g comando.
2. Verifique se Azure recursos existem usando o comando az resource list.
3. Se recursos estiverem faltando, verifique se há erros na saída de configuração e execute novamente usando o a365 setup all comando.

# Check created resources
a365 config display -g

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Projeto do agente não registrado na Entra

Symptom: Instalação é concluída, mas não consegue encontrar o blueprint do agente no centro de administração Microsoft Entra.

Solution:

1. Obtenha o ID do blueprint da configuração gerada usando o a365 config display -g command.

   a365 config display -g
   # Look for: agentBlueprintId
   

2. Pesquise no centro de administração do Microsoft Entra:

   1. Acesse: Microsoft Entra centro de administração.
   2. Navegue até App registrations>Todos aplicativos
   3. Procure por seu agentBlueprintId

3. Se não for encontrado, execute a configuração novamente usando o a365 setup all comando.

   a365 setup all
   

Permissões da API não concedidas

Sintoma: A configuração foi concluída, mas as permissões aparecem como "Não concedidas" no Entra.

Solution:

1. Abra Microsoft Entra centro de administração

2. Encontre o registro do seu aplicativo de blueprint para agente

3. Ir para permissões de API

4. Conceda consentimento do administrador:

   1. Selecione Conceder consentimento administrativo para [Seu Inquilino]
   2. Confirme a ação

5. Verifique se todas as permissões exibem marcas de verificação verdes.

Identidade gerenciada não habilitada

Sintoma: O aplicativo web existe, mas a identidade gerenciada não está ativada.

Solution:

1. Verifique o status de identidade gerenciada usando o az webapp identity show comando.
2. Se não estiver ativado, ative-o manualmente usando o az webapp identity assign comando.
3. Verifique se está ativado usando o az webapp identity show comando.

# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

A configuração demora muito ou trava

Sintoma: O comando de configuração dura mais de 10 minutos sem ser concluído.

Solution:

1. Verifique se as janelas do navegador estão aguardando consentimento - complete todos os fluxos de consentimento.

2. Se realmente estiver travado, interrompa (Ctrl+C) e verifique o que foi criado:

   # Check generated config
   a365 config display -g
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. Limpe e tente novamente:

   a365 cleanup
   a365 setup all