Blueprint do agente e configuração da instância

O fluxo de autenticação agential permite que um agente atue com a sua própria identidade. Neste fluxo:

• O agente autentica-se usando as suas próprias credenciais (credenciais do projeto do agente)
• O agente opera de forma independente com as suas próprias permissões atribuídas
• O agente tem a sua própria identidade, separada de qualquer utilizador
• Este fluxo é ideal para operações autónomas de agentes que não requerem contexto do utilizador

Casos de uso:

• Operações de agentes autónomos (tarefas agendadas, monitorização)
• Enviar emails ou marcar reuniões a partir da caixa de correio do agente
• Criação e gestão de recursos detidos por agentes
• Processamento em segundo plano sem interação do utilizador

Crie a sua identidade agente

Para desenvolver e testar o seu agente com autenticação agente, precisa de criar a identidade do agente e registá-la no Microsoft 365. Esta identidade permite-lhe testar as capacidades do seu agente, como ferramentas, observabilidade e notificações à medida que as constrói.

O processo de criação de agentes envolve três passos principais:

1. Configurar - Inicializar a configuração da CLI do Agente 365
2. Configuração - Criar recursos Azure e agente blueprint
3. Criar instância - Criar ID de aplicação agente e utilizador

Pré-requisitos

Antes de começar, confirme que tem o seguinte:

• CLI do Agente 365 - Ver instalação do CLI do Agente 365

Permissões obrigatórias:

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

Passo 4: Configurar o agente

O a365 config init comando cria a365.config.json, o ficheiro central de configuração utilizado por todos os comandos CLI do Agente 365. A CLI fornece um assistente interativo com integração Azure CLI e predefinições inteligentes para minimizar a entrada manual.

Autenticar com o Azure AD

Antes de inicializar a configuração, autentique com o Azure usando o az login comando:

az login

Selecione a subscrição e o projeto apropriados. O assistente de configuração utiliza o Azure CLI para consultar subscrições disponíveis, grupos de recursos e planos de serviços de aplicação.

Inicializar; Base; Configuração

Execute o seguinte comando para iniciar o assistente de configuração interativa:

a365 config init

O assistente usa integração com Azure CLI e predefinidos inteligentes para minimizar a entrada manual. Serás solicitado para:

O assistente gera automaticamente nomes de recursos relacionados, identidades e valida o tipo do seu projeto.

Limitação de disponibilidade

Neste momento, as únicas regiões Azure suportadas são:

• centralindia
• westeurope
• westus

Se selecionar uma região diferente, ou se editar manualmente a location propriedade no a365.config.json ficheiro, verá o seguinte erro ao tentar criar um blueprint de agente.

The selected region ('{location}') is not supported by the Agent 365 CLI. Choose a supported region and ensure your web app name ('{webAppName}') is globally unique

Saiba mais sobre a estrutura de ficheiros de configuração

Verificar a configuração da regra

Use o a365 config display comando para mostrar a sua configuração e verificar se todos os valores estão corretos:

a365 config display

Passo 2: Criar o plano do agente

O a365 setup comando cria recursos Azure e regista o seu blueprint do agente. O blueprint define a identidade, as permissões e os requisitos de infraestrutura do seu agente. Este passo estabelece a base para implementar e executar o seu agente no Azure.

Executar a Configuração

Execute o comando: .

a365 setup

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

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

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

2. Plano do agente de registos:

   • Cria o blueprint do agente no seu tenant Microsoft Entra
   • Cria registos de aplicações Microsoft Entra
   • Configura a identidade do agente com as permissões necessárias

3. Configurar permissões API

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

4. Ficheiros de configuração de atualizações:

   • Guarda IDs gerados e endpoints para a365.generated.config.json
   • Informação de identidade e recursos gerida por registos

Verificar configuração

Depois de a configuração ser concluída com sucesso, deverá ver um resumo com todos os passos concluídos. Verifique os recursos criados:

1. Configuração gerada pela visualização:

   a365 config display -g
   

   Confirme que estes valores estão presentes:

   • agentBlueprintId - ID de aplicação do seu projeto do agente
   • agentBlueprintObjectId - ID Microsoft Entra da Blueprint
   • managedIdentityPrincipalId - ID principal de identidade gerida atribuído pelo sistema

2. Review Azure Resources in Azure Portal:

   Verifique se foram criados os seguintes recursos:

   • Grupo de Recursos:

     • Aceda ao Grupos de recursos e selecione o grupo de recursos relevante.
     • Verifique se contém o seu Plano de Serviço de Aplicações e a Aplicação Web

   • Plano do Serviço de Aplicações

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

   • Aplicação Web

     • Ir a Serviços>de Aplicações Web
     • Encontre a sua aplicação web e depois vá a Definições>Sistema de Identidade>atribuído
     • Verificar o estado está Ligado
     • Note que o ID do Objeto (principal) corresponde managedIdentityPrincipalId

3. Verificar as aplicações Microsoft Entra no Azure Portal:

   Aceda a Azure Active DirectoryRegistos de aplicações.

   • Procure o seu projeto de agente através do agentBlueprintId
   • Abra a aplicação e selecione permissões API
   • As permissões de verificação são concedidas com marcas verdes:
     • Microsoft Graph (permissões delegadas e de aplicação)
     • Permissões da API de bots de mensagens
   • Todas as permissões devem mostrar "Concedidas para [O Seu Inquilino]"

Passo 3: Criar instância de agente

O a365 create-instance comando cria o ID da aplicação agente e o utilizador agente para o blueprint do seu agente, permitindo autenticação e permissões. Isto cria uma instância específica do seu agente com a sua própria identidade e credenciais, permitindo-lhe autenticar-se e operar dentro do seu ambiente Microsoft 365.

Criar instância

Execute o seguinte comando:

a365 create-instance

O que faz:

1. Cria ID de aplicação agente - ID Microsoft Entra para esta instância de agente
2. Cria utilizador agente - Principal de serviço para a instância do agente
3. Usa o ID do blueprint do agente - A partir da configuração gerada (a365.generated.config.json)
4. Concede consentimento de administrador - Aplica automaticamente permissões herdadas do blueprint
5. Atualiza a configuração - Guarda novas credenciais agentes no ambiente local

Saída Esperada:

Verá mensagens de progresso para cada fase:

• Fase 1: Criação da Identidade do Agente e do Utilizador do Agente
• Pedidos de consentimento do administrador (janelas do navegador vão abrir)
• Fase 2: Atribuição da licença
• Configuração Atualizada

Verificar instância

1. Configuração gerada pela visualização:

   a365 config display -g
   

   Verifique a presença dos seguintes valores:

   • AgenticAppId - ID da aplicação da instância do seu agente
   • AgenticUserId - ID de utilizador do seu agente

2. Valide no Azure Portal:

   • Aceda a Azure Active Directory>Registos de aplicações.
   • Encontra o ID da tua aplicação agente (verifica a configuração gerada para o ID)
   • Verificar que as permissões da API são concedidas e consentidas

Próximos passos

A identidade do seu agente está agora registada e pronta. Seguinte:

1. Adicionar capacidades de ferramentas - Ativar ferramentas do Microsoft 365 (recomendado para testar autenticação)
2. Teste o seu agente - Valide com o Agent Playground