Configurar Blueprint do agente

O esquema de agente define a identidade, as permissões e os requisitos de infraestrutura do seu agente. Crie todas as instâncias de agente a partir deste esquema de agente.

Nota

A configuração de um esquema de agente é necessária para ativar as capacidades de Registo, Work IQ e colegas de equipa de IA. Consulte Começar com o desenvolvimento do Agent 365 para compreender quais capacidades se aplicam ao seu agente.

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

Pré-requisitos

Antes de começar, certifique-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:

    • Utilizador válido do inquilino com uma das seguintes funções:
      • Administrador Global
      • Programador de ID do Agente
    • Acesso a uma subscrição do Azure com permissões para criar recursos

    Sugestão

    Os agentes (não os colegas de equipa de IA) não precisam de um ficheiro de configuração. Utilize a365 setup all --agent-name <name> e a CLI resolve automaticamente o seu inquilino e a aplicação cliente. A configuração de um colega de equipa de IA requer a criação manual de a365.config.json.

Criar esquema de agente

Utilize o comando a365 setup para criar recursos do Azure e registar o esquema de agente. O esquema define a identidade, as permissões e os requisitos de infraestrutura do seu agente. Este passo constitui a base para a implementação e execução do seu agente no Azure.

Executar a configuração

Executar o comando de configuração:

a365 setup -h

O comando tem várias opções. Pode realizar toda a configuração com um único comando utilizando a365 setup all ou escolher opções mais granulares.

Nota

a365 setup all tem como predefinição o modo de agente do esquema. Para configurar um agente de um colega de equipa de IA, transmita --aiteammate. Para agentes M365 (Teams, Copilot), também transmita --m365 para registar automaticamente o ponto final de mensagens.

Configuração do agente (predefiniçã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 de colega de equipa de IA:

a365 setup all --aiteammate

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

  1. Cria a infraestrutura do Azure (caso ainda não exista):

    • Grupo de recursos
    • Plano do Serviço de Aplicações com SKU especificado
    • Aplicação Web do Azure com identidade gerida ativada

  2. Regista o esquema do agente:

    • Cria o esquema do agente no seu inquilino do Microsoft Entra
    • Cria registos de aplicações do Microsoft Entra
    • Configura a identidade do agente com as permissões necessárias
    • Define managerApplications no esquema, que é necessário para a gestão da plataforma

    Importante

    Os esquemas devem ter managerApplications definido para serem aceites pela plataforma. A CLI define isto automaticamente. Se tiver um esquema existente criado antes de este requisito ter sido introduzido, elimine-o e execute novamente o a365 setup all, ou corrija-o manualmente através do Graph API.

  3. Configura as permissões da API:

    • Configura os âmbitos do Microsoft Graph API
    • Configura as permissões da API do Bot de Mensagens
    • Aplica permissões herdáveis para instâncias de agente

  4. Atualiza os ficheiros de configuração:

    • Guarda os IDs e os pontos finais gerados num novo ficheiro no seu diretório de trabalho chamado a365.generated.config.json
    • Regista informações sobre identidades geridas e recursos

Nota

A configuração normalmente leva 3 a 5 minutos e guarda automaticamente a configuração em a365.generated.config.json. Se correr como Administrador Global, a CLI pode abrir uma janela do browser para consentimento do administrador – conclua o fluxo de consentimento para prosseguir. Se executar como Programador de ID do Agente, não aparece nenhuma janela do browser; a CLI gera URLs de consentimento para um Administrador Global concluir mais tarde.

Configuração utilizando o Programador de ID do Agente

Se estiver a executar como Programador de ID do Agente (e não como Administrador Global), a365 setup all conclui automaticamente a maioria dos passos, mas as concessões de permissões OAuth2 requerem um passo separado realizado por um Administrador Global.

Quais passos são concluídos automaticamente:

  • Infraestrutura do Azure (grupo de recursos, Plano do Serviço de Aplicações, Aplicação Web)
  • Registo do esquema do agente
  • Permissões herdáveis para instâncias de agente

Que passos exigem um Administrador Global:

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

Como concluir a configuração utilizando uma conta não administrativa:

Passo Quem Ação
1 Programador Execute o a365 setup all. A CLI conclui todos os passos que consegue e apresenta os próximos passos, incluindo um URL de consentimento para que um Administrador Global o possa abrir.
2 Programador Partilhe o URL de consentimento gerado pela CLI com o seu Administrador Global.
3 Administrador Global Abra o URL de consentimento num browser iniciado como Administrador Global e conceda as permissões pedidas.

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

Partilhe os próximos passos apresentados pela CLI com o seu Administrador Global. Pode abrir a ligação fornecida ou o URL de consentimento para concluir as concessões OAuth2.

Verificar a configuração

Quando a configuração termina, será apresentado um resumo que mostra todos os passos concluídos. Verifique os recursos criados:

  1. Verifique a configuração gerada:

    Abra a365.generated.config.json no seu diretório de trabalho. Ou utilize 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 chave a verificar:

    Campo Finalidade O Que Verificar
    managedIdentityPrincipalId Autenticação de identidade gerida do Azure Deve ser um GUID válido
    agentBlueprintId Identificador exclusivo do seu agente Utilizado no Portal do Programador e no centro de administração
    agentBlueprintObjectId Microsoft Entra ID do Esquema
    messagingEndpoint Encaminhamento de mensagens Onde o Teams e o Outlook enviam mensagens para o seu agente
    agentBlueprintClientSecret Segredo de autenticação Deve existir (o valor é mascarado)
    resourceConsents Permissões de API Deve conter recursos como o Microsoft Graph, as Ferramentas do Agent 365, a API do Bot de Mensagens, a API de Observabilidade
    completed Estado da configuração Deve ser true

    Nota

    Caso tenha executado a configuração como Administrador de ID do Agente ou Programador de ID do Agente, resourceConsents pode estar vazio e completed pode ser false até que um Administrador Global conclua as concessões de permissões OAuth2 utilizando os próximos passos impressos pela CLI.

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

    Ou utilize o comando do PowerShell az resource list.

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

      • Aceda a Grupos de Recursos> e selecione o seu grupo de recursos
      • Verifique se contém o seu Plano do Serviço de Aplicações e a sua Aplicação Web

    • Plano do Serviço de Aplicações:

      • Aceda a Serviços de Aplicações>Planos do Serviço de Aplicações
      • Encontre o seu plano e verifique se o escalão de preço corresponde ao seu SKU de configuração

    • Aplicação Web:

      • Aceda a Serviços de Aplicações>Aplicações Web
      • Encontre a sua aplicação Web, em seguida, vá para Definições>Identidade>Atribuída pelo sistema
      • Verifique se o estado está Ativado
      • Tenha em atenção que o ID do Objeto (principal) corresponde a managedIdentityPrincipalId

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

    Vá para Azure Active Directory>Registos de aplicações>Todas as aplicações:

    • Procure o seu esquema do agente pelo agentBlueprintId

    • Abra a aplicação e selecione permissões da API

    • Verifique se as permissões foram concedidas e estão assinaladas com marcas de verificação verdes:

      • Microsoft Graph (permissões delegadas e de aplicação)
      • Permissões da API de Bots de Mensagens

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

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

    Deve existir um ficheiro chamado a365.generated.config.json que contenha todos os dados de configuração.

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

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

    Importante

    Guarde ambos os ficheiros a365.config.json e a365.generated.config.json. São necessários estes valores para implementação e resolver problemas.

  5. Verifique se a Aplicação Web tem a identidade gerida ativada:

    Use o comando az webapp identity show para verificar se a identidade gerida 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 se o esquema do Agente está registado no Microsoft Entra:

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

    Verifique que:

    ✅ O Registo de Aplicação e a Aplicação Empresarial aparecem
    ✅ No esquema de registo da aplicação, o separador Permissões da API mostra todas as permissões
    ✅ O estado indica "Concedido ao [Seu inquilino]"

Para mais ajuda, consulte:

Permissões do agente

Antes de as aplicações e os agentes poderem ler ou escrever dados do Microsoft 365 (utilizadores, e-mail, ficheiros, Teams, agentes, etc.), deve conceder-lhes explicitamente permissões do Microsoft Graph. As permissões do Microsoft Graph são o modelo de autorização que controla a que dados e ações uma aplicação ou serviço pode aceder através das APIs do Microsoft Graph em todo o Microsoft 365 e Microsoft Entra ID.

Mais informações: Descrição geral das permissões do Microsoft Graph

Para utilizar as permissões do Graph nas instâncias do Agent 365, o programador deve declará-las no esquema do agente. Quando um administrador ativa o esquema no centro de administração do Microsoft 365, o portal revê as permissões do Graph do esquema e faz pedidos ao administrador para que consinta com as mesmas.

Para compreender e validar como as permissões do Graph ativam o seu agente, pode:

Aplicar permissões ao seu esquema

Utilize a365 setup permissions custom para aplicar permissões personalizadas de API diretamente ao seu esquema 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 informações completas sobre como configurar e remover permissões personalizadas, consulte setup permissions custom.

Passos seguintes

Implemente o código do seu agente na cloud:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Publicar o agente no centro de administração da Microsoft

Resolução de Problemas

Esta secção descreve problemas comuns durante a configuração de esquemas de agentes.

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de alto nível, melhores práticas e ligações para conteúdo de resolução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

Estes problemas podem ocorrer durante o registo:

Erro de permissões insuficientes

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

Precisa de uma das seguintes funções no seu inquilino do Microsoft Entra:

  • Administrador Global
  • Programador de ID do Agente

E acesso a contribuidores ou proprietários de subscrição do Azure.

Solução: verifique se dispõe das permissões necessárias no Microsoft Entra.

Nota

Se tiver a função de Administrador de ID do Agente ou Programador de ID do Agente (e não de Administrador Global), a365 setup all ainda assim será concluído com sucesso, mas irá ignorar as concessões de permissões OAuth2. Após a conclusão da configuração, a CLI imprime os próximos passos para que um Administrador Global conclua as concessões de permissões restantes. Este fluxo de trabalho é esperado para as organizações onde o programador do agente e o Administrador Global são pessoas diferentes.

Falta de autenticação da CLI do Azure

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

Solução: certifique-se de que está ligado ao Azure e verifique a sua conta e subscrição.

# 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 relativo ao grupo de recursos, ao Plano do Serviço de Aplicações ou à Aplicação Web.

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

  • Utilizar recursos existentes

    Se os recursos existirem e pretender utilizá-los, certifique-se de que estão em conformidade com a sua configuração. Utilize o comando do PowerShell az resource list.

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

  • Eliminar recursos em conflito

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

    Utilize o comando do PowerShell az group delete para eliminar 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 cleanupcomando para remover todos os recursos do Agent 365, em seguida, use o comando a365 setup all para executar novamente a configuração.

    Aviso

    A execução de a365 cleanup é destrutiva.

    a365 cleanup
a365 setup all

Sintoma: abriu janelas do browser durante a configuração, mas fechou-as antes de conceder o consentimento, ou a configuração foi concluída mas as concessões de permissões OAuth2 ainda estão pendentes.

Solução: escolha de acordo com a sua função:

  • Administrador Global: execute a365 setup all novamente. A CLI pede o consentimento do administrador. Conclua o fluxo de consentimento na janela do browser que aparece.

  • Programador ou Administrador de ID do Agente: não pode concluir as concessões do OAuth2 diretamente. Execute a365 setup all — o resumo da configuração imprime os próximos passos para um Administrador Global, incluindo uma ligação direta ou URL de consentimento para concluir as concessões. Partilhe esses detalhes com o seu Administrador Global.

Ficheiros de configuração inválidos ou em falta

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

Solução:

  1. Certifique-se de que o ficheiro a365.config.json existe.
  2. Se estiver em falta ou inválido, crie-o manualmente ou utilize a365 setup all --agent-name <name> (apenas para agentes).
# Verify a365.config.json exists
Test-Path a365.config.json

A configuração é concluída, mas os recursos não são 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 utilizando o comando az resource list.
  3. Se faltarem recursos, verifique se há erros na saída da configuração e reexecute a configuração utilizando 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

O esquema do agente não está registado no Microsoft Entra

Sintoma: a configuração foi concluída, mas não é possível encontrar o esquema do agente no centro de administração Microsoft Entra.

Solução:

  1. Obtenha um ID do esquema do a365.generated.config.json.

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

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

    1. Aceda ao: centro de administração Microsoft Entra.
    2. Aceda a Registos de aplicações>Todas as aplicações.
    3. Procure o seu agentBlueprintId.

  3. Se não for encontrado, reexecute a configuração utilizando o comando a365 setup all.

    a365 setup all

Permissões de 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 Microsoft Entra.

  2. Localize o registo da aplicação do esquema do agente.

  3. Aceda a Permissões da API.

  4. Conceder consentimento do administrador:

    1. Selecione Conceder consentimento do administrador ao [Seu Inquilino].
    2. Confirme a ação.

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

Identidade gerida não ativada

Sintoma: existe uma aplicação Web, mas a identidade gerida não está ativada.

Solução:

  1. Utilize o comando az webapp identity show para verificar o estado da identidade gerida.
  2. Se não estiver ativado, ative-o manualmente utilizando o comando az webapp identity assign.
  3. Verifique se está ativado utilizando 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 configuração demora demasiado tempo ou deixa de responder

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

Solução:

  1. Se estiver a executar como Administrador Global, verifique se uma janela do browser está à espera de consentimento do administrador. Conclua o fluxo de consentimento para desbloquear a configuração.

  2. Se a configuração realmente deixar 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 configuração

Sintoma: aprovisionou um agente com a365 setup all --agent-name <name> e agora pretende removê-lo, mas não tem um ficheiro de a365.config.json.

Solução: utilize a365 cleanup --agent-name para remover o agente sem um ficheiro de configuração. A CLI lê os IDs de recursos a partir da configuração global gerada, criada durante a configuração de bootstrap.

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

Sugestão

Se o comando parar na autenticação, recorre automaticamente ao fluxo de código do dispositivo. Siga as instruções impressas no terminal para concluir o início de sessão.

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

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

Sintoma: após o aprovisionamento de uma instância de agente, esta não consegue enviar uma mensagem de boas-vindas ao gestor de agentes.

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

  • Para implementar, configure as permissões hereditárias do seu esquema para incluir o âmbito Chat.Create.
  • Configure uma mensagem de chat do Teams para ser enviada assim que uma instância de agente for aprovisionada.
  • Crie uma nova instância de agente com base no esquema e teste a mensagem inicial.
  • Last updated on