Agente 365 CLI

O Agent 365 CLI é uma ferramenta multiplataforma de linha de comando para implantar e gerenciar aplicações do Agent 365 no Azure.

Pré-requisitos

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

• Registro personalizado de aplicativo cliente - A CLI requer um aplicativo cliente personalizado no seu tenant Microsoft Entra ID para autenticação. Veja Registro de aplicativo cliente personalizado para instruções detalhadas de configuração. Você precisa do ID da aplicação (cliente) durante a configuração.
• Assinatura Azure - Acesso a uma assinatura Azure onde você pode criar recursos.
• Permissões necessárias - Sua conta deve ter um dos seguintes papéis:
  • Administrador global
  • Administrador de ID de Agente
  • Desenvolvedor de ID de Agente

Instale a CLI do Agent 365

Use os passos a seguir para instalar a CLI do Agent 365 globalmente no seu sistema operacional.

Pré-requisitos

Você precisa ter o instalado. (.NET 8.0 é recomendado.)

dotnet tool install

Instale o Agente Convidado usando o seguinte comando:

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

Se receber um microsoft.agents.a365.devtools.cli is not found in NuGet feeds https://api.nuget.org/v3/index.json erro, use o --prerelease parâmetro, pois esse pacote ainda pode estar marcado como pré-lançamento.

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

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 está corretamente instalada executando:

a365 -h

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

Atualizar

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

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

Desinstalar

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

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

Locais de arquivos

O local padrão para binários de uma ferramenta depende do sistema operacional:

Esse local é adicionado ao caminho do usuário quando o SDK é executado pela primeira vez. Portanto, as ferramentas globais podem ser invocadas de qualquer diretório sem especificar o local da ferramenta.

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

Comandos disponíveis

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

Atualizações importantes

Comando removido: O create-instance comando foi removido da CLI. Ele contornava as etapas obrigatórias de registro, o que limitaria a funcionalidade do agente. Esse comando pode ser reintroduzido em uma versão posterior, assim que estiver em conformidade com o fluxo de trabalho recomendado.

Use este fluxo de trabalho em vez disso:

1. a365 publish - Publicar agente no centro de administração do Microsoft 365
2. Configurar o blueprint do agente no Portal do Desenvolvedor - Veja Configurar o blueprint do agente no Portal do Desenvolvedor
3. a365 deploy - Implantar no Azure (opcional, somente se usar hospedagem Azure)
4. Crie uma instância de agente pelo Microsoft Teams

Consulte os agentes a bordo para instruções completas.

Solução de problemas

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

• A instalação, atualização ou desinstalação da CLI falha com Not found in NuGet feeds
• create-instance comando não encontrado
• Agente não aparecendo no Teams
• Não é possível criar instância de agente no Teams

A instalação, atualização ou desinstalação da CLI falha com Not found in NuGet feeds

Se receber um microsoft.agents.a365.devtools.cli is not found in NuGet feeds https://api.nuget.org/v3/index.json erro, use o --prerelease parâmetro, pois esse pacote ainda pode estar marcado como pré-lançamento.

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

create-instance comando não encontrado

Sintoma:

Error: Command 'create-instance' not found

Causa: O create-instance comando foi removido da CLI. Ele contornava as etapas obrigatórias de registro, o que limitaria a funcionalidade do agente. Esse comando pode ser reintroduzido em uma versão posterior, assim que estiver em conformidade com o fluxo de trabalho recomendado.

Solution:

Use o fluxo de trabalho atualizado:

1. Publique seu corretor:

   a365 publish
   

2. Configure o blueprint do agente no Portal do Desenvolvedor:

   Consulte o projeto Configurar o agente no Portal de Desenvolvedores para instruções detalhadas.

3. Deploy para Azure (opcional):

   # Only if hosting on Azure Web App
   a365 deploy
   

4. Crie uma instância de agente via Microsoft Teams:

   • Open Microsoft Teams
   • Navegar para Apps
   • Procure seu agente
   • Clique em "Adicionar" para criar uma instância de agente

Para instruções detalhadas, veja Agentes a bordo.

Agente que não aparece em equipes

Sintoma: Após executar comandos, o agente não aparece no Microsoft Teams.

Causa: Você pode ter pulado o publish passo ou tentado usar o comando removido create-instance .

Solution:

1. Verifique se você rodou a365 publish com sucesso
2. Aguardar de 5 a 10 minutos para a propagação
3. Confira o Centro de Administração do Microsoft 365: https://admin.cloud.microsoft/#/agents/all
4. Crie uma instância de agente pela seção de Apps do Teams

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

Sintoma: O agente aparece no Teams, mas você não pode criar uma instância de agente (não é possível adicionar o agente).

Causa: A licença "Microsoft Agent 365 Frontier" não está atribuída à sua conta de usuário.