Início Rápido: empacotar um agente declarativo existente como um plug-in com as Ferramentas de Desenvolvimento do Work IQ

Use as Ferramentas de Desenvolvimento do Work IQ com a origem local para um agente declarativo existente para validar, provisionar, empacotar e compartilhar como um plug-in. Este início rápido começa a partir de um projeto de origem existente, não de um scaffold de novo agente.

Este passo a passo não cria um novo agente nem reconstrói a origem de um agente instalado. Se você estiver iniciando um novo plug-in, siga Criar um plug-in com as Ferramentas de Desenvolvimento do Work IQ.

Dica

Assista ao Work IQ Dev Tools criar um plug-in do Copilot a partir de um prompt e publicá-lo no Agent Store na demonstração interativa.

Pré-requisitos

  • CLI do GitHub Copilot com uma assinatura ativa do Copilot
  • O plug-in do assistente de codificação WIQD para CLI do GitHub Copilot (consulte os comandos de instalação nesta seção)
  • Node.js 24.15 ou posterior e npm, disponível em , PATHpara a CLI WIQD e script de instalação
  • PowerShell 7 ou posterior (somente Windows)
  • Uma conta do Microsoft 365 com acesso ao Copilot
  • Upload de aplicativo personalizado habilitado em seu locatário
  • Um projeto de origem de agente declarativo com suporte

Depois de instalar a CLI do GitHub Copilot, instale o plug-in do assistente de codificação WIQD:

copilot plugin install wiqd@awesome-copilot

Como alternativa, adicione o marketplace WIQD e instale o plug-in a partir daí:

copilot plugin marketplace add microsoft/wiqd
copilot plugin install wiqd@wiqd

Instale a CLI WIQD usando o script de instalação.

Inicie uma nova sessão da CLI do GitHub Copilot após a instalação.

O plug-in do assistente de codificação fornece diretrizes de criação; ele não instala a wiqd CLI. Instale a CLI separadamente antes de executar comandos de validação e ciclo de vida. Confirme a instalação da CLI e wiqd --version marque seus pré-requisitos com wiqd doctor.

Confirme se você tem um projeto inicial com suporte

Inicie a partir da pasta raiz de um projeto de origem de agente declarativo local. No mínimo, a pasta deve conter:

contoso-support-agent/
|-- appPackage/
|   |-- manifest.json
|   |-- declarativeAgent.json
|   `-- <the instruction and action files referenced by the manifests>
`-- <a supported lifecycle file>

O arquivo de ciclo de vida pode ser m365agents.yml, m365agents.local.yml, teamsapp.ymlou teamsapp.local.yml. O projeto pode conter outras pastas e arquivos de ambiente.

Este guia de início rápido não se aplica quando:

  • Você tem apenas um agente publicado ou pacote instalado e nenhum projeto de origem local. As Ferramentas de Desenvolvimento do Work IQ não dão suporte à reconstrução do projeto de origem a partir de um título implantado. Recupere o repositório de origem original ou use a ferramenta de criação original.
  • O agente existe apenas em uma experiência de criação gerenciada, como o Agent Builder ou o Copilot Studio. Use o procedimento de publicação e compartilhamento dessa ferramenta.
  • Você tem um agente de mecanismo personalizado. Esta rota Work IQ Dev Tools suporta agentes declarativos.
  • Você tem apenas um pacote de .zipagente . Os comandos do ciclo de vida exigem o projeto de origem e seu arquivo de ciclo de vida.

Se você não tiver um projeto existente, comece com o início rápido do WIQD para criar um plug-in e adicionar um agente declarativo. O WIQD é o ponto de partida recomendado para o pró-código para cenários com suporte.

Observação

wiqd plugin importimporta formatos de plug-in aberto, plug-in Claude ou plug-in de cursor com suporte. Ele não importa um projeto ou pacote de agente declarativo do Microsoft 365 existente. Para obter mais informações, consulte Importar/exportar (interoperabilidade).

Criar seu plug-in

  1. Se ainda não fez isso, instale o Work IQ Dev Tools.

  2. Abra sua CLI no diretório em que você deseja criar seu plug-in e entre usando o seguinte comando:

    wiqd auth login --interactive
    
  3. Na CLI, inicie o GitHub Copilot usando o copilot comando.

  4. Peça ao GitHub Copilot para criar um plug-in com seu agente declarativo, habilidade ou servidor MCP existente. Por exemplo:

    Create a plugin named My Plugin by using the agent in "..\My Agent"
    

Validar o projeto de plug-in

Selecione explicitamente a validação de origem offline antes de provisionar ou empacotar o plug-in. Na CLI do GitHub Copilot, pergunte:

Validate the plugin source offline in the dev environment

Provisionar o plug-in

Importante

Este exemplo usa o ambiente compartilhado dev padrão. Verifique a configuração do ciclo de vida efetivo e o arquivo de ambiente selecionado em environmentFolderPath (padrão env) antes AGENT_SCOPE=shared de provisionar para compartilhamento. Um ambiente nomeado dev sozinho não estabelece um escopo compartilhado. Mantenha o mesmo ambiente para provisionamento, empacotamento, validação e compartilhamento.

Peça ao GitHub Copilot para provisionar o plug-in.

Provision the plugin using the dev environment

Aguarde a conclusão do provisionamento. O provisionamento não estabelece que todos os recursos de plug-in estejam disponíveis no Copilot Chat; o suporte depende do componente e da experiência de destino do Microsoft 365.

Empacotar o plug-in

Peça ao GitHub Copilot para empacotar o plug-in.

Package the plugin using the dev environment

Importante

Você deve provisionar o plug-in antes de empacotá-lo. Se você empacotar antes de provisionar, o pacote resultante será inválido.

Validar o pacote

Após o empacotamento, localize o ZIP gerado e confirme se o arquivo existe. Na CLI do GitHub Copilot, forneça o caminho real e pergunte:

Validate this existing plugin ZIP in package mode using the dev environment

A validação de pacote usa e --mode package um ZIP existente fornecido por meio de --package-file, não uma compilação automática. Revise o veredicto e as conclusões retornadas. O código 0 de saída significa que as verificações selecionadas foram aprovadas; os avisos ainda podem ser relatados. O bloqueio de descobertas ou resultados incompletos não são uma aprovação, e a validação do pacote não prova o comportamento do tempo de execução.

Os modos de validação atuais são source, package, e marketplace. sourceé a marcação offline explícita. O padrão, package, requer um ZIP existente, carrega uma cópia capturada no serviço de validação do Microsoft 365 e pode exigir autenticação. marketplace adiciona verificações de políticas e evidências; Não é a aprovação oficial da loja. A validação não cria automaticamente um ZIP, não conecta você nem provisiona o plug-in. Para obter detalhes, consulte Validação e MVL.

Compartilhar o plug-in

Agora você pode pedir ao GitHub Copilot para compartilhar sua implantação de plug-in, seja com usuários específicos dentro da sua organização ou com toda a sua organização. Confirme AGENT_SCOPE=shared no ambiente selecionado antes de compartilhar. A audiência de compartilhamento (--scope users--scope tenantou ) não altera o escopo da implantação.

Share the plugin with AmberR@contoso.com using the dev environment

Ou:

Share the plugin with my organization using the dev environment

Importante

O compartilhamento de plug-ins personalizados depende das configurações da sua organização para permitir ou bloquear o compartilhamento de plug-ins. Se você encontrar algum erro durante esta etapa, marque com seus administradores. Para obter mais informações, consulte Configurações de compartilhamento e publicação de agentes.

Publique o plug-in no registro de plug-in da sua organização

Em vez de compartilhar seu plug-in, você pode solicitar a publicação de seu plug-in no registro de plug-ins da sua organização. Os administradores da sua organização podem revisar seu plug-in e aprovar ou negar a solicitação.

Submit my plugin to the organization catalog for admin approval using the dev environment

O compartilhamento concede acesso direto; O envio de catálogo é uma operação separada e não é uma aprovação do administrador ou instalação concluída do usuário.

Exclua o pacote (opcional)

Se esse plug-in for apenas um plug-in de teste, peça ao GitHub Copilot para removê-lo. Essa ação exclui todos os recursos de nuvem provisionados.

Delete the plugin using the dev environment