Criando agentes personalizados para Agente de codificação do Copilot

Você pode criar agentes especializados com experiência personalizada para tarefas de desenvolvimento específicas.

Quem pode usar esse recurso?

O Agente de codificação do Copilot está disponível com os planos GitHub Copilot Pro, GitHub Copilot Pro+, GitHub Copilot Business e GitHub Copilot Enterprise. O agente está disponível em todos os repositórios armazenados no GitHub, exceto os repositórios pertencentes ao contas de usuário gerenciadas e em locais em que foi explicitamente desabilitado.
Sign up for Copilot

Neste artigo

Agentes personalizados possibilitam que você adapte a expertise do Copilot para tarefas específicas. Para uma visão geral conceitual de agentes personalizados, consulte Sobre agentes personalizados.

Observação

Agentes personalizados estão em versão prévia pública para IDEs JetBrains, Eclipse e Xcode e estão sujeitos a alterações.

Criando um perfil agente personalizado em um repositório em

  1. Navegue até a guia agentes em https://GitHub.com/copilot/agents.

  2. Use o menu suspenso na caixa de prompt para selecionar o repositório em que você quer criar o perfil de agente personalizado.

    Observação

    Os proprietários de organizações e empresas podem criar agentes personalizados no nível da organização e da empresa em um repositório .GitHub-private que está disponível em todos os repositórios dentro de sua organização ou empresa. Para saber mais, confira Preparando-se para usar agentes personalizados em sua empresa e Preparando-se para usar agentes personalizados em sua organização.

  3. Opcionalmente, selecione o ramo no qual você deseja criar o perfil do agente perfil do agente. O padrão é a ramificação principal.

  4. Clique em e clique em Criar um agente. Isso abrirá um perfil de agente de modelo chamado my-agent.agent.md no .GitHub/agents diretório do repositório de destino.

  5. Se estiver criando um agente personalizado de nível organizacional ou empresarial, exclua a parte .GitHub/ do caminho do arquivo para mover o modelo para o diretório raiz agents.

  6. Edite o nome do arquivo (o texto anterior .agent.md), selecionando um nome exclusivo e descritivo que identifica a finalidade do agente. Observe que o nome do arquivo pode conter apenas os seguintes caracteres: ., , -, _, , a-z, A-Z. 0-9

  7. Configure o perfil do agente, incluindo o nome, a descrição, as ferramentas e os prompts. Para mais informações sobre o que o perfil do agente pode incluir, veja Configuração de um perfil do agente.

  8. Confirme o arquivo no repositório e faça a mesclagem na ramificação padrão. Volte para a guia Agentes e atualize a página, caso necessário. O agente personalizado agora será exibido no menu suspenso ao clicar em na caixa de prompt.

Criando um perfil agente personalizado em Visual Studio Code

  1. Abra o GitHub Copilot Chat (Chat do GitHub Copilot) no Visual Studio Code.
  2. No menu suspenso de agentes na parte inferior da visualização do chat, selecione Configurar agentes personalizados... e clique em Criar novo agente personalizado.
  3. Defina o local onde o perfil do agente será criado: * Workspace: crie o perfil agente personalizado na pasta .GitHub/agents do workspace para que ele seja utilizado apenas nesse espaço. * Perfil do usuário: crie o perfil agente personalizado na pasta de perfil do usuário atual para que ele seja utilizado em todos os workspaces.
  4. Insira um nome de arquivo para o agente personalizado. O nome padrão exibido no menu suspenso de agentes.
  5. Configure o perfil do agente no arquivo .agent.md recém-criado, adicionando a descrição, as ferramentas e os prompts. Para mais informações sobre o que o perfil do agente pode incluir, veja Configuração de um perfil do agente.
    • Você pode usar o botão Configurar Ferramentas... no editor para abrir a caixa de diálogo "Configurar Ferramentas", onde você pode exibir e selecionar ferramentas disponíveis, incluindo ferramentas internas e ferramentas de servidores MCP. Clique OK para adicionar as ferramentas selecionadas ao perfil do agente.
    • Para configurar qual modelo de IA o agente utilizará, insira a propriedade model: e escolha o modelo desejado no menu suspenso de preenchimento automático.

Para atualizar um perfil do agente, selecione Configurar agentes personalizados no menu suspenso de agentes e clique em um agente da lista para alterá-lo. Para obter mais detalhes sobre agentes personalizados em VS Code, consulte Agentes personalizados em VS Code.

Criar um perfil agente personalizado em IDEs do JetBrains

  1. Abra a janela GitHub Copilot Chat (Chat do GitHub Copilot) no IDE do JetBrains.
  2. No menu suspenso de agentes na parte inferior da visualização do chat, clique em Configurar agentes... e, na janela de configurações, em "Agentes de chat", cliquem em Workspace.
  3. Insira um nome de arquivo para o agente personalizado. O nome padrão exibido no menu suspenso de agentes.
  4. Configure o perfil do agente no arquivo .agent.md recém-criado no diretório .GitHub/agents, adicionando a descrição, as ferramentas e os prompts. Para mais informações sobre o que o perfil do agente pode incluir, veja Configuração de um perfil do agente.
    • Você pode usar o botão Configurar Ferramentas... no editor para abrir a caixa de diálogo ferramentas, onde você pode exibir e selecionar ferramentas disponíveis, incluindo ferramentas internas e ferramentas de servidores MCP. Clique em Aplicar para adicionar as ferramentas selecionadas ao perfil do agente.
    • Para configurar qual modelo de IA o agente utilizará, insira a propriedade model: e escolha o modelo desejado no menu suspenso de preenchimento automático.

Para atualizar um perfil do agente, selecione Configurar agentes personalizados no menu suspenso de agentes e clique em ao lado do agente que quer editar.

Criando um perfil agente personalizado no Eclipse

  1. Abra a janela GitHub Copilot Chat (Chat do GitHub Copilot) no Eclipse.
  2. No menu suspenso de agentes na parte inferior da visualização do chat, selecione Configurar agentes... e clique em Adicionar....
  3. Insira um nome de arquivo para o agente personalizado. O nome padrão exibido no menu suspenso de agentes.
  4. Configure o perfil do agente no arquivo .agent.md recém-criado no diretório .GitHub/agents, adicionando a descrição, as ferramentas e os prompts. Para mais informações sobre o que o perfil do agente pode incluir, veja Configuração de um perfil do agente.
    • Você pode usar o botão Configurar Ferramentas... no editor para abrir a caixa de diálogo "Configurar Ferramentas", onde você pode exibir e selecionar ferramentas disponíveis, incluindo ferramentas internas e ferramentas de servidores MCP. Clique em Aplicar para adicionar as ferramentas selecionadas ao perfil do agente.
    • Para configurar qual modelo de IA o agente utilizará, insira a propriedade model: e escolha o modelo desejado no menu suspenso de preenchimento automático.

Para atualizar um perfil do agente, selecione Configurar agentes... no menu suspenso de agentes, escolha o agente que você quer alterar e clique em Editar.

Criando um perfil agente personalizado no Xcode

  1. Abra a janela GitHub Copilot Chat (Chat do GitHub Copilot) no Xcode.
  2. No menu suspenso de agentes na parte inferior da visualização do chat, clique em Criar um agente.
  3. Insira um nome de arquivo para o agente personalizado. O nome padrão exibido no menu suspenso de agentes.
  4. Configure o perfil do agente no arquivo .agent.md recém-criado no diretório .GitHub/agents, adicionando a descrição, as ferramentas e os prompts. Para mais informações sobre o que o perfil do agente pode incluir, veja Configuração de um perfil do agente.
    • Você pode usar o botão Personalizar Agente dentro do editor de arquivos para abrir uma caixa de diálogo, onde você pode selecionar o modelo de IA para o agente usar, selecionar ferramentas disponíveis (incluindo ferramentas internas e de servidor MCP) e configurar a handoffs propriedade para a transição entre agentes personalizados. Clique em Aplicar para adicionar opções selecionadas aos dados perfil do agente.

Para atualizar um perfil do agente, no menu suspenso de agentes, clique no ícone de lápis ao lado do agente que você quer alterar.

Configurar um perfil do agente

Um perfil do agente é um arquivo Markdown com frontmatter YAML que especifica o nome, a descrição, as ferramentas disponíveis e as configurações do servidor MCP do agente personalizado. Configurar um perfil do agente requer definir a identidade do agente, suas capacidades, o acesso às ferramentas e as instruções de comportamento.

Para informações completas de configuração relacionadas a propriedades YAML, ferramentas, configuração de servidores MCP, aliases de ferramenta e processamento de agentes personalizados, consulte Configuração de agentes personalizados.

Como configurar o perfil do agente:

  1. Se preferir, defina um name para o agente personalizado. Se não for definido, o nome assumirá o nome do arquivo por padrão (sem o sufixo .md ou .agent.md).
  2. Escreva um resumo description (obrigatório) explicando o que seu agente faz e seus recursos específicos ou conhecimento de domínio.
  3. Na propriedade tools, defina quais ferramentas o agente pode usar. Esta é uma lista de nomes ou aliases de ferramentas, abrangendo também as ferramentas de servidores MCP configurados nas definições do repositório ou no perfil do agente (por exemplo, tools: ["read", "edit", "search", "some-mcp-server/tool-1"]). Caso você omita essa propriedade, o agente terá acesso a todas as ferramentas disponíveis. Consulte "Ferramentas" em Configuração de agentes personalizados.
  4. Opcionalmente, na mcp-servers propriedade, você pode configurar servidores MCP que estarão disponíveis apenas para esse agente para estender seus recursos. Consulte "Detalhes de configuração do servidor MCP" em Configuração de agentes personalizados.
  5. Se você estiver criando e usando o perfil do agente no VS Code, nas IDEs do JetBrains, Eclipse ou Xcode, também poderá usar a propriedade model para controlar qual modelo de IA o agente deve usar.
  6. Opcionalmente, defina a propriedade target para vscode ou GitHub-copilot se você deseja usar o agente apenas em um ambiente específico. O agente estará disponível em ambos os ambientes se você omitir a propriedade.
  7. Escreva o prompt do agente. Defina o comportamento, a competência e as instruções do agente no conteúdo Markdown, localizado abaixo do frontmatter YAML. O prompt pode ter no máximo 30.000 caracteres.

Exemplo de perfis de agente

Os exemplos a seguir demonstram a aparência de um perfil do agente para as tarefas comuns de escrever testes ou planejar a implementação de um projeto. Para obter inspiração adicional, consulte os exemplos Agentes personalizados na biblioteca de customização. Você também pode encontrar exemplos mais específicos na coleção da comunidade awesome-copilot.

Especialista em testes

Este exemplo habilita todas as ferramentas omitindo a tools propriedade.

Text
---
name: test-specialist
description: Focuses on test coverage, quality, and testing best practices without modifying production code
---

You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:

- Analyze existing tests and identify coverage gaps
- Write unit tests, integration tests, and end-to-end tests following best practices
- Review test quality and suggest improvements for maintainability
- Ensure tests are isolated, deterministic, and well-documented
- Focus only on test files and avoid modifying production code unless specifically requested

Always include clear test descriptions and use appropriate testing patterns for the language and framework.

Planejador de implementação

Este exemplo habilita apenas um subconjunto de ferramentas.

Text
---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:

- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines
- Document API designs, data models, and system interactions
- Create markdown files with structured plans that development teams can follow

Always structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

Usar agentes personalizados

Depois de criar um agente personalizado, você poderá usá-lo sempre que Agente de codificação do Copilot estiver disponível.

  • Ao solicitar uma tarefa ao Agente de codificação do Copilot em GitHub.com, utilize o menu suspenso no painel de agentes ou na guia de agentes para escolher o agente personalizado no lugar do agente de codificação padrão.
  • Ao designar o Agente de codificação do Copilot a uma issue, é possível escolher o agente personalizado no menu suspenso para lidar com a issue usando a configuração especializada.
  • Ao utilizar o CLI do GitHub Copilot, é possível selecionar um agente personalizado específico usando o comando de barra /agent ou fazendo referência ao agente em um prompt ou por um argumento da linha de comando. Para saber mais, confira Usando GitHub Copilot CLI.

Quando o Copilot abrir pull requests, será informado qual agente personalizado executou o trabalho na descrição de pull request.

Para obter mais informações sobre como usar Agente de codificação do Copilot, consulte Como pedir para o GitHub Copilot criar uma pull request.

Usando agentes personalizados em seu IDE

Você também pode usar seus perfis personalizados perfis de agente diretamente em IDEs com suporte, incluindo Visual Studio Code, IDEs do JetBrains, Eclipse e Xcode. É possível alternar entre os agentes personalizados pelo menu suspenso de agentes na janela de Chat, o que oferece acesso a configurações especializadas para diferentes tarefas, como planejamento, edição de código ou pesquisa.

Note que certas propriedades podem ter comportamentos distintos ou serem desconsideradas entre o GitHub.com e os ambientes de IDE. Para obter mais informações sobre as propriedades com suporte, consulte Configuração de agentes personalizados.

Para mais detalhes sobre os agentes personalizados em VS Code especificamente, consulte Agentes personalizados em VS Code na documentação VS Code.

Próximas etapas