Adicione um único agente com o Agent 365 CLI

Use a CLI do Agente 365 para criar os objetos de identidade Microsoft Entra para um agente e registre-o com o Agente 365. Comece com um agente de não produção para validar a identidade, permissões, consentimento e registro antes de integrar os agentes em massa.

Este artigo utiliza Revisão de Despesa como nome base para um agente padrão que revisa relatórios de despesas em nome de um funcionário registrado. Ele utiliza autenticação on-behalf-of (OBO) e não precisa de conta de usuário Microsoft Entra, caixa de correio ou presença no Teams.

O fluxo de trabalho sem configuração cria:

  • Um blueprint de identidade do agente chamado Blueprint de Revisão de Despesas.
  • Uma identidade de agente chamada Agente de Revisão de Despesas.
  • Concessões de permissão delegada para autenticação OBO.
  • Um registro do Agent 365 para o agente.
  • Um a365.generated.config.json arquivo que registra os identificadores gerados e o status de configuração.

Para uma explicação dos objetos identidade, veja Agent 365 identity.

Prerequisites

Antes de começar, verifique se você tem:

  • Um tenant da Microsoft com o Agente 365 ativado. Use um locatário de não produção ou ambiente de teste para este passo a passo.
  • Uma assinatura do Azure no mesmo tenant.
  • O papel de Contribuinte na assinatura do Azure.
  • É necessária pelo menos a função de Desenvolvedor de ID de Agente no Microsoft Entra ID para criar o blueprint e a identidade do agente.
  • Um Administrador Global disponível para conceder permissões OAuth. Se você ocupar essa função, pode completar o fluxo de trabalho em uma única sessão. Caso contrário, a CLI fornece URLs de consentimento para enviar a um Administrador Global.
  • A função Administrador de Aplicativos ou Administrador Global é necessária se você alterar o cenário para usar a autenticação serviço-a-serviço (S2S).
  • .NET 8.0 ou versão posterior.
  • A CLI do Azure conectada ao locatário e à assinatura que você deseja usar.
  • A CLI do Agent 365.

A configuração do Agent 365 usa o aplicativo empresarial Agent 365 CLI, gerenciado pela Microsoft, quando ele está disponível no seu tenant. Seu ID de aplicação (cliente) é f54280f4-395e-4ea8-9e48-bf2d4952aa14. Se a aplicação não estiver disponível, a CLI procura uma aplicação de propriedade do tenant chamada Agent 365 CLI. Um Administrador Global pode criar e configurar uma aplicação proprietária do locatário a partir do prompt da CLI. Para obter detalhes sobre fallback, consulte Registro de aplicativo cliente personalizado para a CLI do Agent 365.

Note

Esse cenário não cria um usuário agente. Usuários de agentes só são necessários quando um agente precisa de seus próprios recursos licenciados do Microsoft 365, como uma caixa de correio, e estão disponíveis apenas para locatários que participam do programa de pré-visualização Frontier.

Instale a CLI do Agent 365

Instale a CLI como uma ferramenta global .NET:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli

Se a CLI já estiver instalada, atualize-a:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

Verifique a instalação:

a365 --version

Para solução de problemas de instalação e localizações de arquivos suportadas, veja Instalar e usar a CLI do Agente 365.

Selecione o locatário e a assinatura

Entre no Azure:

az login

Liste as assinaturas disponíveis para sua conta:

az account list --output table

Selecione a assinatura no locatário em que você quer adicionar o agente:

az account set --subscription "<subscription-id-or-name>"

Confirme o tenant ativo e a assinatura:

az account show --query "{tenantId:tenantId, subscriptionId:id, subscriptionName:name}" --output table

Registre o ID do inquilino. A CLI detecta isso a partir da conta ativa da CLI do Azure. Você também pode fornecer explicitamente usando --tenant-id.

Valide os pré-requisitos

Execute a verificação de requisitos a partir de qualquer diretório:

a365 setup requirements

O comando verifica autenticação, acesso ao Azure, inscrição do locatário, funções e o aplicativo cliente. Ele continua após uma verificação fracassada, então você pode revisar todos os problemas detectados juntos.

Resolva todas as verificações necessárias que falharam antes de continuar. Se o aplicativo corporativo gerenciado pela Microsoft não estiver disponível, siga o prompt para selecionar ou criar um aplicativo cliente de propriedade do locatário e então execute novamente o comando.

Important

Não modifique o aplicativo CLI Agent 365 gerenciado pela Microsoft. A CLI valida seu service principal e os escopos no seu token de acesso, mas não modifica o registro de aplicativo da Microsoft.

Visualize as mudanças no onboarding

Crie um diretório de trabalho vazio para a configuração gerada e então mude para ele:

New-Item -ItemType Directory -Path .\expense-review-agent
Set-Location .\expense-review-agent

Visualize as alterações sem criar objetos de locatário:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false `
    --dry-run

Revise o ID do locatário, nomes de objetos derivados, aplicativo cliente selecionado, permissões e modo de autenticação. Esse cenário usa o modo padrão obo de autenticação porque o agente atua em nome de um funcionário logado.

Se o inquilino detectado não estiver correto, especifique explicitamente:

a365 setup all `
    --agent-name "Expense Review" `
    --tenant-id "<tenant-id>" `
    --aiteammate false `
    --dry-run

Integrar o agente

Execute o mesmo comando sem --dry-run:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false

A CLI valida novamente os requisitos, cria o blueprint e a identidade do agente, configura as permissões delegadas, registra o agente e escreve a365.generated.config.json.

Se você fizer login como Administrador Global, complete qualquer pedido de consentimento que abrir durante a configuração. Se você usar as funções de Desenvolvedor de ID do Agente ou de Administrador de ID do Agente, a CLI conclui as etapas permitidas pela sua função e imprime as ações de consentimento para um Administrador Global. Envie as URLs de consentimento geradas para o Administrador Global e peça que ele conclua todos os consentimentos.

Note

A configuração sem necessidade de configuração assume que o agente está hospedado externamente. Ele não cria recursos de hospedagem no Azure nem atualiza um projeto de agente.

Verifique o resultado do onboarding

Revise o resumo da configuração. Cada etapa necessária deve aparecer como concluída. Se um Administrador Global ainda precisar conceder consentimento, complete essa transferência antes de considerar a integração concluída.

Inspecione a configuração gerada:

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

Confirme que a saída contém:

  • Um ID do blueprint do agente.
  • Um status de configuração concluída, sem ações de consentimento pendentes.

Confirme se o resumo de configuração reporta a criação bem-sucedida da identidade do agente e o registro do agente.

Depois, verifique a inscrição no centro de administração do Microsoft 365:

  1. Acesse o Centro de administração do Microsoft 365..
  2. Selecionar Agentes>Todos os Agentes.
  3. Encontre um Agente de Revisão de Despesas.
  4. Abra o agente e confirme se seus dados de identidade e registro correspondem à configuração gerada.

Solucionar problemas de integração

Sintoma Resolução
A verificação de requisitos reporta o locatário ou assinatura errada. Execute az account set --subscription "<subscription-id-or-name>", verifique o resultado com az account show, e reexecute a verificação de requisitos. Como alternativa, forneça --tenant-id a a365 setup all.
O aplicativo CLI Agent 365 gerenciado pela Microsoft não foi encontrado. Atualize a CLI e execute a365 setup requirementsnovamente. Se a implementação em etapas ainda não chegou ao seu locatário, use um aplicativo cliente próprio do locatário.
A configuração informa que está faltando uma função. Atribua as funções de Colaborador e Desenvolvedor de ID do Agente ao operador. Aguarde um tempo para que as atribuições sejam propagadas, faça login novamente e execute novamente a verificação de requisitos.
A configuração foi concluída, mas lista as ações de consentimento pendentes. Peça a um Administrador Global para abrir todas as URL de consentimento impressas pela CLI e conceder as permissões solicitadas.
O blueprint ou identidade existe, mas o agente não está em Todos os Agentes. Revise o resumo de configuração para uma falha no registro do agente. Depois de resolver o erro, execute novamente a365 setup all --agent-name "Expense Review" --agent-registration-only.
A configuração selecionou o padrão de autenticação errado. Use o modo OBO padrão quando o agente atua para um usuário conectado. Use --authmode s2s para trabalho em segundo plano ou --authmode both quando ambos os padrões forem necessários. As concessões S2S exigem Administrador de Aplicativos ou Administrador Global.

Para resoluções mais específicas para CLI, veja Agent 365 solução de problemas.

Próximas Etapas 

  • Última atualização em