Configuração de agentes personalizados

Este artigo de referência fornece informações detalhadas de configuração para agentes personalizados. Para obter informações gerais sobre como criar agentes personalizados, consulte Criando agentes personalizados para Agente de nuvem Copilot.

Propriedades de frontmatter do YAML

A tabela a seguir destaca as propriedades que você pode configurar para perfis de agente em GitHub.com, no CLI do Copilot, e nos 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 agente personalizado finalidade e dos recursos |

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 agente personalizadotools propriedade controla quais ferramentas estão disponíveis para seu agente, incluindo as dos servidores MCP.

Você agente personalizado terá acesso às ferramentas do servidor MCP que foram configuradas em suas perfil do agente configurações e/ou nas configurações do repositório. Para obter mais informações sobre como configurar servidores MCP para agente de nuvem em um repositório, consulte Estendendo o agente de nuvem do GitHub Copilot com o PROTOCOLO MCP (Model Context Protocol).

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 nas perfil do agente e/ou nas configurações de 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 repositório tiver servidores MCP configurados, você poderá optar por disponibilizar apenas ferramentas específicas desses servidores.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/*.
  • Ferramentas de extensões podem usar o nome da VS Code 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 aliases de ferramenta a seguir estão disponíveis para agentes personalizados. Todos os aliases não diferenciam maiúsculas de minúsculas:

| Alias primário | Aliases compatíveis | Agente de nuvem Mapeamento | Propósito | | ------------- | -------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | execute | 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 | "Agente personalizado" Ferramentas | Permite que um diferente agente personalizado seja invocado para realizar uma tarefa. | | web | WebSearch, WebFetch | Atualmente não aplicável a agente de nuvem. | Permite buscar conteúdo de URLs e executar uma pesquisa na Web | | todo | TodoWrite | Atualmente não aplicável a agente de nuvem. | Cria e gerencia listas de tarefas estruturadas. Não tem suporte em agente de nuvem atualmente, mas tem suporte em VS Code. |

Nomes de ferramentas para servidores MCP "prontos para uso"

Os seguintes servidores MCP estão disponíveis prontos para uso imediato para Agente de nuvem Copilot e podem ser referenciados usando namespace.

          `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 perfil do agente a seguir mostra um agente com um servidor MCP e um segredo configurado. 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 mcp-servers propriedade em um perfil do agente é uma representação YAML do formato de configuração JSON usado para configurar servidores MCP para Agente de nuvem Copilot.

A maioria das sub-propriedades é igual à representação JSON. As seções a seguir descrevem as alterações desde a implementação inicial da configuração do MCP, sendo relevantes para agentes personalizados. Para obter mais informações sobre o formato de configuração JSON, consulte Estendendo o agente de nuvem do GitHub Copilot com o PROTOCOLO MCP (Model Context Protocol).

Tipo de servidor MCP

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

Segredos e variáveis de ambiente do servidor MCP

          Agente personalizado A configuração do MCP dá suporte às mesmas funcionalidades de substituição de variável de ambiente e segredo que as configurações de MCP existentes no nível do 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 dar suporte a padrões comuns usados no GitHub Actions Claude Code.

A configuração JSON do MCP no nível do repositório e a agente personalizado configuração yaml dão suporte aos 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 agente personalizado configuração yaml dá suporte aos 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
  

Configurações de exemplo 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

          Agentes personalizados Nomes

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

          Agente personalizado O controle de versão é baseado em SHAs de commit do Git para o arquivo perfil do agente. Isso permite que você crie ramificações ou marcas com versões diferentes de agentes personalizados quando necessário. Quando você atribuir 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, 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. Quando você configura 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 de MCP prontas para uso (como o GitHub MCP) são processadas primeiro, seguidas pela configuração mcp agente personalizado e, por fim, configurações mcp especificadas por meio de configurações de 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)