Modelo 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
     • Desenvolvedor de Agente ID
   • Acesso a uma assinatura Azure com permissões para criar recursos

   Tip

   Os agentes (não os colegas de IA) não precisam de um arquivo de configuração. Use 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 a365.config.json.

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.

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 do companheiro de equipe de IA:

a365 setup all --aiteammate

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 tenant Microsoft Entra
   • Cria os registros de aplicativos 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 projetos devem ter managerApplications configurado para serem aceitos pela plataforma. A CLI define isso automaticamente. Se você tiver um blueprint existente criado antes de esse requisito ser introduzido, exclua-o e execute a365 setup all novamente ou corrija-o manualmente por meio do API do Graph.

3. Configurar permissões de API:

   • Configura os escopos do Microsoft API do Graph
   • 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

Configuração usando o Desenvolvedor de ID de Agente

Se você executar como Desenvolvedor de ID do Agente (não Administrador Global), a365 setup all concluirá a maioria das etapas automaticamente, mas as concessões de permissão OAuth2 exigirão uma etapa de Administrador Global separada.

Quais etapas são concluídas automaticamente:

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

Quais etapas exigem um Administrador Global:

• Concessões delegadas de permissão OAuth2 (consentimento AllPrincipals) para Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API e Power Platform API

Como concluir a instalação usando uma conta não administradora:

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 impressas pela CLI com o Administrador Global. Eles podem abrir o link fornecido ou a URL de consentimento para concluir as concessões do OAuth2.

Verificar configuração

Quando a instalaçã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 em seu diretório de trabalho. Ou usar o PowerShell:

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

   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",
   "messagingEndpoint": "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	Finalidade	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
   messagingEndpoint	Roteamento de mensagens	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

   Note

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

2. Verifique recursos do Azure em portal do Azure:

   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>Aplicativos Web
     • 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. Verificar aplicativos do Microsoft Entra no portal do Azure:

   Vá para Azure Active Directory>Registros de aplicativo>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:

   Você deve ter um arquivo nomeado a365.generated.config.json que contenha todos os dados de configuração.

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

   # 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 esquema do Agente registrado no Microsoft Entra:

   Em centro de administração do Microsoft Entra, faça uma busca pelo seu agentBlueprintId ou 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 com aplicativos clientes personalizados

Permissões de agente

Antes que aplicativos e agentes possam ler ou gravar dados do Microsoft 365 (usuários, emails, arquivos, Teams, agentes e assim por diante), você deve conceder permissões explicitamente ao 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 Microsoft Entra ID.

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

Para usar permissões do Graph para instâncias de agente do Agente 365, o desenvolvedor deve declará-las no blueprint do agente. Quando um administrador ativa o modelo no Centro de Administração do Microsoft 365, o portal analisa as permissões do Graph do modelo e solicita que o administrador consinta com elas.

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

• Exiba todas as permissões do Graph disponíveis.
• Visite o Explorador do Graph para experimentar consultas, inspecionar 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 modelo

Use a365 setup permissions custom para aplicar permissões de API personalizadas diretamente no 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:

Solucionando problemas

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

Às vezes, esses problemas ocorrem durante o registro:

• Erro de permissões insuficientes
• Autenticação do 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
• Modelo de agente não registrado no Microsoft Entra
• Permissões da API não concedidas
• Identidade gerenciada não habilitada
• A instalação leva muito tempo 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 a365 setup execução do comando .

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

• Administrador global
• Desenvolvedor de Agente ID

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

Solução: Verifique se você tem 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 PowerShell

Falta autenticação da CLI do Azure

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 instalação falha com Resource already exists o erro do grupo de recursos, do plano do Serviço de Aplicativo ou do Aplicativo Web.

Soluções: Escolha uma das soluções a seguir.

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

  Use 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, use o a365 setup all comando para executar novamente a instalaçã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 instalação, mas as fechou sem concluir o consentimento ou a instalação concluída, mas as concessões de permissão OAuth2 ainda estão pendentes.

Solução: Escolha com base em sua função:

• Administrador global: executar a365 setup all novamente. A CLI solicita consentimento do administrador. Conclua o fluxo de consentimento na janela do navegador exibida.

• 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 o 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.

Solution:

1. Verifique se o a365.config.json arquivo existe.
2. Se estiver ausente ou inválido, crie-o manualmente ou use a365 setup all --agent-name <name> (somente 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 bem-sucedido, mas os recursos do Azure não existem.

Solution:

1. Verifique os recursos criados abrindo a365.generated.config.json em seu diretório de trabalho.
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 a instalação usando o a365 setup all comando.

# 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

Configuração do agente não registrada no Microsoft Entra

Sintoma: A instalação é concluída, mas você não consegue encontrar o blueprint do agente no Centro de administração do Microsoft Entra.

Solution:

1. Obtenha a ID do plano de a365.generated.config.json.

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

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

   1. Acesse o Centro de Administração do Microsoft Entra.
   2. Navegue até registros de aplicativo>todos os 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 instalação é concluída, mas as permissões são mostradas como "Não concedidas" no Microsoft Entra.

Solution:

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

2. Localize o registro do aplicativo Blueprint do agente.

3. Acesse Permissões da 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 mostram marcas de seleçã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 da identidade gerenciada usando o az webapp identity show comando.
2. Se não estiver habilitado, habilite-o manualmente usando o az webapp identity assign comando.
3. Verifique se ele está habilitado 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 instalação leva muito tempo ou para de responder

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

Solution:

1. Se você estiver executando como Administrador Global, verifique se uma janela do navegador está aguardando o consentimento do administrador. Conclua o fluxo de consentimento para desbloquear a instalação.

2. Se a configuração realmente parar de responder, cancele-a (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 e tente novamente.

   a365 cleanup
   a365 setup all
   

Limpar um agente sem necessidade de configuração

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

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>

Se você não tiver mais a configuração global gerada (por exemplo, após reinstalar a CLI), use a365 cleanup com um a365.config.json mínimo criado manualmente ou remova os recursos diretamente via Portal do Azure e Centro de Administração Microsoft Entra.

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

Sintoma: Depois de provisionar uma instância de agente, ela não poderá 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.