O que é o modo de plano do GitHub Copilot

Concluído

Dica

Consulte a guia Texto e imagens para obter mais detalhes!

GitHub Copilot em Visual Studio Code fornece três agentes internos, cada um operando em um nível diferente de autonomia e com uma relação diferente com seu workspace:

• Agente: um agente de implementação totalmente autônomo. Ele decompõe uma meta em subtarefas, executa chamadas de ferramenta (leituras de arquivo, gravações, comandos de terminal, chamadas de servidor MCP) e aplica alterações diretamente ao seu workspace. O loop do Agente é executado até que o objetivo seja alcançado ou até que encontre uma ambiguidade que não consiga resolver.
• Perguntar: um agente de perguntas e respostas sem estado com acesso somente leitura ao espaço de trabalho. Ele pode raciocinar sobre seu código, explicar conceitos e sugerir abordagens, mas nunca grava ou executa nada.
• Plano: um agente que prioriza o raciocínio e opera em um modelo de duas fases deliberadas. A pesquisa e a síntese vêm primeiro, depois a implementação, com uma porta de revisão humana obrigatória entre as duas fases.

A distinção que importa para o trabalho de operações não é apenas sobre segurança. Trata-se de onde, no loop do agente, o julgamento humano se encontra. Com o Agente, você revisa a saída posteriormente. Com o agente de Planejamento, você revisa e aprova a abordagem antes que qualquer chamada de ferramenta que modifique o estado seja feita.

Como o agente do plano opera internamente

O agente de Planejamento é uma instância de um padrão de agente mais amplo chamado planejar e executar, onde o raciocínio sobre o que fazer é separado da execução. Entender como o agente coleta informações em cada estágio ajuda você a escrever prompts melhores e interpretar sua saída de forma mais crítica.

Fase 1: Coleta de contexto

Quando você envia um prompt, o agente de plano não gera um plano imediatamente. Primeiro, ele constrói um modelo de contexto do seu ambiente invocando um conjunto de ferramentas somente leitura em sequência:

• Enumeração de arquivos do espaço de trabalho: o agente examina a árvore de arquivos do seu espaço de trabalho para entender a estrutura do projeto. Quais idiomas, estruturas e arquivos de configuração estão presentes.
• Leituras de arquivo de destino: com base na árvore de arquivos, o agente lê arquivos relevantes para sua solicitação. Para um prompt de infraestrutura, ele lê os módulos Bicep existentes, arquivos de parâmetros e qualquer bicepconfig.json. Para um prompt do PowerShell, ele lê os scripts existentes, manifestos de módulos e configuração PSScriptAnalyzer.
• Instruções personalizadas: o agente lê .github/copilot-instructions.md se ele existe na raiz do workspace. Esse arquivo é tratado como um contexto autoritário que molda cada plano que o agente gera nesse espaço de trabalho.
• Memória da sessão: o agente lê /memories/session/ para pegar qualquer contexto do início da mesma conversa. Planos anteriores, respostas para esclarecer perguntas ou fatos que você afirmou anteriormente.

Nenhuma chamada de rede externa é feita para sites de documentação ou APIs durante essa fase. O conhecimento do agente sobre serviços Azure, APIs do PowerShell ou sintaxe Bicep vem de seus dados de treinamento, não de pesquisas dinâmicas.

Fase 2: Esclarecer perguntas

Se o contexto coletado na Fase 1 for insuficiente para produzir um plano inequívoco, o agente fará perguntas de esclarecimento. Essas perguntas não são geradas aleatoriamente. Eles correspondem aos pontos de decisão na implementação em que respostas diferentes levam a planos significativamente diferentes.

Para um prompt de operações, os pontos de decisão típicos incluem:

• Escopo: qual assinatura, grupo de recursos ou servidor é o alvo?
• Dependências: o novo recurso precisa referenciar algo que já existe ou deve criar suas próprias dependências?
• Restrições: existem convenções de nomenclatura, requisitos de conformidade ou limites de orçamento que descartam determinadas abordagens?
• Estratégia de teste: o plano deve incluir uma etapa de validação de execução a seco ou de hipóteses e, em caso afirmativo, em relação a qual ambiente?

A qualidade das perguntas feitas pelo agente é um sinal útil. Se o agente não fizer perguntas de esclarecimento e produzir imediatamente um plano para um prompt complexo e pouco especificado, trate o plano resultante com atenção redobrada. Ele fez suposições que podem não corresponder ao seu ambiente.

Fase 3: Síntese de plano

Com contexto suficiente, o agente sintetiza um plano estruturado. O que envolve o raciocínio sobre:

• Ordenação de dependência: quais recursos ou etapas de configuração devem ser criados antes que outras pessoas possam referenciá-los.
• Superfície de risco: quais etapas são reversíveis e quais não são e onde as portas de verificação devem ser colocadas.
• Alinhamento de Ferramentas: quais comandos CLI do Azure, cmdlets do PowerShell ou construções de Bicep são apropriados considerando as restrições e os padrões existentes encontrados no espaço de trabalho.
• Encerramento da verificação: Quais evidências confirmariam que cada etapa foi bem-sucedida e como essa evidência pode ser coletada sem intervenção humana.

A saída do plano é gravada em /memories/session/plan.md automaticamente, tornando-a disponível para referência durante o restante da conversa.

Fase 4: Iteração

O plano não é final após a primeira geração. Cada prompt de acompanhamento que você envia faz com que o agente reentra na fase de síntese com o contexto atualizado. Incluindo o plano anterior, seus comentários e quaisquer novas restrições que você introduziu são considerados. O agente não reinicia do zero; ele trata o plano anterior como um plano prévio que pode ser alterado.

Esse loop iterativo é onde o modo Planejar adquire a maior parte de seu valor para o trabalho de operações. Os requisitos que surgem no meio da conversa podem ser incorporados sem perder o contexto estabelecido em turnos anteriores.

Acessar o agente do Plano

Você pode acessar o agente do Plano de duas maneiras:

• Seletor de agente: abra a visualização de Chat (Ctrl+Alt+I), e selecionePlano na lista suspensa de agentes.
• Comando de barra: digite /plan seguido da descrição da sua tarefa na caixa de entrada do chat. Por exemplo:

/plan Create a PowerShell script to audit all expired user accounts in Active Directory

Como é um plano

Quando o agente do plano gera um plano, ele normalmente produz três seções:

• Resumo: uma visão geral de alto nível do que o plano realiza e da abordagem que ele adota. Escrito para ser compreensível por implementadores técnicos e stakeholders não técnicos.
• Etapas de implementação: tarefas ordenadas que descrevem quais arquivos criar ou modificar, qual código gravar e como os componentes se conectam entre si. As etapas são sequenciadas para respeitar as dependências. Por exemplo, uma sub-rede deve existir antes que um NSG possa referenciá-la.
• Etapas de verificação: ações para confirmar se a implementação funciona corretamente, como executar az deployment what-if, validar a conformidade do DSC com Test-DscConfigurationou verificar a integridade do recurso após a implantação. As etapas de verificação têm o escopo definido para que possam ser executadas sem a necessidade de acesso à produção.

Por exemplo, se você pedir ao agente de Plano para criar uma política de marcação de grupo de recursos Azure, o plano poderá incluir etapas para criar um arquivo JSON de definição de política, atribuir a política a um grupo de gerenciamento e verificar a conformidade executando um comando CLI do Azure.

Onde os planos são armazenados

O agente de Plano salva automaticamente seu plano de implementação em um arquivo de memória de sessão em /memories/session/plan.md. Você pode acessar esse arquivo executando o comando Chat: Mostrar Arquivos de Memória na Paleta de Comandos e selecionando plan.md. Como a memória da sessão é limpada quando a sessão termina, o plano não está disponível em sessões posteriores. Se você precisar preservar um plano, copie-o para um arquivo em seu repositório antes de fechar a sessão.

Modo Plano versus Modo Agente

A diferença entre o modo de plano e o modo de agente não é principalmente sobre a funcionalidade. Ambos têm acesso ao mesmo modelo subjacente. A diferença reside na posição da revisão humana no ciclo de agentes e no contrato de efeitos colaterais sob o qual cada modo opera.

Dimensão	Agente de planificação	Agente
Efeitos colaterais durante o raciocínio	Nenhum; somente leitura	Grava arquivos, executa comandos, chama ferramentas
Barreira de revisão humana	Antes de qualquer implementação começar	Após a conclusão da implementação (ou durante, se ocorrerem erros)
Reversibilidade do estado da tarefa intermediária	Sempre reversível; nenhuma alteração feita	Depende do que foi executado
Adequado para fluxos de trabalho de gerenciamento de alterações	Sim; o plano é o artefato submetido para aprovação	Não; a saída é o artefato, que pode já ter sido aplicado
Uso da janela de contexto	Inferior; nenhuma chamada de ferramenta resulta das etapas de implementação	Maior; acumula resultados de chamadas de ferramenta executadas
Manipulação de ambiguidade	Identifica ambiguidades em forma de perguntas antes de continuar	Faz suposições e prossegue; pode falhar ou exigir reversão

A implicação prática para as equipes de operações é a seguinte: quando uma tarefa envolve vários recursos interdependentes, etapas irreversíveis (como alterações de esquema de banco de dados ou modificações de regra de firewall) ou requer uma trilha de aprovação documentada, o modo de plano é a escolha estruturalmente correta, não apenas a mais segura.

Use o modo Agent quando a tarefa é limitada, o estado do workspace é facilmente reversível e a iteração rápida importa mais do que uma abordagem pré-aprovada.

Entregar à implementação

Depois de finalizar um plano, você terá várias opções para continuar:

• Implemente na mesma sessão: selecione Iniciar Implementação para permitir que o Agente implemente o plano diretamente em seu workspace. O Agente recebe o documento de plano como seu contexto inicial e começa a executar as etapas de implementação.
• Continue na CLI Copilot: selecione Iniciar Implementação>Continue na CLI Copilot para executar a implementação como uma sessão em segundo plano. O Copilot CLI cria uma árvore de trabalho Git; uma cópia isolada do seu repositório no commit atual. Portanto, a implementação é executada em um estado limpo sem afetar sua árvore de trabalho.
• Continuar em um agente na nuvem: transfere para um agente na nuvem do Copilot em execução na infraestrutura do GitHub. O agente de nuvem implementa o plano real, abre uma solicitação de pull, cria o pipeline de CI/CD e estabelece um registro de aprovação auditável.

O mecanismo de transferência é significativo arquiteturalmente: o documento de plano gravado em /memories/session/plan.md torna-se a especificação da tarefa do agente de implementação. A qualidade e a especificidade do plano controla diretamente a qualidade da implementação. Um plano vago produz uma implementação vaga e um plano com portões de verificação explícitos faz com que o agente de implementação pause e verifique em cada portão antes de continuar.