Compartilhar via

Interface de linha de comandos do Toolkit de Agentes do Microsoft 365

Importante

O SDK do TeamsFx será oficialmente preterido até setembro de 2025, com o suporte a continuar até setembro de 2026. Recomendamos que planee a sua transição para o SDK do Teams para criar agentes no Microsoft Teams. Para expandir as capacidades do seu agente noutras plataformas do Microsoft 365, utilize o SDK de Agentes do Microsoft 365.

A interface de linha de comandos do Microsoft 365 Agents Toolkit (Agents Toolkit CLI) é uma interface de linha de comandos baseada em texto que pode ajudar a estruturar, validar e implementar aplicações para o Microsoft 365 a partir do terminal ou de um processo de CI/CD. Para obter mais informações, veja código fonte e pacote npm.

Quer prefira operações de programador centradas no teclado ou esteja a automatizar o pipeline ci/CD, a CLI do Toolkit de Agentes oferece as mesmas funcionalidades que as extensões de IDE. Fornece as seguintes funcionalidades para facilitar o desenvolvimento de agentes ou aplicações para Microsoft 365 Copilot, Microsoft Teams e Microsoft 365:

  • Colaboração: convide outros programadores para colaborarem no seu projeto do Toolkit de Agentes para depurar e implementar.
  • Criação de Agente/Aplicação: gere um novo agente ou aplicação com modelos e exemplos disponíveis.
  • Pré-visualização do Agente/Aplicação: carregue e pré-visualize o seu agente ou aplicação no Teams, Outlook e na aplicação Microsoft 365.
  • Aprovisionamento e Implementação de Recursos: aprovisione os recursos da cloud necessários e implemente a aplicação para Azure.
  • Validação, Empacotamento e Publicação: valide, empacote e publique o agente ou aplicação com comandos da CLI.
  • Gestão do Ambiente: faça a gestão de vários ambientes, aplicações Microsoft Entra e registo de aplicações do Teams.

Introdução

Instale @microsoft/m365agentstoolkit-cli de npm e execute atk -h para verificar todos os comandos disponíveis:

  npm install -g @microsoft/m365agentstoolkit-cli
  atk -h

Captura de ecrã a mostrar a instalação do pacote npm.

Comandos com suporte

A tabela seguinte lista os comandos suportados para ajudar os programadores a criar e gerir agentes ou aplicações:

Comando Descrição
atk doctor Verificador de pré-requisitos para criar Microsoft 365 Apps.
atk new Crie uma nova Aplicação do Microsoft 365.
atk add Adicionar funcionalidade à sua Aplicação do Microsoft 365.
atk auth Gerir contas do Microsoft 365 e Azure.
atk entra-app Gerir a aplicação Microsoft Entra na aplicação atual.
atk env Gerencie ambientes.
atk help Mostrar ajuda da CLI do Toolkit de Agentes do Microsoft 365.
atk install Carregue um determinado pacote de aplicação no Microsoft 365.
atk launchinfo Obtenha informações de lançamento de uma Aplicação do Microsoft 365 adquirida.
atk list Lista de modelos e exemplos de Aplicações do Microsoft 365 disponíveis.
atk provision Execute a fase de aprovisionamento em m365agents.yml ou m365agents.local.yml.
atk deploy Execute a fase de implementação em m365agents.yml ou m365agents.local.yml.
atk package Crie a sua Aplicação do Microsoft 365 num pacote para publicação.
atk validate Valide a Aplicação do Microsoft 365 com o esquema de manifesto, regras de validação ou casos de teste.
atk publish Execute a fase de publicação no m365agents.yml.
atk preview Pré-visualize o aplicativo atual.
atk update Atualize o manifesto da Aplicação Microsoft 365 para o Portal do Programador.
atk upgrade Atualize o projeto para trabalhar com a versão mais recente do Toolkit de Agentes do Microsoft 365.
atk collaborator Verifique, conceda e liste permissões para quem pode aceder e gerir a Aplicação microsoft 365 e Microsoft Entra aplicação.
atk uninstall Limpe os recursos associados ao ID do Manifesto, ao ID do Título ou a um ambiente.

Captura de ecrã a mostrar a lista de comandos disponíveis.

Opções globais

Seguem-se as opções globais que pode utilizar com cada comando:

Opções Descrição
--version -v Apresentar a versão da CLI do Toolkit de Agentes do Microsoft 365.
--help -h Mostrar ajuda da CLI do Toolkit de Agentes do Microsoft 365.
--interactive -i Execute o comando no modo interativo. O valor padrão é true.
--debug Imprimir informações de depuração. O valor padrão é falso.
--verbose Imprimir informações de diagnóstico. O valor padrão é falso.
--telemetry Ativa a telemetria. O valor padrão é true.

Captura de ecrã a mostrar a lista de opções globais.

Modo interativo

Os comandos têm diferentes modos interativos predefinidos. Alguns comandos são interativos por predefinição e outros não são interativos. Para determinar o modo interativo predefinido de um comando, utilize a opção -h com o comando específico.

atk doctor

O atk doctor comando verifica os pré-requisitos necessários para criar Microsoft 365 Apps.

atk new

O atk new comando funciona num modo interativo por predefinição e fornece orientações para criar uma nova Aplicação do Microsoft 365. Para trabalhar atk new num modo não interativo, defina o --interactive sinalizador como false.

atk new
atk new -i false
Comando Descrição
atk new sample Crie uma aplicação a partir de um exemplo existente.
atk list samples Apresenta uma lista de todos os exemplos pré-existentes disponíveis.

atk new parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk new:

Parâmetro Obrigatório Descrição
--app-name -n Sim Nome da sua aplicação.
--capability -c Sim Especifica a funcionalidade da aplicação. As opções disponíveis são declarative-agent, basic-custom-engine-agent e weather-agent. Utilize atk list templates para ver todas as opções disponíveis.
--programming-language -l Não Linguagem de programação. As opções disponíveis são javascript, typescripte csharp. O valor padrão é javascript.
--folder -f Não Diretório onde a pasta do projeto é criada. O valor padrão é ./.
--spfx-solution -s Não Criar ou importar uma solução de Estrutura do SharePoint existente. As opções disponíveis são new e import. O valor padrão é new.
--spfx-install-latest-package Não Instale a versão mais recente do Estrutura do SharePoint. O valor padrão é true.
--spfx-framework-type -k Não Aplicável se o recurso framework estiver selecionado. As opções disponíveis são minimal, reacte none. O valor padrão é react.
--spfx-webpart-name -w Não Nome para Estrutura do SharePoint Peça Web. O valor padrão é helloworld.
--spfx-folder Não Diretório ou caminho que contém a solução de Estrutura do SharePoint existente.
--me-architecture -m Não Arquitetura da extensão de mensagens baseada em pesquisa. As opções disponíveis são new-api, api-spece bot. O valor padrão é new-api.
--openapi-spec-location -a Não Localização do documento de descrição openAPI.
--api-operation -o Não Selecione as operações com as quais o Teams pode interagir.
--bot-host-type-trigger -t Não Especifica o acionador para Chat Notification Message o modelo de aplicação. As opções disponíveis são http-express, http-webapie http-and-timer-functions. O valor padrão é http-express.

Captura de ecrã a mostrar os novos parâmetros de atk.

atk new cenários

Seguem-se uma lista de cenários para controlar todos os parâmetros com atk new:

  • Crie um agente meteorológico.

    atk new -c weather-agent -l typescript -n myagent -i false

  • Crie um novo bot de notificação acionado pelo temporizador.

    atk new -c notification -t timer-functions -l typescript -n myapp -i false

  • Importar uma solução de Estrutura do SharePoint existente.

    atk new -c tab-spfx -s import --spfx-folder <folder-path> -n myapp -i false

atk add

Adicionar funcionalidade à sua Aplicação do Microsoft 365.

Comando Descrição
atk add spfx-web-part [options] Peça Web SPFx alojada automaticamente totalmente integrada com o Microsoft 365.
atk add action [options] Uma ação para expandir o Copilot com as suas APIs.
atk add auth-config [options] Adicione configurações para suportar ações com autenticação no agente declarativo.
atk add capability [options] Uma capacidade para expandir o Copilot com as suas APIs.

atk auth

Gerir contas do Microsoft 365 e Azure.

Comando Descrição
atk auth list Apresentar todas as contas ligadas do Microsoft 365 e Azure.
atk auth login Inicie sessão no Microsoft 365 ou Azure conta.
atk auth logout <service> Termine sessão no Microsoft 365 ou Azure conta.

atk entra-app

Gerir a aplicação Microsoft Entra na aplicação atual.

Comando Descrição
atk entra-app update Atualize a aplicação Microsoft Entra na aplicação atual.

atk env

Gerir ambientes de aplicações.

Comando Descrição
atk env add Adicione um novo ambiente copiando do ambiente especificado.
atk env list Lista todos os ambientes disponíveis.
atk env reset Repor ficheiro de ambiente.

atk env cenário

Crie um novo ambiente ao copiar a partir do ambiente de programador existente:

atk env add staging --env dev

atk help

O atk help comando apresenta todos os comandos disponíveis para a CLI do Toolkit de Agentes do Microsoft 365.

atk install

Carregue um determinado pacote de aplicação no Microsoft 365.

atk install parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk install:

Comando Descrição
--file-path Caminho para o pacote zip do manifesto da aplicação.
--xml-path Caminho para o ficheiro xml de manifesto XML.
--scope Âmbito da aplicação. As opções disponíveis são Pessoal e Partilhado.

atk install cenários

Carregue o pacote de aplicação com o manifesto baseado em JSON para o Teams, Outlook e a aplicação Microsoft 365.

atk install --file-path appPackage.zip

Carregue o pacote de aplicação no Âmbito partilhado com o manifesto baseado em JSON para o Teams, Outlook e a aplicação Microsoft 365.

atk install --file-path appPackage.zip --scope Shared

Carregue o pacote de aplicação de suplemento do Outlook com o manifesto baseado em XML para o Outlook.

atk install --xml-path manifest.xml

atk launchinfo

Obtenha informações de lançamento de uma Aplicação do Microsoft 365 adquirida.

atk launchinfo parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk launchinfo:

Comando Descrição
--title-id Especifica o ID de título da aplicação do Microsoft 365 adquirida.
--manifest-id Especifica o ID de manifesto da aplicação do Microsoft 365 adquirida.

atk launchinfo cenários

Obtenha informações de lançamento da aplicação do Microsoft 365 adquirida pelo ID de título.

atk launchinfo --title-id U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Obtenha informações de lançamento da aplicação do Microsoft 365 adquirida por ID de manifesto.

atk launchinfo --manifest-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

atk list

Listar exemplos e modelos de aplicações do Microsoft 365 disponíveis.

atk list parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk list:

Comando Descrição
atk list samples Apresenta uma lista de exemplos de aplicações disponíveis.
atk list templates Apresenta uma lista de modelos de aplicações disponíveis.

Captura de ecrã a mostrar a lista de modelos.

atk provision

O atk provision comando executa a fase de aprovisionamento em m365agents.yml.

Para acionar a fase de aprovisionamento no m365agents.local.yml, execute atk provision --env local.

atk provision parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk provision:

Parâmetros Obrigatório Descrição
--env Não Especifica o nome do ambiente do projeto estruturado pelo Toolkit de Agentes do Microsoft 365.
--folder -f Não Especifica a pasta raiz do projeto. Predefinição para ./.
--ignore-env-file Não Para ignorar o carregamento do ficheiro .env quando --env não for especificado.

atk deploy

O atk deploy comando executa a fase de implementação em m365agents.yml.

Para acionar a fase de implementação no m365agents.local.yml, execute atk deploy --env local.

atk deploy parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk deploy:

Parâmetro Obrigatório Descrição
--env Sim Especifica o nome do ambiente do projeto estruturado pelo Toolkit de Agentes do Microsoft 365.
--folder -f Não Especifica a pasta raiz do projeto. Predefinição para ./.
--ignore-env-file Não Para ignorar o carregamento do ficheiro .env quando --env não for especificado.
--config-file-path -c Não Especifica o caminho do ficheiro yaml de configuração.

atk package

Crie a sua Aplicação do Microsoft 365 num pacote para publicação.

atk package parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk package:

Parâmetro Obrigatório Descrição
--env Não Especifica o nome do ambiente do projeto estruturado pelo Toolkit de Agentes do Microsoft 365.
--env-file Não Especifica o ficheiro .env que define as variáveis a substituir no ficheiro de modelo de manifesto de aplicação.
--manifest-file Não Especifica o caminho do ficheiro de manifesto da aplicação. O valor padrão é ./appPackage/manifest.json.
--output-folder Não Especifica a pasta de saída que contém os manifestos. O valor padrão é ./appPackage/build.
--output-package-file Não Especifica o caminho do ficheiro do pacote de aplicação zipado de saída. O valor padrão é ./appPackage/build/appPackage.${env}.zip.
--folder -f Não Especifica a pasta raiz do projeto. O valor padrão é ./.

atk validate

Valide a Aplicação do Microsoft 365 com o esquema de manifesto, regras de validação ou casos de teste.

atk validate parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk validate:

Parâmetro Obrigatório Descrição
--env Não Especifica o nome do ambiente do projeto estruturado pelo Toolkit de Agentes do Microsoft 365.
--env-file Não Especifica o ficheiro .env que define as variáveis a substituir no ficheiro de modelo de manifesto de aplicação.
--manifest-file Não Especifica o caminho do ficheiro de manifesto da aplicação. O valor padrão é ./appPackage/manifest.json.
--package-file Não Especifica o caminho do ficheiro do pacote de aplicação zipado.
--output-folder Não Especifica a pasta de saída que contém os manifestos. O valor padrão é ./appPackage/build.
--output-package-file Não Especifica o caminho do ficheiro do pacote de aplicação zipado de saída. O valor padrão é ./appPackage/build/appPackage.${env}.zip.
--folder -f Não Especifica a pasta raiz do projeto. O valor padrão é ./.
--validate-method -m Não Especifica o método de validação Valor permitido: validation-rules ou test-cases.

atk publish

O atk publish comando executa a fase de publicação em m365agents.yml.

atk publish parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk publish:

Parâmetro Obrigatório Descrição
--env Não Especifica o nome do ambiente do projeto estruturado pelo Toolkit de Agentes do Microsoft 365.
--env-file Não Especifica o ficheiro .env que define as variáveis a substituir no ficheiro de modelo de manifesto de aplicação.
--manifest-file Não Especifica o caminho do ficheiro de manifesto da aplicação. O valor padrão é ./appPackage/manifest.json.
--package-file Não Especifica o caminho do ficheiro do pacote de aplicação zipado.
--output-folder Não Especifica a pasta de saída que contém os manifestos. O valor padrão é ./appPackage/build.
--output-package-file Não Especifica o caminho do ficheiro do pacote de aplicação zipado de saída. O valor padrão é ./appPackage/build/appPackage.${env}.zip.
--folder -f Não Especifica a pasta raiz do projeto. O valor padrão é ./.

atk preview

O atk preview comando permite-lhe pré-visualizar a sua aplicação durante o desenvolvimento. Este comando fornece uma vista em tempo real da sua aplicação, ajudando-o a identificar e corrigir problemas antes da implementação.

atk preview parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk preview:

Parâmetro Obrigatório Descrição
--m365-host -m Não Pré-visualize a aplicação no Teams, Outlook ou na aplicação Microsoft 365. As opções disponíveis são teams, outlooke office. O valor padrão é teams.
--manifest-file Não Especifica o caminho do ficheiro de manifesto da aplicação. O valor padrão é ./appPackage/manifest.json.
--run-command -c Não O comando inicia o serviço e funciona apenas no ambiente local. Se não estiver definido, deteta automaticamente o comando adequado do tipo de projeto (npm run dev:atk, dotnet runou func start). Se estiver vazio, ignora o início do serviço local.
--running-pattern -p Não A saída do sinal pronto para o qual o serviço é iniciado. Funciona apenas para local o ambiente. Se não estiver definido, o comando O valor predefinido é (iniciado|com êxito|concluído|falhou|falhou|a ouvir|pronto). Se estiver vazio, o processo é iniciado como sinal pronto.
--open-only -o Não Funciona apenas para local o ambiente. Se for verdadeiro, abra diretamente o cliente Web sem iniciar o serviço local. O valor padrão é false.
--browser -b Não Selecione browser para abrir o cliente Web do Microsoft Teams. As opções disponíveis são chrome, edgee default. O valor padrão é default.
--browser-arg -ba Não Argumento para passar para o browser. Por exemplo, --browser-args="--guest.
--exec-path -ep Não Os caminhos que são adicionados à variável de ambiente do sistema "PATH" quando o comando é executado. O valor padrão é devTools/func.
--desktop -d Não Se for verdade, abra o cliente de ambiente de trabalho do Teams em vez do cliente Web. O valor padrão é falso.
--env Não Especifica um ambiente existente para o projeto. O valor padrão é local.
--folder -f Não Especifica a pasta raiz do projeto. O valor padrão é ./.

atk preview cenários

O atk preview comando tem de ser utilizado depois atk provision de e atk deploy.

A lista seguinte fornece os cenários comuns para atk preview:

  • Pré-visualização Local: seguem-se as dependências para utilizar a pré-visualização local:

    • Node.js
    • SDK DO .NET
    • Ferramentas do Azure Functions Core versão 3.
    atk preview --env --local
atk preview --env --local --browser chrome

  • Visualização Remota

    atk preview --env --remote
atk preview --env --remote --browser edge

    Observação

    Os logs dos serviços em segundo plano, como React, são salvos em ~/.fx/cli-log/local-preview/.

atk update

Atualize o manifesto da aplicação para o Portal do Programador.

atk update parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk update:

Parâmetro Obrigatório Descrição
--env Não Especifica o nome do ambiente do projeto estruturado pelo Toolkit de Agentes do Microsoft 365.
--env-file Não Especifica o ficheiro .env que define as variáveis a substituir no ficheiro de modelo de manifesto de aplicação.
--manifest-file Não Especifica o caminho do ficheiro de manifesto da aplicação. O valor padrão é ./appPackage/manifest.json.
--package-file Não Especifica o caminho do ficheiro do pacote de aplicação zipado.
--output-folder Não Especifica a pasta de saída que contém os manifestos. O valor padrão é ./appPackage/build.
--output-package-file Não Especifica o caminho do ficheiro do pacote de aplicação zipado de saída. O valor padrão é ./appPackage/build/appPackage.${env}.zip.
--folder -f Não Especifica a pasta raiz do projeto. O valor padrão é ./.

atk upgrade

Atualize o projeto para trabalhar com a versão mais recente do Toolkit de Agentes do Microsoft 365.

atk upgrade parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk upgrade:

Parâmetro Obrigatório Descrição
--force -f Não Force a atualização do projeto para trabalhar com a versão mais recente do Toolkit de Agentes do Microsoft 365. O valor predefinido é false.

atk collaborator

Verifique, conceda e liste permissões para quem pode aceder e gerir aplicações e Microsoft Entra aplicação.

Comando Descrição
atk collaborator status Apresenta a permissão atual status do projeto.
atk collaborator grant Conceder permissão para outra conta.

atk collaborator status parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk collaborator status:

Parâmetro Obrigatório Descrição
--env Não Especifica o nome do ambiente do projeto estruturado pelo Toolkit de Agentes do Microsoft 365.
--manifest-file Não Especifica o caminho do ficheiro de manifesto da aplicação. O valor padrão é ./appPackage/manifest.json.
--entra-app-manifest-file -a Não Selecione o caminho para o ficheiro de modelo de manifesto entra. O valor padrão é ${folder}/aad.manifest.json.
--all -a Não Apresentar todos os colaboradores.
--folder -f Não Selecione a pasta raiz do projeto. O valor padrão é ./.

atk collaborator grant parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk collaborator grant:

Parâmetro Obrigatório Descrição
--email Não Introduza o endereço de e-mail do colaborador.
--manifest-file Não Especifica o caminho do ficheiro de manifesto da aplicação. O valor padrão é ./appPackage/manifest.json.
--entra-app-manifest-file -a Não Selecione o caminho para o ficheiro de manifesto da aplicação Entra. O valor padrão é ${folder}/aad.manifest.json.
--env Não Especifica o nome do ambiente do projeto estruturado pelo Toolkit de Agentes do Microsoft 365.
--folder -f Não Selecione a pasta raiz do projeto. O valor padrão é ./.

atk collaborator cenários

Conceda permissão para que outra conta do Microsoft 365 colabore na aplicação.

atk collaborator grant -i false --manifest-file ./appPackage/manifest.json --env dev --email other@email.com

atk uninstall

Limpe os recursos associados ao ID do manifesto, ao ID do título ou a um ambiente no projeto gerado pelo Toolkit de Agentes do Microsoft 365. Os recursos incluem o registo de aplicações no Portal do Programador, o registo de bots no Portal do Bot Framework e as aplicações personalizadas carregadas nas aplicações do Microsoft 365.

atk uninstall parâmetros

A tabela seguinte lista os parâmetros disponíveis para atk uninstall:

Comando Descrição
--mode Escolha uma forma de limpo recursos.
--title-id Especifica o ID de título da aplicação do Microsoft 365 instalada.
--manifest-id Especifica o ID de manifesto da aplicação do Microsoft 365 instalada.

atk uninstall cenários

Remova a Aplicação do Microsoft 365 adquirida com o ID de título.

atk uninstall -i false --mode title-id --title-id U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Remova a Aplicação do Microsoft 365 adquirida com o ID de manifesto.

atk uninstall -i false --mode manifest-id --manifest-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --options 'm365-app,app-registration,bot-framework-registration'

Remova a Aplicação do Microsoft 365 adquirida com o ambiente no projeto gerado pelo Toolkit de Agentes do Microsoft 365.

atk uninstall -i false --mode env --env xxx --options 'm365-app,app-registration,bot-framework-registration' --folder ./myapp

Desinstalar no modo interativo.

atk uninstall
  • Last updated on