Configurar blueprint do agente

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

Para obter mais informações sobre a Identidade do Agent 365, consulte Identidade do Agent 365.

Pré-requisitos

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

1. CLI do Agent 365 - Consulte instalação da CLI do Agent 365.

2. Permissões necessárias:

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

   Dica

   Os agentes (que não são colegas de equipe controlados por IA) não precisam de um arquivo de configuração. Usar a365 setup all --agent-name <name> e a CLI resolve seu locatário e aplicativo cliente automaticamente. A configuração do companheiro de equipe de IA requer uma criação manual de a365.config.json.

Criar blueprint do agente

Use o comando a365 setup para criar recursos Azure e registrar seu blueprint do agente. O blueprint define a identidade, as permissões e os requisitos de infraestrutura do seu agente. Esta etapa estabelece as bases para a implantação e a execução do 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 escolher opções mais granulares.

Configuração do agente (padrão):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

Configuração do agente M365 (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

Configuração dos colegas de equipe controlados pela IA:

a365 setup all --aiteammate

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

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

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

2. Registra blueprint do agente:

   • Cria o blueprint do agente em seu locatário do Microsoft Entra
   • Cria registros de aplicativo do Microsoft Entra
   • Configura a identidade do agente com as permissões necessárias
   • Define managerApplications no blueprint, que é necessário para o gerenciamento da plataforma

   Importante

   Os blueprints devem ter managerApplications definido para serem aceitos pela plataforma. A CLI define isso automaticamente. Se você já possui um blueprint criado antes de esse requisito ser introduzido, exclua-o e execute a365 setup all novamente, ou corrija-o manualmente via API do Graph.

3. Configurar permissões de API:

   • Configura os escopos da API do Microsoft Graph
   • Configura as permissões da API do bot do sistema de mensagens
   • Aplica permissões herdadas para instâncias de agente

4. Atualiza os arquivos de configuração:

   • Salva IDs e pontos de extremidade gerados em um novo arquivo no seu diretório de trabalho a365.generated.config.json
   • Registra informações sobre identidades e recursos gerenciados

Configuração usando o Desenvolvedor de ID do agente

Se você estiver trabalhando com o Desenvolvedor de ID do agente (e não como Administrador Global), a365 setup all conclui a maioria das etapas automaticamente, mas a concessão de permissões OAuth2 requer uma etapa separada por parte do administrador global.

Quais etapas são concluídas automaticamente:

• Infraestrutura do Azure (grupo de recursos, Plano de Serviço de Aplicativos, Aplicativo Web)
• Registro de blueprint do agente
• Permissões herdáveis para instâncias de agente

Quais etapas exigem um Administrador Global:

• Concessões de permissão delegada OAuth2 (consentimentoAllPrincipals ) para Microsoft Graph, Ferramentas do Agent 365, API de Bot de Mensagens, API de Observabilidade e API do Power Platform

Como concluir a configuração usando uma conta que não seja do administrador:

Executando os comandos:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

Compartilhe as próximas etapas exibidas pela CLI com seu Administrador Global. Eles podem abrir o link fornecido ou a URL de consentimento para concluir as autorizações OAuth2.

Verificar configuração

Quando a configuração for concluída, você verá um resumo que mostra todas as etapas concluídas. Verifique os recursos criados:

1. Verifique a configuração gerada:

   Abra a365.generated.config.json no seu diretório de trabalho. Ou usar o PowerShell:

   Get-Content a365.generated.config.json | ConvertFrom-Json
   

   A saída 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",
   "messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   Campos principais a serem verificados:

   Campo	Finalidade	O Que Verificar
   managedIdentityPrincipalId	Autenticação por identidade gerenciada do Azure	Deve ser um GUID válido
   agentBlueprintId	O identificador exclusivo do seu agente	Utilizado no Portal do Desenvolvedor e no Centro de Administração
   agentBlueprintObjectId	Microsoft Entra ID da Blueprint
   messagingEndpoint	Roteamento de mensagens	Onde o Teams/Outlook envia mensagens para o seu agente
   agentBlueprintClientSecret	Segredo da autenticação	Deve existir (o valor está oculto)
   resourceConsents	Permissões da API	Deve conter recursos como Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API
   completed	Status da configuração	Deve ser true

   Observação

   Se você executou a configuração como Administrador de ID do Agente ou Desenvolvedor de ID do Agente, resourceConsents pode estar vazia e completed pode ser false até que um Administrador Global conclua as concessões de permissão OAuth2 usando as próximas etapas impressas pela CLI.

2. Verifique os recursos do Azure no Portal do Azure:

   Ou use o comando az resource list do 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:

     • Acesse Grupos de recursos> Selecione seu grupo de recursos
     • Verifique se ele contém seu Plano do Serviço de Aplicativos e seu aplicativo web

   • Plano do Serviço de Aplicativo:

     • Acesse Serviços de Aplicativo>Planos de Serviço de Aplicativo
     • Encontre seu plano e verifique se o tipo de preço corresponde ao seu SKU de configuração

   • Aplicativo Web:

     • Acesse Serviços de Aplicativo>Aplicativos Web
     • Encontre seu aplicativo Web e acesse Configurações>Identidade>Sistema atribuído
     • Verifique se o status está Ativado
     • Note que a ID do Objeto (principal) corresponde a managedIdentityPrincipalId

3. Verifique os aplicativos Microsoft Entra no portal do Azure:

   Acesse Azure Active Directory>Registros de aplicativos>Todos os aplicativos:

   • Procure pelo seu blueprint de agente pelo agentBlueprintId

   • Abra o aplicativo e selecione Permissões da API

   • Verifique se as permissões foram concedidas com marcas de seleção verdes:

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

   • Todas as permissões mostram "Concedidas para [Seu Locatário]"

4. Verifique se o arquivo de configuração gerado foi criado:

   Você deve ter um arquivo chamado a365.generated.config.json que contém todos os dados de configuração.

   Use o comando PowerShell Test-Path para verificar se ele existe.

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

   Importante

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

5. Verifique se o aplicativo Web está com identidade gerenciada habilitada:

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

   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. Verificar se o blueprint do agente está registrado no Microsoft Entra:

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

   Verifique se:

   ✅ Aparecem as opções Registro do aplicativo e Aplicativo corporativo
   ✅ No blueprint de registro de aplicativo, a aba Permissões da API mostra todas as permissões
   ✅ O status mostra "Concedido para [Seu Locatário]"

Para obter mais ajuda, consulte:

• Problemas com aplicativos personalizados para clientes

Permissões de agente

Antes que os aplicativos e agentes possam ler ou gravar dados do Microsoft 365 (usuários, e-mails, arquivos, Teams, agentes etc.), é necessário conceder explicitamente a eles permissões 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 no Microsoft Entra ID.

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

Para utilizar as permissões do Graph nas instâncias do agente do Agent 365, o desenvolvedor deve declará-las no blueprint do agente. Quando um administrador ativa o blueprint no Centro de Administração do Microsoft 365, o porta revisar as permissões do Graph do blueprint e solicita que o administrador forneça o consentimento necessário.

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

• Consulte todas as permissões do Microsoft Graph disponíveis.
• Acesse o Explorador de gráficos para testar consultas, analisar respostas e entender as permissões.
• Use o Microsoft 365 Agents Playground para testar seu agente localmente antes da implantação.

Aplique permissões ao seu blueprint

Use a365 setup permissions custom para aplicar permissões personalizadas de API diretamente ao seu blueprint no Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

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:

Solução de Problemas

Esta seção descreve problemas comuns durante a configuração de blueprints de agentes.

Esses problemas às vezes ocorrem durante o registro:

• Erro de permissões insuficientes
• Autenticação da CLI do Azure 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
• Blueprint do agente não registrado no Microsoft Entra
• Permissões da API não concedidas
• A identidade gerenciada não está ativada
• A instalação demora muito ou para de responder
• Limpar um agente sem configuração
• Não é possível enviar a primeira mensagem no Teams

Erro de permissões insuficientes

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

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

• Administrador Global
• Desenvolvedor de ID de agente

É 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 Microsoft Entra.

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

Autenticação da CLI do Azure ausente

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

Solução: certifique-se de estar 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 o erro Resource already exists para o grupo de recursos, plano do Serviço de Aplicativos ou Aplicativo Web.

Soluções: escolha uma das seguintes soluções.

• Utilizar os recursos disponíveis

  Se houver recursos disponíveis e você quiser utilizá-los, certifique-se de que eles sejam compatíveis com a sua configuração. Use o comando az resource list do 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 refaça a configuração.

  Use o comando az group delete do 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 comando cleanup para remover todos os recursos do Agent 365 e, em seguida, execute o comando a365 setup all para executar novamente a configuração.

  Aviso

  Executar a365 cleanup é destrutivo.

  a365 cleanup
  a365 setup all
  

Consentimento do administrador não concluído

Sintoma: você abriu janelas do navegador durante a configuração, mas as fechou antes de concluir o consentimento, ou a configuração foi concluída, mas as permissões do OAuth2 ainda estão pendentes.

Solução: escolha com base na sua função:

• Administrador Global: execute a365 setup all novamente. A CLI solicita consentimento do administrador. Conclua o fluxo de consentimento na janela do navegador que aparecer.

• Administrador ou Desenvolvedor de ID do Agente: você não pode concluir as concessões do OAuth2 diretamente. Executar a365 setup all – o resumo da configuração apresenta as próximas etapas para um Administrador Global, incluindo um link direto ou URL de consentimento para concluir a aceitação das permissões. Compartilhe esses detalhes com seu Administrador Global.

Arquivos de configuração ausentes ou inválidos

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

Solução:

1. Verifique se o arquivo a365.config.json existe.
2. Se estiver ausente ou inválido, crie o arquivo manualmente ou use a365 setup all --agent-name <name> (somente para agentes).

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

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

Sintoma: o comando de configuração foi executado com sucesso, mas os recursos do Azure não existem.

Solução:

1. Verifique os recursos criados abrindo a365.generated.config.json no seu diretório de trabalho.
2. Verifique se os recursos do Azure existem usando o comando az resource list ..
3. Se faltar algum recurso, verifique se há erros na saída da configuração e execute novamente a configuração usando o comando a365 setup all ..

# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# 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 Microsoft Entra

Sintoma: a configuração é concluída, mas você não encontra o blueprint do agente no Centro de administração do Microsoft Entra.

Solução:

1. Obter uma ID do blueprint do a365.generated.config.json.

   Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId
   

2. Pesquisar no Centro de administração do Microsoft Entra:

   1. Acesse: centro de administração do Microsoft Entra.
   2. Navegue até Registros de aplicativos>Todos os aplicativos.
   3. Procurar por agentBlueprintId.

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

   a365 setup all
   

Permissões da API não concedidas

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

Solução:

1. Abra o Centro de administração do Microsoft Entra.

2. Localize o registro de aplicativo de blueprint do agente.

3. Acesse Permissões da API.

4. Conceder consentimento do administrador:

   1. Selecione Conceder consentimento de administrador para [Seu Locatário].
   2. Confirme a ação.

5. Verifique se todas as permissões mostram marcas de seleção verdes.

A identidade gerenciada não está ativada

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

Solução:

1. Verifique o status da identidade gerenciada usando o comando az webapp identity show ..
2. Se não estiver habilitado, habilite manualmente usando o comando az webapp identity assign ..
3. Verifique se a identidade gerenciada está habilitada usando o comando az webapp identity show ..

# 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 instalação demora muito ou para de responder

Sintoma: o comando de configuração executa por mais de 10 minutos sem terminar.

Solução:

1. Se você estiver executando o programa como Administrador Global, verifique se há alguma janela do navegador aguardando o consentimento do administrador. Complete o fluxo de consentimento para desbloquear a configuração.

2. Se o programa de instalação realmente parar de responder, cancele-o (Ctrl+C) e verifique o que foi criado.

   # Check generated config
   Get-Content a365.generated.config.json | ConvertFrom-Json
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. Limpe tudo e tente novamente.

   a365 cleanup
   a365 setup all
   

Limpar um agente sem configuração

Sintoma: você provisionou um agente com a365 setup all --agent-name <name> e agora quer removê-lo, mas não tem um arquivo a365.config.json.

Solução: use a365 cleanup --agent-name para remover o agente sem um arquivo de configuração. A CLI lê as IDs de recurso da configuração global gerada que foi escrita durante a configuração do bootstrap.

a365 cleanup --agent-name <your-agent-name>

Caso você não tenha mais a configuração global gerada (por exemplo, após reinstalar a CLI), use a365 cleanup com uma configuração mínima criada manualmente a365.config.json, ou remova os recursos diretamente pelo portal do Azure e pelo Centro de administração do Microsoft Entra.

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

Sintoma: após provisionar uma instância de agente, ela não pode enviar uma mensagem para o gerente de agentes como mensagem de boas-vindas.

Solução: é necessária a permissão [Chat.Create][perm-chatcreate] para criar um novo objeto de bate-papo. Se já houver um bate-papo individual, esta operação retorna o bate-papo existente e não cria um novo.

• Para implementar, configure as permissões herdáveis do seu blueprint para incluir o escopo Chat.Create.
• Configure uma mensagem de bate-papo no Teams para ser enviada assim que uma instância de agente for provisionada.
• Crie uma nova instância do agente a partir do blueprint e teste a mensagem de primeira execução.