Configurando a configuração do Agente 365

A CLI do Agent 365 precisa conhecer seu inquilino e outros detalhes para criar os recursos de agente 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 do Microsoft Entra com uma das seguintes funções:
  • Administrador global
  • Administrador de ID de Agente
  • Desenvolvedor de Agente ID

Configure a 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. O CLI fornece um assistente interativo com integração ao Azure CLI e configurações inteligentes para minimizar a entrada manual.

Inicializar configuração

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

a365 config init

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

O assistente gera automaticamente nomes de recursos relacionados (identidade do agente, blueprint, usuário do agente) e valida o tipo de 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

Permissões de blueprint personalizadas

Se o agente precisar de acesso a recursos além do conjunto padrão (Microsoft Graph, API do Bot de Mensagens, API de Observabilidade, Power Platform), declare-os no campo customBlueprintPermissions de a365.config.json:

{
  "customBlueprintPermissions": [
    {
      "resourceAppId": "00000003-0000-0000-c000-000000000000",
      "resourceName": "Microsoft Graph",
      "scopes": ["Mail.Read", "Mail.Send"]
    },
    {
      "resourceAppId": "<your-api-app-id>",
      "resourceName": "My Custom API",
      "scopes": ["MyApi.ReadWrite"]
    }
  ]
}

Depois de adicionar permissões personalizadas a a365.config.json, aplique-as ao seu projeto:

a365 setup permissions custom

Ou inclua-os na configuração completa:

a365 setup all

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",
  "environment": "prod",
  "aiTeammate": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "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 é um GUID válido
✅ clientAppId é um GUID válido (seu registro personalizado de aplicativo cliente)
✅ managerEmail usa seu domínio do 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)

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 comprometido no controle do código-fonte.

Próxima etapa

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

Configuração sem necessidade de configuração com --agent-name

Você pode provisionar agentes (não colegas de IA) sem criar um a365.config.json arquivo. A CLI resolve automaticamente os valores necessários em runtime.

# Provision an Agent without a config file
a365 setup all --agent-name <your-agent-name>

Quando você fornece --agent-name:

• A CLI detecta automaticamente o ID do Tenant de az account show. Substitua-o com --tenant-id <id> , se necessário.
• A CLI localiza um registro do aplicativo Entra chamado Agent 365 CLI no locatário para resolver o aplicativo Cliente. Você não precisa incluir clientAppId na configuração.
• O caminho do projeto de implantação usa como padrão o diretório atual. Execute o comando da pasta de projeto do agente.

Para limpar os recursos provisionados sem um arquivo de configuração:

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

A limpeza lê as IDs de recurso do arquivo de configuração global gerado pela configuração do bootstrap, de modo que a365.config.json não é necessário.

Modos de identidade do agente

O aiTeammate campo controla como as instâncias do agente são provisionadas e qual identidade elas carregam em runtime. Escolha o modo certo com base no que seu agente precisa fazer.

Modo padrão (aiTeammate: false) — padrão

Use este modo quando o agente funcionar como uma integração de serviço ou backend, processando mensagens, respondendo a eventos ou chamando APIs, sem precisar de uma identidade de usuário por instância. Esse modo amplia o intervalo de agentes que você pode criar: qualquer serviço que se comunique com a plataforma agent 365 pode ser registrado como um agente, mesmo que ele não represente um usuário ou participe de experiências de colaboração voltadas para o usuário.

Esse modo é o padrão. Execute a configuração sem opções, ou passe --aiteammate false explicitamente:

# Standard setup (default)
a365 setup all

# Equivalent explicit form
a365 setup all --aiteammate false

Os agentes também dão suporte ao provisionamento sem configuração por meio de --agent-name. Consulte Configuração sem pré-configuração com --agent-name.

Modo de equipe de IA (aiTeammate: true)

Use esse modo quando seu agente precisar atuar como um participante de primeira classe ao lado de usuários humanos , por exemplo, ingressar em reuniões, enviar mensagens em nome de um usuário ou tarefas atribuídas em um fluxo de trabalho. As instâncias do agente provisionadas nesse modo recebem uma identidade de usuário dedicada, permitindo que a plataforma identifique e interaja com cada instância individualmente.

A configuração do colega de equipe de IA ainda requer a365.config.json inicializado com a365 config init. Passe --aiteammate true para selecionar este modo:

a365 setup all --aiteammate true

Resolução de problemas

Use estas etapas para diagnosticar e resolver rapidamente problemas comuns com a a365.config.json e a CLI do Agent 365.

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

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 inicializar a configuração.

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 UPN do agente inválido

Sintoma: a validação falha para o nome UPN 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.