O que você vai aprender: Como instalar e autenticar a extensão oficial do Microsoft Copilot Studio no VS Code, contornar o ponto onde a maioria trava no sign-in, clonar seu primeiro agente e entender o que o conceito de harness muda nesse fluxo. Editar componentes e sincronizar alterações de volta com o Copilot Studio fica para o próximo artigo.

Pré-requisitos

O Limite de Criar Agentes Só Pelo Portal Web

O portal do Copilot Studio resolve bem a criação inicial de um agente. O problema aparece quando o agente cresce: dezenas de tópicos, várias ações e conectores, mais de uma pessoa mexendo na mesma definição. Navegar entre telas para achar um tópico específico consome tempo, e não existe um jeito nativo de saber quem alterou o quê, quando, ou de reverter uma mudança que quebrou o comportamento esperado.

Isso não é um problema exclusivo do Copilot Studio: é o mesmo motivo pelo qual qualquer projeto de desenvolvimento sério não vive só na nuvem. Como em qualquer projeto de desenvolvimento, vale ter uma versão local do agente e a possibilidade de configurar e trabalhar offline, sem ficar refém da disponibilidade do servidor da Microsoft para isso. Se o portal estiver lento, fora do ar ou passando por manutenção, um fluxo local não trava sua capacidade de revisar ou preparar a próxima alteração.

É esse o motivo real para adotar a extensão do Copilot Studio no VS Code. Não é sobre preferência de editor: é sobre trazer práticas de engenharia de software (controle de versão, revisão por pares, trabalho offline) para dentro de um processo que hoje vive quase inteiramente no navegador.

O Que a Extensão Realmente Traz Para o Fluxo de Trabalho

A extensão oficial do Copilot Studio para VS Code conecta o editor diretamente aos seus agentes na nuvem. Na prática, ela permite:

Este artigo não entra no detalhe de como usar cada um desses recursos: editar componentes e sincronizar alterações rendem um tutorial próprio. Aqui o objetivo é fechar a etapa que precede tudo isso: instalar a extensão, autenticar corretamente e clonar seu primeiro agente, sem travar no caminho.

A Mudança Recente: Entenda o Conceito de Harness

Antes de instalar qualquer coisa, vale entender uma peça que mudou recentemente na forma como o Copilot Studio descreve seus próprios recursos: o harness.

Segundo a documentação oficial, harness é o runtime que existe entre o agente que você desenha e o modelo de linguagem que ele usa. Você define tópicos, ações e regras; o harness decide quando chamar o modelo, quais componentes enviar a ele, como interpretar a resposta e qual ferramenta acionar em seguida. Diferentes harnesses mudam o que o agente consegue fazer e como o uso é cobrado.

A Microsoft descreve três harnesses hoje:

Por que isso importa para quem vai configurar a extensão no VS Code: a própria documentação da extensão traz uma nota explícita informando que os recursos de clonagem, edição e sincronização hoje são potencializados pelo standard harness. Ou seja, o fluxo que este artigo ensina a configurar está, neste momento, alinhado ao harness de agentes baseados em regras, não ao GitHub Copilot harness, que é a opção voltada para processos de negócio mais complexos e multietapas. Se o seu agente evoluir para um cenário que exige raciocínio livre, manipulação de arquivos ou orquestração de múltiplas ferramentas, vale revisitar qual harness ele está usando antes de assumir que o fluxo local se comporta da mesma forma.

Colocando em Prática: Instalando a Extensão

Existem dois caminhos oficiais para instalar a extensão. Os dois levam ao mesmo resultado.

Método 1: Pela aba Extensions do VS Code

1. Abra a aba Extensions (Ctrl+Shift+X).
2. Busque por "Copilot Studio". Confirme que o publisher é Microsoft.
3. Selecione a extensão e clique em Install.
4. Se o VS Code pedir para recarregar, clique em Reload.
5. Confirme a instalação: o ícone do Copilot Studio deve aparecer na barra de atividades lateral.

Método 2: Pelo Marketplace web

1. Acesse https://marketplace.visualstudio.com/ e busque por "Copilot Studio", ou use o link direto https://marketplace.visualstudio.com/items?itemName=ms-CopilotStudio.vscode-copilotstudio.
2. Clique em Install na página do marketplace.
3. Permita que o navegador abra o VS Code e confirme a instalação pelo ícone na barra de atividades.

📌 Por que isso importa: confirmar o publisher evita instalar uma extensão homônima ou não oficial. O Copilot Studio manipula credenciais de acesso ao seu tenant, então vale o cuidado extra nesse passo.

Configuração Inicial e Sign-in: Onde Quase Todo Mundo Trava

Com a extensão instalada, o fluxo oficial de primeira configuração é:

1. Clique no ícone do Copilot Studio na barra de atividades. Um aviso pede que você faça sign-in.
2. Clique em Sign In no aviso e depois em Allow. O navegador padrão abre a página de autenticação da Microsoft.
3. Informe suas credenciais e complete a MFA, se exigida.
4. Revise as permissões solicitadas (ler e escrever agentes do Copilot Studio, acessar informações do ambiente e sincronizar arquivos com a nuvem) e selecione Accept.
5. Volte ao VS Code. O painel carrega os ambientes e agentes aos quais você tem acesso.

Na prática, foi exatamente aqui que travei ao configurar pela primeira vez por isso indico seguir pelo caminho abaixo caso tenham o mesmo problema.

Se o diálogo de permissão não aparecer ou a autenticação falhar

A documentação oficial lista um caminho alternativo e algumas causas comuns:

• Abra o Command Palette (Ctrl+Shift+P) e execute Copilot Studio: Sign In diretamente, sem depender do clique no ícone.

• Limpe cache e cookies do navegador para microsoft.com.
• Tente autenticar em um navegador diferente do padrão.
• Desative temporariamente extensões de navegador que possam bloquear a autenticação (bloqueadores de pop-up, por exemplo).
• Verifique proxy e firewall corporativo: em ambientes de rede restritiva, a autenticação pode falhar silenciosamente.
• Confirme que a conta usada é de um tipo suportado pela sua organização.

Como Confirmar Que a Configuração Funcionou

Depois da autenticação, o painel Agents deve mostrar uma estrutura parecida com esta:

AGENTS
  └─ Grupo de ambiente (ex.: developer, default, sandbox, production)
      ├─ Ambiente 1
      │   ├─ Agente 1
      │   └─ Agente 2
      └─ Ambiente 2
          └─ Agente 3

Se o sign-in funcionou mas essa estrutura aparece vazia, o problema deixou de ser autenticação e passou a ser permissão: verifique se sua conta tem acesso ao ambiente do Power Platform e se você tem permissão de leitura sobre os agentes daquele ambiente. Um administrador de Power Platform que restringiu o acesso ao ambiente ou não liberou o Copilot Studio para o tenant também bloqueia essa listagem, mesmo com o login concluído sem erros.

Clonando Seu Primeiro Agente

Com o ambiente certo aparecendo no painel Agents, o passo seguinte é trazer a definição do agente para o seu computador. O clone não substitui o portal: ele cria uma cópia editável dos arquivos que hoje só existem na nuvem.

Antes de clonar, escolha bem a pasta

• Use um caminho sem espaços quando possível. Espaços são suportados, mas evite quando puder.
• Prefira uma pasta já rastreada pelo Git, ou inicialize o Git logo depois de clonar.
• Garanta espaço em disco suficiente: o tamanho varia conforme o número de componentes do agente.

Pelo painel Agents (recomendado)

1. Abra a extensão do Copilot Studio na barra de atividades, ou use Ctrl+Shift+P e execute Copilot Studio: Focus on Agents View.
2. No painel Agents, selecione o ambiente que contém o agente desejado.
3. Clique com o botão direito no agente e selecione Clone agent.
4. Escolha ou crie uma pasta local no seletor de arquivos e confirme.
5. Aguarde a notificação de sucesso. O processo costuma levar entre 10 e 30 segundos.
6. Confirme que a pasta abriu no Explorer do VS Code e que o painel Source Control mostra a árvore de trabalho limpa.

O que realmente vem na pasta clonada

O clone traz a definição completa do agente, não uma exportação parcial:

meu-agente/
├── actions/                      # Conectores
├── knowledge/files/               # Fontes de conhecimento
├── topics/                        # Tópicos de conversa
├── workflows/                     # Ferramentas e ações do agente
├── trigger/                       # Gatilhos de evento
├── agent.mcs.yaml                 # Definição principal do agente
├── icon.png                       # Ícone do agente
├── settings.mcs.yml               # Configurações do agente
└── connectioreferences.mcs.yml    # Referências de conexão usadas por conectores

📌 É essa estrutura que permite versionar o agente com Git com granularidade real, arquivo por arquivo, em vez de depender de uma exportação única e opaca feita pelo portal.

Quando Vale a Pena Trabalhar Assim

Configurar a extensão é rápido; decidir se vale adotar esse fluxo no dia a dia é a parte que exige critério.

Faz sentido quando:

• Mais de uma pessoa mexe no mesmo agente e você precisa de histórico de mudanças e revisão via pull request.
• O agente já tem tópicos e ações suficientes para tornar a navegação pelo portal lenta.
• Sua equipe já usa Git para outros projetos e quer aplicar a mesma disciplina aqui.
• Você quer poder revisar, comentar e preparar alterações mesmo sem depender da disponibilidade do portal do Copilot Studio.

Ainda faz sentido usar só o portal web quando:

• O agente é simples, mantido por uma única pessoa, sem necessidade real de versionamento.
• O time não tem prática de Git: nesse caso, adotar a extensão sem essa base tende a criar mais atrito do que ganho.

Para contextualizar a utilidade prática desse fluxo, vale saber que a extensão trabalha com três operações de sincronização entre o local e a nuvem: 

Preview (visualizar mudanças remotas sem aplicá-las), Get (baixar mudanças da nuvem) e Apply (enviar mudanças locais para o Copilot Studio).

O detalhe de como usar cada uma delas fica para o próximo artigo desta série; o que importa aqui é entender que a configuração que você acabou de fazer é a base para esse ciclo funcionar depois.

Fechamento

Com a extensão instalada, autenticada, o ambiente correto aparecendo no painel Agents e o primeiro agente já clonado, a configuração está pronta. O próximo passo (editar os componentes em YAML e sincronizar as alterações com segurança) eu apresentarei em breve.

Se você ainda está decidindo entre criar um agente pelo Agent Builder do Microsoft 365 Copilot ou já partir para o Copilot Studio, veja Como Criar um Agente no Microsoft 365 Copilot.

Referências

• Overview da extensão Copilot Studio para VS Code
• Instalar e configurar a extensão
• Escolher um harness
• Clonar o agente no VS Code
• Sincronizar alterações