Configurando a configuração do Agente 365

A CLI do Agent 365 precisa conhecer seu tenant, assinatura e outros detalhes para criar os recursos necessários, como o Agent Blueprint. A CLI armazena essas informações em um arquivo central de configuração chamado a365.config.json no seu diretório de trabalho. Todos os comandos da CLI usam este arquivo de configuração.

Pré-requisitos

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

• CLI do Agente 365 - Veja instalação do CLI do Agente 365.

Permissões necessárias:

• Usuário válido do locatário Microsoft Entra 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

Configure o CLI do Agent 365

O a365 config init comando cria a365.config.json, o arquivo central de configuração usado por todos os comandos CLI do Agente 365, no seu diretório de trabalho. A CLI fornece um assistente interativo com integração ao Azure CLI e padrões inteligentes para minimizar a entrada manual.

Autenticar com Azure

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

az login

Selecione a assinatura apropriada quando solicitado. O assistente de configuração usa Azure CLI para consultar assinaturas disponíveis, grupos de recursos e planos do serviço de aplicativo. Para uma experiência de desenvolvimento mais tranquila, configure sua conta de usuário de locatário com o papel e as permissões corretas, assinatura e plano de serviço de aplicativo antes de começar.

Inicializar configuração

Execute o a365 config init comando para iniciar o assistente de configuração interativo:

a365 config init

O assistente usa integração com Azure CLI e configurações padrão inteligentes para minimizar a entrada manual. Você está sendo solicitado a:

O assistente gera automaticamente nomes de recursos relacionados (aplicativo web, identidade de agente, blueprint, usuário de agente) e valida o tipo do seu projeto. Antes de salvar, você pode opcionalmente configurar permissões de blueprint personalizadas para recursos externos (como a presença do Teams ou arquivos OneDrive) e personalizar qualquer um dos nomes gerados.

Saiba mais sobre a estrutura do arquivo de configuração

Verificar arquivos de configuração do Agente 365

O Agente 365 utiliza múltiplos arquivos de configuração ao longo do ciclo de vida do desenvolvimento:

Após concluir a configuração, verifique se você possui os seguintes itens:

Verificar a criação do a365.config.json arquivo

Verifique visualmente se o a365.config.json arquivo existe. Ou use o comando PowerShell Test-Path em um script para automatizar essa verificação.

# Check file exists in current working directory
Test-Path a365.config.json
# Should return: True

Verificar a365.config.json dados de configuração

Execute o a365 config display comando para visualizar a configuração atual da CLI do Agente 365.

a365 config display

A saída desse comando é a seguinte:

{
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "resourceGroup": "your-resource-group",
  "location": "location-of-your-azure-resources",
  "environment": "prod",
  "needDeployment": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "appServicePlanName": "your-app-service-plan",
  "appServicePlanSku": "service-plan-sku",
  "webAppName": "your-web-app",
  "agentIdentityDisplayName": "your-agent-name Identity",
  "agentBlueprintDisplayName": "your-agent-name Blueprint",
  "agentUserPrincipalName": "youragent@yourtenant.onmicrosoft.com",
  "agentUserDisplayName": "your-agent-name Agent User",
  "managerEmail": "manager@yourtenant.com",
  "agentUserUsageLocation": "usage-location",
  "deploymentProjectPath": "C:\\path\\to\\your\\project",
  "agentDescription": "your-agent-name - Agent 365 Agent"
}

Lista de verificação

✅ Todos os campos têm valores válidos (sem cadeias vazias ou nulos)
✅ tenantId e subscriptionId são GUIDs válidos
✅ clientAppId é um GUID válido (seu registro personalizado de aplicativo cliente)
✅ resourceGroup e appServicePlanName existem em sua assinatura Azure
✅ managerEmail Usa seu domínio de locatário
✅ deploymentProjectPath aponta para o diretório do seu código de agente
✅ agentUserPrincipalName segue o formato agentname@tenant.com
✅ environment é definido (tipicamente prod)
✅ needDeployment é true para a configuração inicial. Se você não precisa de implantação, aprenda a configurar um endpoint de mensagens de agente.

Se sua configuração não corresponder ao resultado esperado, veja a seção de Solução de Problemas para soluções detalhadas.

Adicione a365.generated.config.json ao arquivo .gitignore. Esse arquivo contém segredos gerados e nunca deve ser commitado no controle de versão.

Próxima etapa

Se tudo estiver certo, você está pronto para prosseguir.

Resolução de problemas

Use esses passos para diagnosticar e resolver rapidamente problemas comuns com a a365.config.json e o Agente 365 CLI.

• O arquivo de configuração não existe
• Valores de configuração ausentes ou inválidos
• Locatário inválido ou assinatura inválida
• Falha na validação do aplicativo cliente personalizado
• Nome principal do usuário do agente inválido
• Nome do aplicativo Web já usado

O arquivo de configuração não existe

Sintoma: Os comandos CLI falham com "Configuração não encontrada" ou Test-Path a365.config.json retornam False.

Solução: Crie um novo a365.config.json arquivo.

Conclua as etapas para Authenticate com Azure e Initialize configuration.

Valores de configuração ausentes ou inválidos

Sintoma: O arquivo de configuração existe, mas possui campos vazios ou erros de validação.

Solução: Siga os passos para verificar a365.config.json os dados de configuração.

Se algum campo estiver incorreto:

• Opção 1: Reexecute o mago usando o a365 config init comando.
• Opção 2: Edite a365.config.json manualmente com os valores corretos.

Locatário ou assinatura inválidos

Sintoma: A CLI falha com erros de autenticação ou autorização.

Solution:

Use esses comandos para autenticar novamente com Azure, verificar a conta de entrada, alternar para a assinatura correta e reinicializar a configuração da CLI do Agent 365.

# Re-authenticate with Azure
az login

# Verify you're logged into the correct account
az account show

# If needed, switch to the correct subscription
az account set --subscription "<subscription-name-or-id>"

# Re-initialize configuration
a365 config init

Falha na validação do aplicativo cliente personalizado

Sintoma: O assistente de configuração falha ao validar o ID personalizado do aplicativo cliente.

Solução: Revise o registro personalizado do seu aplicativo cliente para garantir que o registro do aplicativo tenha todas as permissões necessárias e consentimento do administrador.

Nome principal do usuário do agente inválido

Sintoma: A validação falha para o nome principal do agente durante a configuração.

Solução: Verifique se o UPN segue o formato username@domain. Por exemplo, demo.agent@contoso.onmicrosoft.com. Um sufixo de domínio ausente é a causa mais comum.

Nome do aplicativo Web já usado

Sintoma: A instalação falha porque o nome do aplicativo Web já está em uso.

Solution: nomes de aplicativos Web devem ser globalmente exclusivos em Azure. Atualize webAppName em a365.config.json para um valor exclusivo ou execute a365 config init novamente para gerar um novo nome.