Configuração de agentes personalizados

Este artigo de referência fornece informações detalhadas de configuração para agentes personalizados. Para informações gerais sobre a criação de agentes personalizados, consulte Criando agentes personalizados para agente de codificação Copilot.

Propriedades de frontmatter do YAML

A tabela a seguir detalha as propriedades que você pode configurar para perfis de agente em GitHub.com, CLI do Copilot, e IDEs com suporte (a menos que observado de outra forma). Qualquer comportamento específico do ambiente é observado na descrição da propriedade. O nome do arquivo de configuração (menos .md ou .agent.md) é usado para eliminação de duplicação entre níveis para que a configuração de nível mais baixo tenha precedência.

          **String obrigatória**     | Descrição da finalidade e das capacidades do agente personalizado |

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.

Tools

A propriedade agente personalizado tools controla quais ferramentas estão disponíveis para seu agente, incluindo as de servidores MCP.

O agente personalizado terá acesso às ferramentas do servidor MCP que foram configuradas tanto no seu perfil do agente quanto nas configurações do repositório. Para obter mais informações sobre como configurar servidores MCP para o agente de codificação em um repositório, consulte Estendendo o agente de codificação do GitHub Copilot com o protocolo de contexto do modelo (MCP).

Você pode configurar tools usando as seguintes abordagens:

•         **Habilite todas as ferramentas disponíveis**: omita a `tools` propriedade inteiramente ou use `tools: ["*"]` para habilitar todas as ferramentas disponíveis. Isso incluirá todas as ferramentas de servidor MCP configuradas em perfil do agente e/ou nas configurações do repositório.
  

•         **Habilitar ferramentas específicas**: forneça uma lista de nomes de ferramentas ou aliases específicos (por exemplo, `tools: ["read", "edit", "search"]`) para habilitar apenas essas ferramentas. Para obter os aliases de ferramenta disponíveis, consulte [aliases de ferramenta](#tool-aliases) abaixo.
  

  • Observe que, se o seu repositório tiver servidores MCP configurados, você pode optar por disponibilizar apenas ferramentas específicas desses servidores para o seu agente personalizado. Os nomes de ferramentas de servidores MCP específicos podem ser prefixados com o nome do servidor seguido por um /. Por exemplo, some-mcp-server/some-tool.
  • Você também pode habilitar explicitamente todas as ferramentas de um servidor MCP específico usando some-mcp-server/*.
  • As ferramentas das extensões VS Code podem usar o nome da extensão como um proxy, como azure.some-extension/some-tool.

•         **Desabilitar todas as ferramentas**: use uma lista vazia (`tools: []`) para desabilitar todas as ferramentas do agente.
  

Todos os nomes de ferramentas não reconhecidos são ignorados, o que permite que ferramentas específicas do produto sejam especificadas em um perfil do agente sem causar problemas.

Aliases de ferramenta

Os seguintes aliases de ferramentas estão disponíveis para agentes personalizados. Todos os aliases não diferenciam maiúsculas de minúsculas:

          `shell`, `Bash`, `powershell`                         | Ferramentas do Shell: `bash` ou `powershell`                             | Execute um comando no shell apropriado para o sistema operacional.                                     |

| read | Read, NotebookRead | view | Ler o conteúdo do arquivo. | | edit | Edit, MultiEdit, , Write``NotebookEdit | Editar ferramentas: por exemplo str_replace, str_replace_editor | Permitir que LLM edite. Os argumentos exatos podem variar. | | search | Grep, Glob | search | Pesquise arquivos ou texto em arquivos. | | agent | custom-agent, Task | ferramentas "Agente personalizado" | Permite que um agente personalizado diferente seja invocado para realizar uma tarefa. | | web | WebSearch, WebFetch | Atualmente não aplicável ao agente de codificação. | Permite buscar conteúdo de URLs e executar uma pesquisa na Web | | todo | TodoWrite | Atualmente não aplicável ao agente de codificação. | Cria e gerencia listas de tarefas estruturadas. Não suportado em agente de codificação hoje, mas suportado por VS Code. |

Nomes de ferramentas para servidores MCP "prontos para uso"

Os seguintes servidores MCP estão disponíveis imediatamente para agente de codificação Copilot e podem ser referenciados usando namespaces:

          `github/*` inclui todos eles ou você pode referenciar `github/<tool name>` onde `<tool name>` está um valor da documentação do servidor MCP. |

| playwright | Todas as ferramentas do dramaturgo estão disponíveis por padrão, mas o servidor está configurado para acessar apenas o localhost. playwright/* inclui todos eles ou você pode referenciar playwright/<tool name> onde <tool name> está um valor da documentação do servidor MCP. Por padrão, o token ao qual ele tem acesso está no escopo do repositório de código-fonte. |

Detalhes da configuração do servidor MCP

O exemplo a seguir perfil do agente mostra um agente com um servidor MCP e uma senha configurada. Além disso, apenas uma ferramenta do servidor MCP foi habilitada na propriedade tools no Frontmatter YAML:

---
name: my-custom-agent-with-mcp
description: Custom agent description
tools: ['tool-a', 'tool-b', 'custom-mcp/tool-1']
mcp-servers:
  custom-mcp:
    type: 'local'
    command: 'some-command'
    args: ['--arg1', '--arg2']
    tools: ["*"]
    env:
      ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
---

Prompt with suggestions for behavior and output

A propriedade mcp-servers em um perfil do agente é uma representação YAML do formato de configuração JSON usado para configurar servidores MCP para agente de codificação Copilot.

A maioria das sub-propriedades é igual à representação JSON. As seções a seguir descrevem as alterações em relação à implementação inicial da configuração do MCP em agente de codificação Copilot que são relevantes para agentes personalizados. Para obter mais informações sobre o formato de configuração JSON, consulte Estendendo o agente de codificação do GitHub Copilot com o protocolo de contexto do modelo (MCP).

Tipo de servidor MCP

Para compatibilidade, o tipo stdio usado por Claude Code e VS Code é mapeado para o tipo local de agente de codificação.

Segredos e variáveis de ambiente do servidor MCP

A configuração Agente personalizado do MCP oferece suporte às mesmas funcionalidades de substituição de variáveis ​​de ambiente e segredos que as configurações existentes do MCP em nível de repositório. Semelhante às configurações no nível do repositório, segredos e variáveis podem ser obtidos do ambiente "copilot" nas configurações do repositório. A sintaxe para referenciar esses valores foi expandida para suportar padrões comuns usados em GitHub Actions e Claude Code.

Tanto a configuração JSON do MCP em nível de repositório quanto a configuração YAML agente personalizado suportam os seguintes padrões de sintaxe:

•         `$COPILOT_MCP_ENV_VAR_VALUE` - Variável de ambiente e cabeçalho
  

•         `${COPILOT_MCP_ENV_VAR_VALUE}` - Variável de ambiente e cabeçalho (sintaxe de Claude Code)
  

•         `${COPILOT_MCP_ENV_VAR_VALUE:-default}` - Variável de ambiente e cabeçalho com padrão
  

A configuração YAML agente personalizado suporta os seguintes padrões de sintaxe adicionais:

•         `${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}` - Variável de ambiente e cabeçalho
  

•         `${{ vars.COPILOT_MCP_ENV_VAR_VALUE }}` - Variável de ambiente e cabeçalho
  

Exemplo de configurações perfil do 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.

---
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.

---
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.

---
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.

---
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.

Processamento de agentes personalizados

nomes de Agentes personalizados

No caso de conflitos de nomenclatura, a configuração de nível mais baixo substitui as configurações de nível superior. Isso significa que um agente no nível do repositório teria precedência sobre um agente no nível da organização e o agente no nível da organização substituiria um agente de nível empresarial.

Controle de versão

O controle de versão Agente personalizado baseia-se nos SHAs de commit do Git para o arquivo perfil do agente. Isso permite criar ramificações ou tags com diferentes versões de agentes personalizados conforme necessário. Ao atribuir um agente personalizado a uma tarefa, o agente personalizado será instanciado usando a versão mais recente do perfil do agente para esse repositório e branch. Quando o agente cria uma solicitação de pull request, as interações dentro da solicitação de pull usam a mesma versão do agente personalizado para consistência.

Processamento de ferramentas

A tools lista filtra o conjunto de ferramentas que são disponibilizadas para o agente, sejam elas internas ou provenientes de servidores MCP. Ao configurar as ferramentas em seu perfil do agente, o comportamento depende do que você especificar:

• Se nenhuma ferramenta for especificada, todas as ferramentas disponíveis estarão habilitadas
• Uma lista de ferramentas vazia (tools: []) desabilita todas as ferramentas
• Uma lista específica (tools: [...]) habilita apenas essas ferramentas

Configurações do servidor MCP

Para configurações de servidor MCP, há uma ordem de processamento específica que garante o comportamento de substituição adequado: as configurações MCP prontas para uso padronizadas (como GitHub MCP) são processadas primeiro, seguidas pela configuração agente personalizado MCP e, por fim, configurações MCP especificadas por meio de configurações do repositório. Isso permite que cada nível substitua as configurações do nível anterior conforme apropriado.

Leitura adicional

•         [AUTOTITLE](/copilot/how-tos/copilot-cli)
  

•         [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference)