Compartilhar via

Blueprint de Configuração do Agente

Importante

Você precisa fazer parte do programa de prévia Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente às mais recentes inovações de IA da Microsoft. As versões preliminares da Frontier estão sujeitas aos termos de versão preliminar existentes dos contratos de cliente. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

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 tenant 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 a365.config.json válido no seu diretório de trabalho, configurado por esta etapa: Configuração do Agent 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 do 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

Observação

Durante a configuração, o comando abre janelas do navegador para o consentimento do administrador. Preencha esses fluxos de consentimento para prosseguir. A instalação normalmente leva de 3 a 5 minutos e salva a configuração automaticamente para a365.generated.config.json.

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:

    • Procure 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:

Permissões de agente

Antes que os aplicativos e agentes possam ler ou gravar dados do Microsoft 365 (usuários, emails, arquivos, Teams, agentes etc.), eles devem receber permissões explicitamente do Microsoft Graph. As permissões do Microsoft Graph são o modelo de autorização que controla quais dados e ações um aplicativo ou serviço pode acessar por meio das APIs do Microsoft Graph no Microsoft 365 e na ID do Entra.

Saiba mais: Visão geral das permissões do Microsoft Graph

Para utilizar permissões do Graph para instâncias de agente do Agente 365, elas devem ser declaradas no blueprint do agente pelo desenvolvedor. Quando um administrador no Centro de Administração do Microsoft 365 ativa o blueprint em seu locatário, as permissões do Graph do blueprint são revisadas e o administrador consente com elas durante o processo de ativação.

Para entender e validar como as permissões do Graph habilitam seu agente, você pode:

Aplique permissões ao seu modelo

Use a365 config permissions para adicionar as permissões de recurso necessárias à sua configuração, em seguida execute a365 setup permissions custom para aplicá-las ao blueprint no Microsoft Entra.

# Add resource permissions to config
a365 config permissions `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

# Apply permissions to your blueprint
a365 setup permissions custom

Para obter detalhes completos sobre como configurar e remover permissões personalizadas, consulte setup permissions custom.

Próximas etapas

Implante o código do seu agente na nuvem:

Azure

Serviços Web da Amazon (AWS)

Plataforma de Nuvem do Google (GCP)

Publicar agente no Microsoft admin center

Resolução de problemas

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

Dica

O Guia de Solução de Problemas do Agente 365 contém recomendações de resolução de problemas de alto nível, melhores práticas e links para conteúdo de solução de problemas para cada parte do ciclo de desenvolvimento do Agente 365.

Esses problemas às vezes ocorrem durante o registro:

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 do Microsoft Entra:

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

É necessário ter acesso de colaborador ou proprietário em uma assinatura do Azure.

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

Falta autenticação da Azure CLI

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

Solução: 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 a365.config.json e execute novamente a instalação.

    Você pode usar o comando do az group delete 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 e, em seguida, o a365 setup all comando para executar novamente a instalação.

    Aviso

    Executar a365 cleanup é destrutivo

    a365 cleanup
a365 setup all

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 solicita novamente 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 init de configuração a365.
# 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 os recursos estiverem ausentes, verifique se há erros na saída da instalaçã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

Blueprint do agente não registrado no 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 a ID do blueprint da configuração gerada usando o comando a365 config display -g..

    a365 config display -g
# Look for: agentBlueprintId

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

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

  3. Se não for encontrado, execute novamente a instalação 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. Localize o registro de aplicativo de blueprint do 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á habilitada.

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, cancele (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

Não é possível enviar a primeira mensagem no Teams

Sintoma: Depois que uma instância de agente é provisionada, não é possível enviar uma mensagem ao gerente do agente como uma mensagem de boas-vindas.

Solução: A permissão [Chat.Create][perm-chatcreate] é necessária para criar um novo objeto de chat. Se já existir uma conversa individual, esta operação devolve o chat existente e não cria um novo.

  • Para implementar, configure as permissões herdáveis do seu blueprint para incluir o Chat.Create escopo.
  • Configure uma mensagem de chat do Teams para enviar depois que uma instância do agente for provisionada.
  • Crie uma nova instância de agente a partir do blueprint e teste a mensagem de primeira execução.
  • Last updated on