Configuração de agentes personalizados

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

Propriedades de frontmatter do YAML

A tabela a seguir destaca as propriedades que você pode configurar para agent profiles em GitHub.com, no Copilot CLIe 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.

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

Você custom agent terá acesso às ferramentas do servidor MCP que foram configuradas em suas agent profile configurações e/ou nas configurações do repositório. Para obter mais informações sobre como configurar servidores MCP de repositórios compartilhados no GitHub, consulte Configurar servidores MCP para seu repositório.

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 agent profile 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 abaixo.
  • Observe que, se o repositório tiver servidores MCP configurados, você poderá optar por disponibilizar apenas ferramentas específicas desses servidores.custom agent 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 agent profile sem causar problemas.

Aliases de ferramenta

Os aliases de ferramenta a seguir estão disponíveis para custom agents. Todos os aliases não diferenciam maiúsculas de minúsculas:

| Alias primário | Aliases compatíveis | Cloud agent 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 | "Custom agent" Ferramentas | Permite que um diferente custom agent seja invocado para realizar uma tarefa. | | web | WebSearch, WebFetch | Atualmente não aplicável a cloud agent. | Permite buscar conteúdo de URLs e executar uma pesquisa na Web | | todo | TodoWrite | Atualmente não aplicável a cloud agent. | Cria e gerencia listas de tarefas estruturadas. Não tem suporte em cloud agent 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 Copilot cloud agent e podem ser referenciados usando namespacing.

Detalhes da configuração do servidor MCP

O exemplo agent profile 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 propriedade mcp-servers em um agent profile é uma representação YAML do formato de configuração JSON usado para configurar servidores MCP para repositórios em GitHub.

A maioria das sub-propriedades é igual à representação JSON. As seções a seguir descrevem as alterações na implementação inicial da configuração do MCP nos repositórios em GitHub que são relevantes para custom agents. Para obter mais informações sobre o formato de configuração JSON, consulte Configurar servidores MCP para seu repositório.

Tipo de servidor MCP

Para compatibilidade, o stdio tipo usado por Claude Code e VS Code é mapeado para o tipo cloud agent do local.

Segredos e variáveis de ambiente do servidor MCP

Custom agent 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 em nível do repositório, segredos e variáveis podem ser obtidos a partir de segredos e variáveis dos Agentes para Copilot cloud agent, configurados em nível de organização e de 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 custom agent 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 custom agent 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 agent profile

Os exemplos a seguir demonstram a aparência de um agent profile para as tarefas comuns de escrever testes ou planejar a implementação de um projeto. Para obter inspiração adicional, consulte os exemplos Custom agents 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 custom agents

Custom agents 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

Custom agent O controle de versão é baseado em SHAs de commit do Git para o arquivo agent profile. Isso permite que você crie ramificações ou marcas com versões diferentes de custom agents quando necessário. Quando você atribuir custom agent a uma tarefa, o custom agent será instanciado usando a versão mais recente do agent profile para esse repositório e ramificação. Quando o agente cria uma solicitação de pull, as interações dentro da solicitação de pull usam a mesma versão do custom agent 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 agent profile, 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 custom agent 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

• GitHub Copilot CLI
• referência de comando da CLI GitHub Copilot