Usando fluxos de trabalho dinâmicos

Encontre, execute, monitore e retome fluxos de trabalho dinâmicos em GitHub Copilot CLI e em GitHub Copilot app.

Neste artigo

Observação

Esse recurso está em prévia pública e está sujeito a alterações.

Este artigo explica como criar, usar e compartilhar fluxos de trabalho dinâmicos no GitHub Copilot CLI e no GitHub Copilot app.

Para ter uma visão geral do que são fluxos de trabalho dinâmicos e como eles funcionam, consulte Fluxos de trabalho dinâmicos.

Pré-requisito

Para usar fluxos de trabalho dinâmicos em Copilot CLI, você deve ativar recursos experimentais executando a CLI com a opção de linha de comando --experimental ou usando /experimental on em uma sessão interativa.

Descobrir sobre fluxos de trabalho dinâmicos disponíveis

Talvez você já tenha acesso a um ou mais fluxos de trabalho dinâmicos na sua sessão — por exemplo, por meio de uma extensão pessoal ou de uma extensão no repositório em que você está trabalhando. Nesse caso, você pode usar um mencionando-o pelo nome em um prompt.

Para descobrir se os fluxos de trabalho dinâmicos estão disponíveis, basta perguntar Copilot. Por exemplo:

Copilot prompt
What dynamic workflows are available?

Se houver fluxos de trabalho dinâmicos disponíveis, você pode solicitar que Copilot descreva um. Por exemplo:

Copilot prompt
Tell me more about the java-security-checks dynamic workflow.

Se você ainda não tiver fluxos de trabalho dinâmicos, poderá criar um. Consulte Como criar um fluxo de trabalho dinâmico.

Executando um fluxo de trabalho dinâmico

  1. Em uma sessão Copilot, digite um prompt em linguagem natural pedindo ao Copilot que execute um fluxo de trabalho dinâmico.

    Use o nome registrado do fluxo de trabalho e forneça as entradas necessárias. Por exemplo, um fluxo de trabalho dinâmico que realiza uma revisão de segurança normalmente exigirá que você especifique os arquivos sobre os quais ele deve ser executado. Nesse caso, você pode inserir um prompt como:

    Copilot prompt
    Run the java-security-checks dynamic workflow on the java files in the current directory, with an AI credit limit of 500.

    Importante

    Definir limites em um fluxo de trabalho dinâmico é opcional, mas recomendado, pois ajuda a controlar o uso de recursos e evitar o consumo excessivo de AI credits. Para obter mais informações sobre os limites que você pode definir, consulte Fluxos de trabalho dinâmicos.

  2. Dependendo das suas configurações atuais de aprovação de permissões, Copilot solicita que você aprove a execução do fluxo de trabalho dinâmico antes de ela começar. Escolha Sim.

Se a extensão fornecer outra forma de iniciar seu fluxo de trabalho, como um comando com barra ou um controle da tela no Copilot app, siga as instruções dessa extensão.

Executando um fluxo de trabalho dinâmico da linha de comando

  1. No terminal, use o Copilot CLI comando copilot workflow run WORKFLOW-NAME [OPTIONS] para executar um fluxo de trabalho dinâmico existente.

    O fluxo de trabalho deve estar disponível por meio de uma extensão pessoal, uma extensão de projeto ou um plug-in instalado. Se você criou o fluxo de trabalho em uma sessão de chat, primeiro disponibilize sua extensão fora dessa sessão. Consulte Reutilizando e compartilhando fluxos de trabalho dinâmicos.

    Use --args para fornecer entradas para o fluxo de trabalho como JSON.

    Importante

    Esse comando não exibe solicitações de aprovação de permissões, mesmo quando você o executa em um terminal. Dê aos agentes do fluxo de trabalho as permissões de que precisam antes de começar, por exemplo, com --allow-tool ou --allow-url. Solicitações que não podem ser aprovadas automaticamente são recusadas. Para obter mais informações, consulte referência programática do GitHub Copilot CLI.

    Por exemplo, suponha que você tenha um fluxo de trabalho chamado java-security-checks que aceite uma directory entrada e precise de permissão para ler arquivos:

    Shell
    copilot workflow run java-security-checks \
   --args '{"directories":["java/src","java/tests"]}' \
   --allow-tool=read

    Substitua o nome do fluxo de trabalho, os campos de entrada e as permissões para corresponderem ao seu fluxo de trabalho. Se o fluxo de trabalho não precisar de entradas, omita --args.

    Como alternativa, coloque as entradas JSON em um arquivo e prefixe seu caminho com @:

    Shell
    copilot workflow run java-security-checks \
   --args @workflow-input.json \
   --allow-tool=read

  2. Acompanhe as fases e as mensagens de progresso informadas pelo fluxo de trabalho. Quando ele é concluído, o comando imprime seu resultado, se ele retorna um e sai. Se a execução for pausada ou interrompida sem ser concluída, o comando informará o status e o ID da execução. Para interromper uma execução, pressione Ctrl+C.

Os limites configurados do fluxo de trabalho e seus limites pessoais padrão ainda se aplicam. Consulte Fluxos de trabalho dinâmicos.

Salvar o resultado em um arquivo

Adicione --result-file para gravar o valor retornado do fluxo de trabalho em um arquivo JSON em vez de imprimi-lo no terminal. As mensagens de progresso ainda são exibidas.

Shell
copilot workflow run java-security-checks \
   --args @workflow-input.json \
   --result-file security-results.json \
   --allow-tool=read

O arquivo contém apenas o valor retornado, não as mensagens de progresso ou os detalhes da execução. Os caminhos relativos são resolvidos a partir do diretório em que você iniciou o comando.

O arquivo é gravado somente quando o fluxo de trabalho é concluído com êxito e retorna um resultado. Um arquivo existente é substituído somente após o novo resultado ter sido gravado com êxito. Uma execução pausada, com falha ou interrompida deixa inalterado qualquer arquivo existente.

Executando um fluxo de trabalho em um script

Para scripts e pipelines de CI/CD, configure a autenticação e as permissões antes de executar o comando. Você pode usar uma variável de ambiente de autenticação, como COPILOT_GITHUB_TOKEN. Consulte referência de comando da CLI GitHub Copilot.

Para carregar uma extensão de projeto quando o diretório de trabalho ainda não tiver sido marcado como confiável, defina GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true para essa invocação. Isso permite que o código de extensão do repositório seja executado. Use-o apenas para o código em que você confia. Você ainda deve conceder à ferramenta as permissões de que os agentes do fluxo de trabalho precisam.

Use --silent para suprimir a saída de progresso. Adicione --output-format json para receber um registro JSON que contém o nome do fluxo de trabalho, a ID de execução, o status e qualquer resultado retornado:

Shell
copilot --allow-tool=read workflow run java-security-checks \
   --args @workflow-input.json \
   --silent --output-format json

Criando um fluxo de trabalho dinâmico

Por padrão, Copilot cria um fluxo de trabalho em uma extensão para sua sessão atual. Em vez disso, você pode pedir que ele crie o fluxo de trabalho em uma extensão pessoal ou de projeto.

  1. Descreva o que você deseja que o fluxo de trabalho faça, a ordem necessária das etapas, em quais partes deve ser usado um agente e eventuais limitações. Por exemplo:

    Copilot prompt
    Create a dynamic workflow named review-changed that lists changed files, asks an agent to review them, and summarizes the findings.

    Observação

    Se você não fornecer um nome para o fluxo de trabalho, Copilot escolherá um durante a autoria.

  2. Dependendo das configurações atuais de aprovação de permissão, você será solicitado a permitir Copilot a criação de um novo fluxo de trabalho dinâmico. Escolha Sim.

Copilot pode solicitar outras aprovações enquanto trabalha na criação e no registro do fluxo de trabalho dinâmico.

  1. Após a conclusão do processo de criação, verifique se o fluxo de trabalho foi criado e registrado com êxito. Para fazer isso, pergunte Copilot quais fluxos de trabalho dinâmicos estão disponíveis.

Criar e registrar um fluxo de trabalho não inicia uma execução. Para usá-lo, consulte Executando um fluxo de trabalho dinâmico.

Você também pode escrever a extensão por conta própria, com orientação de Copilot. Para ler as orientações integradas, pergunte:

Copilot prompt
Show me the guidance for writing dynamic workflows.

Reutilizando e compartilhando fluxos de trabalho dinâmicos

Fluxos de trabalho dinâmicos são implementados como Copilot extensões. Por padrão, quando você solicita Copilot a criação de um fluxo de trabalho, sua extensão só está disponível nessa sessão. Um fluxo de trabalho também já pode estar armazenado em uma extensão pessoal ou de projeto.

Para reutilizar ou compartilhar um fluxo de trabalho que você criou na sessão atual, copie sua extensão para o diretório de extensões pessoais ou o diretório de extensões do repositório. Isso copia a definição, não o histórico de execuções ou o progresso salvo.

  1. Peça Copilot para informar o caminho para o fluxo de trabalho dinâmico que você deseja compartilhar. Por exemplo:

    Copilot prompt
    Tell me the path to the java-security-checks dynamic workflow.

Copilot responderá com um caminho como: /Users/yourname/.copilot/session-state/d58ba0bf-78fa-4172-b277-c18ba400e7c6/extensions/java-security-checks/extension.mjs

  1. Para disponibilizar esse fluxo de trabalho dinâmico em todas as sessões, copie o diretório que contém o extension.mjs arquivo em seu ~/.copilot/extensions/ diretório.

    Você pode pedir Copilot para fazer isso por você. Por exemplo:

    Copilot prompt
    Copy the java-security-checks workflow to my personal extensions directory.

  2. Como alternativa, para compartilhar o fluxo de trabalho dinâmico com todos que trabalham em um repositório, copie o diretório que contém o extension.mjs arquivo no .github/extensions/ diretório da cópia local do repositório.

    Mais uma vez, você pode pedir Copilot para fazer isso por você. Por exemplo, se você estiver trabalhando no repositório no qual deseja disponibilizar o fluxo de trabalho dinâmico:

    Copilot prompt
    Copy the java-security-checks workflow to the current repository's extensions directory.

    Depois que essa alteração for mesclada no repositório, os colegas de equipe poderão usar o fluxo de trabalho depois de atualizar a cópia local e carregar a extensão.

  3. Inicie uma nova sessão ou reinicie uma sessão existente. Quando a sessão terminar de carregar, peça para listar Copilot os fluxos de trabalho dinâmicos disponíveis para verificar se o fluxo de trabalho já está disponível.

Distribuição de fluxos de trabalho dinâmicos em um plugin

Os plug-ins fornecem uma maneira de distribuir a funcionalidade personalizada Copilot . Você pode usar um plug-in para adicionar fluxos de trabalho dinâmicos ao Copilot CLI e ao GitHub Copilot app.

Para obter mais informações, consulte Criando um plug-in para GitHub Copilot CLI.

Depois de criar um plug-in contendo seu fluxo de trabalho dinâmico e publicá-lo em um marketplace de plug-in, as pessoas poderão descobrir e instalá-lo. Consulte Localizando e instalando plug-ins para GitHub Copilot CLI.

Monitorar e gerenciar execuções de fluxos de trabalho dinâmicos

Você pode monitorar o progresso e o uso AI credits de uma execução, juntamente com todas as fases e os subagentes que o fluxo de trabalho relata. Você também pode consultar as execuções concluídas, pausar ou cancelar uma execução ativa e retomar uma execução que você pausou ou que foi interrompida ao atingir um limite.

Em Copilot CLI:

  1. Em uma sessão interativa, insira /workflows.

    As execuções atualmente em andamento e concluídas recentemente de fluxos de trabalho dinâmicos são listadas.

  2. Use as teclas de direção para mover a seleção e pressione Enter para abrir os detalhes de uma execução.

    Os detalhes incluem o período de tempo em que uma execução está ativa, qualquer fase atual relatada pelo fluxo de trabalho, o número de subagentes ativos no momento, o número total de subagentes gerados e o número de AI credits usados até agora.

  3. Em uma execução ativa, pressione P para pausar, X para cancelar a execução.

No Copilot app:

Observação

O monitoramento de execução só está disponível para sessões locais.

Se você estiver executando ou tiver executado um fluxo de trabalho dinâmico na sessão atual, um botão Fluxos de Trabalho será exibido acima da caixa de prompt.

  1. Clique no botão Fluxos de trabalho.

    Uma janela pop-up é exibida, listando execuções ativas, prontas para serem retomadas e concluídas recentemente.

  2. Clique em uma execução de fluxo de trabalho no pop-up.

    Um painel é exibido mostrando os detalhes da execução do fluxo de trabalho selecionado.

    Os detalhes incluem há quanto tempo uma execução está em andamento, qualquer fase atual informada pelo fluxo de trabalho, o número de subagentes ativos no momento, o número total de subagentes criados e o número de AI credits usados até agora.

  3. Para interromper uma execução ativa, clique em Cancelar. Para pausar, para que ele possa ser retomado mais tarde, clique em Pausar.

Monitorando fluxos de trabalho dinâmicos com o OTel

Se você tiver habilitado o OpenTelemetry (OTel), poderá inspecionar a atividade de fluxo de trabalho em seus rastreamentos. Um fluxo de trabalho cria um invoke_workflow intervalo sempre que é executado ou retomado, com a atividade de seus agentes vinculada a ele.

Para a configuração em Copilot CLI, consulte referência de comando da CLI GitHub Copilot.

Retomando uma execução

Você pode retomar uma execução pausada ou uma execução interrompida ao atingir um limite, se ela estiver listada como retomável. O fluxo de trabalho pode reutilizar resultados salvos de etapas e subagentes já concluídos, em vez de iniciar uma nova execução. O trabalho que não foi salvo pode precisar ser executado novamente.

Ao retomar uma execução que atingiu um limite, defina um total maior para esse limite. O uso antes da execução interrompida ainda conta para o novo total.

As execuções canceladas não podem ser retomadas.

Em Copilot CLI:

  1. Em uma sessão interativa, insira /workflows.
  2. Use as teclas de direção para mover a seleção para a execução pausada ou interrompida que você deseja retomar.
  3. Pressione R para retomar a execução.
  4. Se solicitado, aumente o limite atingido e confirme o novo total.

** Copilot appNo :**

  1. Em uma sessão que contém execuções de fluxo de trabalho dinâmico pausadas ou paradas, clique no botão Fluxos de trabalho, logo acima do campo de prompt.

    Todas as execuções retomáveis são listadas em uma seção "Pronto para retomar".

  2. Clique na execução que você deseja retomar.

  3. No painel lateral, clique em Continuar. Se a execução atingiu um limite, clique em Retomar com limite... Em vez disso, siga os prompts para definir um total maior e retomar.

Agendando uma execução de fluxo de trabalho dinâmico

Você pode agendar uma execução de fluxo de trabalho dinâmico na sua sessão atual Copilot CLI, como qualquer outro prompt, usando os comandos /after ou /every. Por exemplo:

Copilot prompt
/every 1d run the changed-files-report dynamic workflow on the 'main' branch, limiting it to 200 AI credits

Para obter mais informações, consulte Agendamento de prompts em GitHub Copilot CLI.