Criar agentes do GitHub Copilot personalizados no Visual Studio Code

  • 8 minutos

Os agentes personalizados são assistentes de IA especializados que você configura para funções ou fluxos de trabalho específicos no Visual Studio Code. Cada agente encapsula um conjunto de instruções e permissões de ferramenta que orientam o comportamento do GitHub Copilot a agir como um tipo específico de especialista. Quando você seleciona um agente personalizado no GitHub Copilot Chat, a IA adota a persona desse agente, segue suas diretrizes e usa apenas as ferramentas atribuídas a ele.

O que são agentes do GitHub Copilot personalizados?

Um agente personalizado é uma configuração personalizada que transforma o GitHub Copilot Chat em um assistente específico de função. Em vez de depender do comportamento de uso geral, um agente personalizado opera de acordo com as instruções e restrições que você define. Por exemplo, você pode criar um agente "Revisor de Segurança" que analisa o código para vulnerabilidades, um agente "Gravador de Teste" que se concentra na geração de testes de unidade ou um agente "Planner" que produz planos de implementação sem modificar nenhum arquivo.

Agentes personalizados foram introduzidos como um recurso avançado no Visual Studio Code (disponível a partir da versão 1.106 do Visual Studio Code, anteriormente conhecida como "modos de chat personalizados"). Eles dão aos desenvolvedores controle refinado sobre como a IA opera em diferentes contextos de desenvolvimento. Cada agente aparece no menu suspenso de agentes do GitHub Copilot Chat, onde você pode selecioná-lo para alternar o modo da IA a qualquer momento.

Os agentes personalizados podem ser armazenados em dois locais:

  • Agentes do workspace: Armazenados na pasta .github/agents/ de seu repositório. Esses agentes são compartilhados com sua equipe por meio do controle de versão, garantindo que todos no projeto tenham acesso aos mesmos assistentes especializados.

  • Agentes de perfil do usuário: armazenados na pasta de prompts do perfil de usuário do Visual Studio Code. Esses agentes são pessoais e estão disponíveis em todos os seus espaços de trabalho, úteis para agentes que refletem suas preferências individuais de fluxo de trabalho.

Examinar como os agentes personalizados funcionam

Um agente personalizado é um arquivo Markdown com uma .agent.md extensão. O Visual Studio Code detecta automaticamente qualquer arquivo .agent.md na pasta .github/agents/ do seu workspace (ou no seu perfil de usuário) e os carrega como agentes disponíveis na interface do Chat do GitHub Copilot.

Cada arquivo de agente consiste em duas partes:

  • Um cabeçalho de frontmatter YAML: Esta seção especifica metadados, incluindo o nome do agente, uma descrição que aparece na interface de bate-papo, as ferramentas que ele pode usar, uma preferência de modelo opcional e configurações de transferência para conexão com outros agentes.

  • Um corpo markdown: Esta seção contém as instruções e o contexto do agente. O conteúdo é anexado a cada prompt de usuário sempre que o agente estiver ativo, orientando como o GitHub Copilot interpreta e responde às solicitações. Você escreve essas instruções no mesmo estilo de linguagem natural usado para arquivos de instrução personalizados.

Campos de frontmatter do agente

O frontmatter YAML dá suporte aos seguintes campos para configurar o comportamento do agente:

Campo DESCRIÇÃO
description Uma breve descrição é exibida como texto de preenchimento no campo de entrada do chat quando o agente é selecionado.
name Um nome de exibição opcional. Se omitido, o nome do arquivo (sem .agent.md) será usado.
tools Um conjunto de ferramentas que o agente pode usar, como ['read', 'edit', 'search']. Omitir esse campo dá acesso a todas as ferramentas disponíveis.
model Um modelo de IA preferencial. Pode ser uma única cadeia de caracteres de ID de modelo ou uma matriz de IDs de modelo para fallback (por exemplo, ['o4-mini', 'gpt-4.1']).
agents Uma matriz de nomes de agente que podem ser invocados como subagentes por esse agente.
handoffs Um conjunto de configurações de transferência que definem as transições para outros agentes (abordado na próxima unidade).
argument-hint Texto da dica exibido no campo de entrada do chat, descrevendo o que o usuário deve digitar para o agente.
user-invokable Um valor booleano que controla se o agente aparece na lista suspensa de agentes. Defina como false para criar agentes que só podem ser chamados como subagentes por outros agentes. Usa true como padrão.
disable-model-invocation Quando definido como true, o agente não envia prompts para o modelo de idioma. Útil para agentes que executam ações somente por meio de ferramentas.
target Especifica o ambiente de execução do agente: client (é executado no Visual Studio Code, o padrão) ou cloud (é executado na nuvem).
mcp-servers Um objeto que define servidores MCP (Model Context Protocol) aos quais o agente deve ter acesso. Os servidores MCP estendem os recursos do agente conectando-se a ferramentas externas e fontes de dados.

O exemplo a seguir mostra a estrutura de um arquivo de agente personalizado usando vários desses campos:

---
description: Reviews code for security vulnerabilities and suggests improvements
tools: ['search', 'read']
---
# Security Reviewer

You are a senior security engineer. When the user provides code or asks you to review files, analyze the code for common security vulnerabilities including:

- SQL injection
- Cross-site scripting (XSS)
- Authentication and authorization flaws
- Insecure data handling
- Hardcoded credentials or secrets

Provide your findings as a structured list with severity levels (Critical, High, Medium, Low). For each finding, explain the vulnerability, show the affected code, and suggest a secure alternative.

Do not modify any files. Your role is advisory only.

Quando um desenvolvedor seleciona esse agente no GitHub Copilot Chat, todas as interações usam essas instruções. O agente "sabe" que deve se concentrar na análise de segurança e não tentará editar arquivos porque suas instruções e conjunto de ferramentas o restringem a operações somente leitura.

Definir recursos do agente com ferramentas

O tools campo no frontmatter YAML controla quais ações o agente pode executar. As ferramentas determinam se o agente pode ler arquivos, editar código, pesquisar a base de código, executar comandos de terminal ou acessar outros recursos. Ao personalizar a lista de ferramentas, você garante que cada agente execute apenas ações relevantes para sua função.

As ferramentas comuns incluem:

Tool DESCRIÇÃO
read Ler o conteúdo de arquivo do workspace
edit Modificar arquivos no workspace
search Pesquisar nos arquivos do espaço de trabalho
fetch Recuperar conteúdo de URLs
terminal Executar comandos no terminal
agent Invocar outros agentes como subagentes

Se você omitir o campo tools totalmente, o agente terá acesso por padrão a todas as ferramentas padrão. No entanto, listar explicitamente as ferramentas é uma prática recomendada porque cria limites claros para o comportamento do agente. Um agente de planejamento que não deve modificar o código deve especificar apenas ['search', 'read', 'fetch'], enquanto um agente de implementação que precisa escrever código incluiria ['search', 'read', 'edit', 'terminal'].

Observação

Se uma ferramenta listada na configuração do agente não estiver disponível no ambiente atual, ela será ignorada silenciosamente. Isso significa que você pode definir agentes com ferramentas que podem estar disponíveis apenas em determinadas configurações sem causar erros.

Subagentes

O agents campo no frontmatter YAML permite que um agente invoque outros agentes como subagentes. Um subagente é um agente que outro agente chama para lidar com uma subtarefa e incorpora o resultado em sua própria resposta. Esse comportamento é diferente de uma transferência de responsabilidade, que transfere o controle para o usuário; uma chamada de subagente ocorre dentro do processamento do agente e retorna o resultado automaticamente para o agente que fez a chamada.

Por exemplo, um agente "Desenvolvedor Líder" pode invocar um subagente "Revisor de Segurança" para verificar um trecho de código, receber as descobertas e então incorporá-las em sua resposta final, tudo dentro de uma única interação.

Para configurar subagentes, liste os nomes de subagentes no agents campo:

---
description: Lead developer agent that coordinates with specialists
tools: ['search', 'read', 'edit']
agents: ['security-reviewer', 'test-writer']
---

Os agentes destinados apenas ao uso como subagentes podem configurar user-invokable: false para que não apareçam no menu de agentes, mantendo a interface limpa.

Observação

Para usar subagentes, inclua a ferramenta agent na lista tools do agente chamador (ou omita o campo tools inteiramente para ativar todas as ferramentas). A agent ferramenta permite que um agente chame outro programaticamente durante sua resposta.

Agentes de nível de organização

Para equipes que mantêm agentes compartilhados em vários repositórios, o GitHub dá suporte a agentes de nível de organização. Esses agentes são configurados no nível da organização do GitHub e aparecem automaticamente ao lado de agentes de workspace e perfil de usuário no Visual Studio Code quando você está conectado a uma conta do GitHub com acesso à organização.

Os agentes de nível de organização garantem a consistência entre as equipes. Por exemplo, uma equipe de segurança pode publicar um agente compartilhado "Revisor de Segurança" que todo repositório na organização pode usar, garantindo que os mesmos critérios de revisão de segurança sejam aplicados em todos os lugares sem exigir que cada repositório defina seu próprio agente.

Compatibilidade de formato do agente

O Visual Studio Code reconhece arquivos de agente no formato .agent.md como configuração primária. Além disso, o Visual Studio Code dá suporte a arquivos de agente Claude-style que seguem o formato Claude Code. Se você já tiver configurações de agente do Claude Code, elas funcionarão no GitHub Copilot Chat do Visual Studio Code sem modificação. Essa compatibilidade cruzada simplifica a migração para equipes que usam várias ferramentas de IA.

Agentes internos versus personalizados

O Visual Studio Code inclui vários agentes internos que fornecem configurações de uso geral para chat. Esses agentes incluem o agente "GitHub Copilot" padrão e agentes especializados para tarefas comuns. Os agentes personalizados estendem esse sistema permitindo que você defina suas próprias funções com instruções específicas do projeto e configurações de ferramentas.

Os agentes personalizados aparecem na lista suspensa de agentes do GitHub Copilot Chat, juntamente com os agentes integrados. Você pode alternar entre qualquer agente a qualquer momento para alterar a forma como a IA opera. Essa flexibilidade permite que você se mova entre diferentes modos de trabalho — planejamento, codificação, revisão, teste — sem sair da interface de Chat do GitHub Copilot.

A principal vantagem dos agentes personalizados em relação aos agentes internos é a especificidade. Um agente de revisão de código interno aplica práticas recomendadas gerais, enquanto o agente personalizado "Revisor de Código" pode aplicar a lista de verificação de revisão específica da sua equipe, referenciar as decisões arquitetônicas do projeto e focar nos padrões e antipadrões que mais importam em sua base de código.

Etapas para criar um agente personalizado

Siga estas etapas para criar um agente personalizado no Visual Studio Code:

  1. Abra o menu de agentes: No painel do GitHub Copilot Chat, abra o menu suspenso de agentes (que normalmente mostra o nome do agente atual). Selecione Configurar Agentes Personalizados e, em seguida, escolha Criar novo agente personalizado. Como alternativa, execute o Chat: New Custom Agent comando na Paleta de Comandos (Ctrl+Shift+P).

  2. Escolha o escopo: selecione onde armazenar o arquivo do agente. Escolha Workspace para criar o arquivo .github/agents/ (disponibilizando-o para sua equipe por meio do controle de versão) ou escolha o perfil do usuário para torná-lo pessoal e disponível em todos os seus workspaces.

  3. Nomeie o agente: insira um nome de arquivo descritivo para o agente. Esse nome aparece como o nome padrão na lista suspensa de agentes. Use um nome que indique claramente a função do agente, como planner, code-reviewerou test-writer.

  4. Defina os metadados do agente: no frontmatter YAML do arquivo recém-criado .agent.md , configure as propriedades do agente. Defina um description (esse texto aparece como texto de espaço reservado na entrada do chat quando o agente é selecionado), especifique o tools ao qual o agente deve ter acesso e, opcionalmente, defina um model preferencial ou configure handoffs para outros agentes.

  5. Escreva as instruções do agente: no corpo do arquivo abaixo do frontmatter YAML, forneça as instruções personalizadas para o agente. Essas instruções definem a persona, a experiência e as diretrizes comportamentais do agente. Escreva-as no Markdown usando uma linguagem clara e específica que informa à IA como abordar tarefas, no que se concentrar e em quais restrições seguir.

  6. Salvar e ativar: salve o arquivo. O agente personalizado aparece imediatamente na lista suspensa de agentes do GitHub Copilot Chat (considerando que user-invokable seja true, que é o padrão). Selecione o agente para começar a usá-lo.

Dica

Você pode digitar /agents no GitHub Copilot Chat como um atalho rápido para visualizar e alternar entre todos os agentes disponíveis, incluindo agentes integrados, de espaço de trabalho, de perfil de usuário e de nível organizacional.

Habilidades do agente

As habilidades dos agentes são um conceito relacionado, mas distinto dos agentes personalizados. Embora os agentes definam uma persona com instruções e ferramentas, as habilidades do agente (definidas em SKILL.md arquivos) descrevem recursos específicos ou áreas de conhecimento nas quais um agente pode se basear. As habilidades fornecem metadados estruturados sobre o que um agente sabe e pode fazer. O Visual Studio Code dá suporte a habilidades como parte de seu sistema de personalização mais amplo. As competências normalmente são definidas em seu ambiente de trabalho e detectadas automaticamente pelo GitHub Copilot para aprimorar as respostas do assistente com conhecimento especializado.

Exemplos de agentes personalizados

Os exemplos a seguir ilustram como definir agentes para funções de desenvolvimento comuns.

Agente "Planner"

Um agente do Planner concentra-se na análise de requisitos e na geração de planos de implementação sem modificar nenhum código. Ele usa apenas ferramentas de leitura apenas e inclui uma transferência para um agente de implementação quando o plano estiver pronto para ser executado.

---
description: Generates high-level implementation plans without writing code
tools: ['search', 'read', 'fetch']
handoffs:
  - label: Start Implementation
    agent: implementer
    prompt: Now implement the plan outlined above.
    send: false
---
# Planner

You are a senior software architect. When the user describes a feature or change, analyze the request and generate a detailed implementation plan.

Your plan should include:
1. A summary of the feature requirements.
2. A list of files that need to be created or modified.
3. Step-by-step implementation tasks in logical order.
4. Any potential risks or considerations.

Do not write or modify any code. Focus on planning only. Ask clarifying questions if the requirements are ambiguous.

Agente "Revisor de Código"

Um agente do Revisor de Código examina o código quanto a problemas de qualidade, vulnerabilidades de segurança e adesão às práticas recomendadas. Ele usa ferramentas de leitura e pesquisa, mas não edita arquivos diretamente.

---
description: Reviews code for bugs, security issues, and style compliance
tools: ['search', 'read']
---
# Code Reviewer

You are an experienced code reviewer. When the user asks you to review code, examine it for:

- Bugs and logical errors
- Security vulnerabilities (SQL injection, XSS, authentication flaws)
- Performance issues
- Naming convention violations
- Missing error handling
- Code duplication

Present your findings as a structured review with severity levels. For each issue, explain the problem, show the affected code, and suggest an improvement. End with an overall assessment of code quality.

Esses exemplos podem ser adaptados para atender às necessidades específicas de sua equipe. O princípio principal é definir instruções claras que concentrem o agente em uma tarefa específica e configurem a lista de ferramentas para corresponder às responsabilidades do agente.

Resumo

Agentes personalizados no Visual Studio Code permitem definir personas de IA especializadas com instruções personalizadas e permissões de ferramenta. Ao criar .agent.md arquivos em seu workspace ou perfil de usuário, você pode criar agentes para funções de desenvolvimento específicas: planejamento, implementação, revisão, teste e muito mais. Cada agente opera dentro dos limites definidos, usando apenas as ferramentas que você permite e seguindo as instruções fornecidas. Recursos avançados, como subagentes, agentes de nível de organização e integração de servidor MCP, ampliam as capacidades dos agentes. Esses recursos fornecem controle preciso sobre como o GitHub Copilot se comporta em diferentes estágios do fluxo de trabalho de desenvolvimento.