Instale e use a CLI do Agent 365

A CLI do Agente 365 é uma ferramenta de linha de comando multiplataforma para implantar e gerenciar aplicações do Agente 365 no Azure. Esta referência explica como instalar, atualizar, desinstalar e usar a CLI para automação e solução de problemas.

Você não precisa instalar a CLI manualmente.O Agente 365 Skills verifica a linha de código, instala ou atualiza automaticamente e executa todos os comandos necessários em seu nome. Este artigo é uma referência para desenvolvedores que precisam instalar ou usar a CLI diretamente – por exemplo, ao construir automação de CI/CD, solucionar problemas em uma etapa específica ou trabalhar sem um agente de codificação de IA.

Note

O fluxo de trabalho completo do desenvolvedor - incluindo instalação guiada por IA, diretrizes de função e etapas pós-implantação - está em Introdução ao desenvolvimento do Agente 365. Este artigo é a referência da CLI: instalação, atualização, desinstalação, comandos disponíveis e solução de problemas.

Pré-requisitos

A CLI requer .NET 8.0 ou posterior. Para todos os outros pré-requisitos, incluindo uma assinatura do Azure e funções obrigatórias do Entra, veja Quickstart: Conecte um agente existente ao Agente 365.

autenticação do Microsoft Entra

Por padrão, a configuração do Agent 365 usa o aplicativo empresarial Agent 365 CLI gerenciado pela Microsoft quando estiver disponível no seu locatário.

Property Valor
Nome de exibição Agent 365 CLI
ID do aplicativo (cliente) f54280f4-395e-4ea8-9e48-bf2d4952aa14

Para verificar a aplicação, acesse o centro de administração do Microsoft Entra, selecione Aplicações>Empresariais Todas as aplicações e procure o ID da aplicação. O ID de Objeto do principal de serviço é exclusivo para o seu inquilino. Não use o ID do Objeto onde a CLI ou documentação pede um ID de aplicação (cliente).

A interface de linha de comando (CLI) verifica o principal de serviço da aplicação empresarial no seu tenant e valida se o token de acesso contém os escopos delegados necessários. Ele não cria nem modifica o registro de aplicativos da Microsoft. O aplicativo gerenciado pela Microsoft não eleva o usuário logado, não contorna Acesso Condicional ou Padrões de Segurança, nem remove requisitos de consentimento separados para recursos do agente.

Se o aplicativo empresarial gerenciado pela Microsoft não estiver disponível, a configuração sem necessidade de configuração procurará um aplicativo de propriedade do locatário chamado Agent 365 CLI. Configurações existentes que especificam um customizado clientAppId continuam sendo suportadas. Para instruções, veja Registro de aplicativo cliente personalizado para CLI do Agente 365.

A aplicação gerenciada pela Microsoft utiliza estes métodos interativos de autenticação:

Environment Método de autenticação
Windows nativos Gerenciador de Contas Web (WAM)
Subsistema do Windows para Linux (WSL), macOS e Linux Código do dispositivo

Aplicativos personalizados de propriedade do inquilino usam o navegador do sistema quando o WAM não está disponível.

Instale a CLI do Agent 365

Use as etapas a seguir para instalar a CLI do Agent 365 globalmente em seu sistema operacional.

Pré-requisitos

Você deve ter .NET instalado. (é recomendável .NET 8.0.)

Instalar .NET no Windows

Usar o comando dotnet para instalar a ferramenta

Instale a CLI do Agente 365 usando o seguinte comando:

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

Para as instruções mais recentes e versões disponíveis, visite a página oficial do NuGet: Microsoft.Agents.A365.DevTools.Cli no NuGet.org

Verifique a instalação

Após instalar a CLI do Agente 365, verifique se ela está corretamente instalada executando o --help comando:

a365 -h

Esse comando exibe as informações de ajuda e confirma que o CLI está pronto para uso.

Atualize a CLI do Agent 365

Atualize a CLI do Agente 365 usando o comando de atualização da ferramenta dotnet:

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

Note

Para atualizar a CLI do Agente 365, você precisa de uma conexão com a internet para acessar o pacote NuGet mais recente: Microsoft.Agents.A365.DevTools.Cli.

Desinstalar a CLI do Agente 365

Desinstale a CLI do Agente 365 usando o comando de desinstalação da ferramenta dotnet:

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

Localizações de arquivos CLI do Agente 365

O local padrão para um arquivo executável de uma ferramenta depende do sistema operacional.

Sistema operacional Caminho
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

O SDK adiciona essa localização ao seu caminho quando você o executa pela primeira vez. Assim, você pode invocar ferramentas globais de qualquer diretório sem especificar a localização da ferramenta.

O acesso à ferramenta é específico do usuário, não do computador global. Uma ferramenta global está disponível apenas para o usuário que a instalar.

Comandos de CLI do Agent 365

Para a lista completa de comandos disponíveis, use o --help comando ou consulte a Referência CLI do Agente 365.

Dica

Você não precisa executar comandos da CLI manualmente. As Habilidades do Agente 365 automatizam todo o fluxo de trabalho – instalação, configuração da CLI, configuração do blueprint, implantação e publicação – usando um agente de codificação com IA. Use a referência da CLI aqui se você estiver criando automação de CI/CD, solucionando problemas de uma etapa específica ou trabalhando sem um agente de codificação de IA.

Para obter instruções completas sobre como configurar um agente do Agent 365 usando a CLI, consulte Introdução ao desenvolvimento do Agente 365.

Resolução de problemas

Esta seção fornece informações sobre como solucionar erros com a CLI do Agente 365.

Dica

O Guia de Solução de Problemas do Agente 365 contém recomendações de resolução de problemas de alto nível, melhores práticas e links para conteúdo de solução de problemas para cada parte do ciclo de desenvolvimento do Agente 365.

Questões específicas de CLI abordadas nesta seção:

A aplicação CLI Agent 365 gerenciada pela Microsoft não está disponível

Atualize o CLI e execute a365 setup requirements novamente. Para verificar se o lançamento em etapas chegou ao seu locatário, pesquise em aplicativos empresariais no Microsoft Entra por ID f54280f4-395e-4ea8-9e48-bf2d4952aa14de aplicação.

Se o principal de serviço não estiver presente, a configuração volta a um aplicativo de propriedade do locatário chamado Agent 365 CLI. Se você ainda não tem esse aplicativo, siga as instruções em Registro de aplicativo cliente personalizado para o Agent 365 CLI.

A autenticação por código de dispositivo é bloqueada

O aplicativo gerenciado pela Microsoft utiliza autenticação por código de dispositivo em WSL, macOS e Linux. Padrões de Segurança ou uma política de Acesso Condicional podem bloquear esse fluxo e retornar AADSTS530035.

Não desative a política de segurança da sua organização para contornar esse erro. Execute a CLI no Windows nativo para usar WAM, ou trabalhe com seu administrador de identidade para usar um aplicativo personalizado de propriedade do locatário e um fluxo de autenticação que sua política permita.

A autenticação falha com AADSTS70007

Versões antigas da CLI podem usar um modo de resposta de navegador não suportado com o aplicativo gerenciado pela Microsoft e retornar AADSTS70007. Atualize para a versão mais recente do CLI e tente novamente:

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

Os escopos delegados exigidos estão ausentes

A CLI valida as permissões delegadas efetivas da aplicação gerenciada pela Microsoft com base na declaração scp contida no token de acesso. Atualize a CLI e execute a365 setup requirementsnovamente.

Não adicione URIs de redirecionamento, reivindicações opcionais, permissões de API ou concessões de permissões locais de inquilino ao aplicativo gerenciado pela Microsoft. Se a validação ainda relatar escopos ausentes, capture os IDs de rastreamento e correlação do erro e entre em contato com o suporte da Microsoft. Se você usa um aplicativo de propriedade do locatário, siga os passos de validação no registro de aplicativo cliente personalizado para a CLI do Agente 365.

agente não aparece no Microsoft Teams

Criação de instâncias de agente - Solução de problemas: agente não aparece no Teams

Não é possível criar instância de agente no Teams

Solução de problemas para criar instâncias de agente: Não é possível criar instância de agente no Teams

  • Last updated on