En este artículo de referencia se expone información detallada para la configuración de agentes personalizados. Para obtener información general sobre cómo crear agentes personalizados, consulte Creación de agentes personalizados para Agente de programación Copilot.
Nota:
Agentes personalizados se encuentran en versión preliminar pública para los IDEs de JetBrains, Eclipse y Xcode y pueden estar sujetos a cambios.
Propiedades del frontmatter de YAML
En la tabla siguiente se describen las propiedades que puede configurar para perfiles de agente en GitHub.com, la CLI de Copilot y los IDE admitidos (salvo que se indique lo contrario). Cualquier comportamiento específico del entorno se indica en la descripción de la propiedad. El nombre del archivo de configuración (menos .md o .agent.md) se usa para la desduplicación entre niveles para que la configuración de nivel más bajo tenga prioridad.
| Propiedad | Tipo | Propósito |
|---|---|---|
name | cuerda / cadena | Nombre visible de agente personalizado. Optional. |
description |
**Cadena necesaria** | Descripción de la finalidad y funcionalidades de agente personalizado |
| target | cuerda / cadena | Entorno o contexto de destino de agente personalizado (vscode o github-copilot). Si no se define, el valor predeterminado se aplica a ambos entornos. |
| tools | lista de cadenas, cadena | Lista de nombres de herramientas que puede usar agente personalizado. Admite una cadena separada por comas y una matriz de cadenas yaml. Si no se define, el valor predeterminado se aplica a todas las herramientas. Consulte Herramientas. |
| model | cuerda / cadena | Modelo que se usará cuando se ejecute este agente personalizado. Si no se establece, hereda el modelo predeterminado. |
| disable-model-invocation | boolean | Deshabilita Agente de programación Copilot para usar automáticamente este agente personalizado en función del contexto de la tarea. Cuando true, el agente debe seleccionarse manualmente. El valor disable-model-invocation: true es equivalente a infer: false. Si se establecen ambos, disable-model-invocation tiene prioridad. Si no se establece, el valor predeterminado es false. |
| user-invocable | boolean | Controla si este agente personalizado puede ser seleccionado por un usuario. Cuando false, el agente no se puede seleccionar manualmente y solo se puede acceder a él a través de programación. Si no se establece, el valor predeterminado es true. |
| infer | boolean | Retirado. Utilice disable-model-invocation y user-invocable en su lugar. Habilita Agente de programación Copilot para usar automáticamente este agente personalizado en función del contexto de la tarea. Cuando false, el agente debe seleccionarse manualmente. Si no se establece, el valor predeterminado es true. |
| mcp-servers | objeto | Servidores y herramientas MCP adicionales que debe usar agente personalizado.
Tampoco se usa en VS Code y en otros IDE agentes personalizados. |
| metadata | objeto que consiste en un par de nombre y valor, ambos son cadenas | Permite la anotación del agente con datos útiles.
Tampoco se usa en VS Code y en otros IDE agentes personalizados. |
Defina el comportamiento, la experiencia y las instrucciones del agente en el contenido de Markdown debajo del frontmatter de YAML. El mensaje puede tener un máximo de 30 000 caracteres.
Nota:
- Las propiedades
argument-hintyhandoffsde VS Code y agentes personalizados de otros IDE no se admiten actualmente para Agente de programación Copilot en GitHub.com. Se omiten para garantizar la compatibilidad. - Para obtener más información sobre la estructura de archivos de agente personalizado en VS Code, consulte Agentes personalizados en VS Code en la documentación sobre VS Code.
Tools
La propiedad agente personalizado tools controla las herramientas disponibles para el agente, incluidas las provenientes de los servidores MCP.
Su agente personalizado tendrá acceso a las herramientas del servidor MCP que se han configurado tanto en su perfil de agente como en la configuración del repositorio. Para obtener más información sobre cómo configurar servidores MCP para codificar el agente en un repositorio, consulte Extensión del agente de codificación de GitHub Copilot con el protocolo de contexto de modelo (MCP).
Puede configurar tools mediante los métodos siguientes:
-
**Habilitar todas las herramientas disponibles**: omita la `tools` propiedad por completo o use `tools: ["*"]` para habilitar todas las herramientas disponibles. Esto incluirá todas las herramientas del servidor MCP configuradas en el perfil del agente perfil de agente y/o la configuración del repositorio. -
**Habilitar herramientas específicas**: proporcione una lista de nombres o alias de herramientas específicos (por ejemplo, `tools: ["read", "edit", "search"]`) para habilitar solo esas herramientas. Para conocer los alias de herramientas disponibles, consulte [Alias de](#tool-aliases) herramientas a continuación.- Tenga en cuenta que si en su repositorio hay configurados servidores MCP, puede elegir que solo algunas herramientas de esos servidores estén disponibles para el agente personalizado. Los nombres de herramientas de servidores MCP específicos se pueden prefijar con el nombre del servidor seguido de .
/Por ejemplo:some-mcp-server/some-tool. - También puede habilitar explícitamente todas las herramientas desde un servidor MCP específico mediante
some-mcp-server/*. - Las herramientas de las extensiones de VS Code pueden usar el nombre de la extensión como proxy, como por ejemplo,
azure.some-extension/some-tool.
- Tenga en cuenta que si en su repositorio hay configurados servidores MCP, puede elegir que solo algunas herramientas de esos servidores estén disponibles para el agente personalizado. Los nombres de herramientas de servidores MCP específicos se pueden prefijar con el nombre del servidor seguido de .
-
**Deshabilitar todas las herramientas**: use una lista vacía (`tools: []`) para deshabilitar todas las herramientas del agente.
Se omiten todos los nombres de herramientas no reconocidos, lo que permite especificar herramientas específicas del producto en un perfil de agente sin causar problemas.
Alias de herramientas
Los siguientes alias de herramienta están disponibles para agentes personalizados. Todos los alias no distinguen mayúsculas de minúsculas:
| Alias principal | Alias compatibles | Asignación de Agente de codificación | Propósito |
|---|---|---|---|
execute |
`shell`, , `Bash`, `powershell` | Herramientas de Shell: `bash` o `powershell` | Ejecute un comando en el shell adecuado para el sistema operativo. |
| read |
Read, NotebookRead | view | Leer el contenido del archivo. |
| edit |
Edit, MultiEdit, , Write, NotebookEdit | Editar herramientas: por ejemplo str_replace, , str_replace_editor | Permite que el LLM edite. Los argumentos exactos pueden variar. |
| search |
Grep, Glob | search | Busque archivos o texto en archivos. |
| agent |
custom-agent, Task | Herramientas de "Agente personalizado" | Permite invocar un agente personalizado diferente para realizar una tarea. |
| web |
WebSearch, WebFetch | Actualmente no se aplica a agente de programación. | Permite capturar contenido de direcciones URL y realizar una búsqueda web |
| todo | TodoWrite | Actualmente no se aplica a agente de programación. | Crea y administra listas de tareas estructuradas. No es compatible con agente de programación, pero sí lo es con VS Code. |
Nombres de herramientas para servidores MCP "listos para usar"
Los siguientes servidores MCP están disponibles de forma predeterminada para Agente de programación Copilot y se puede apuntar a ellos mediante el espacio de nombres:
| Nombre del servidor MCP | Herramientas disponibles |
|---|---|
github | Todas las herramientas de solo lectura están disponibles por defecto, pero el token que recibe el servidor es específico al ámbito del repositorio de origen. |
`github/*` incluye todos ellos, o puede hacer referencia a `github/<tool name>` dónde `<tool name>` es un valor de la documentación del servidor MCP. |
| playwright | Todas las herramientas de playwright están disponibles de forma predeterminada, pero el servidor está configurado para acceder solo a localhost.
playwright/* incluye todos ellos, o puede hacer referencia a playwright/<tool name> dónde <tool name> es un valor de la documentación del servidor MCP. De forma predeterminada, el token al que tiene acceso está en el ámbito del repositorio de código fuente. |
Detalles de configuración del servidor MCP
En el ejemplo siguiente perfil de agente se muestra un agente con un servidor MCP y un secreto configurado. Además, solo se ha habilitado una herramienta del servidor MCP en la tools propiedad del frontmatter de 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
La propiedad mcp-servers en un perfil de agente es una representación YAML del formato de configuración JSON utilizado para configurar servidores MCP para Agente de programación Copilot.
La mayoría de las subpropiedades son las mismas que la representación JSON. En las secciones siguientes se describen los cambios de la implementación inicial de la configuración de MCP en Agente de programación Copilot que sirven para agentes personalizados. Para obtener más información sobre el formato de configuración JSON, consulte Extensión del agente de codificación de GitHub Copilot con el protocolo de contexto de modelo (MCP).
Tipo de servidor MCP
Por motivos de compatibilidad, el tipo stdio utilizado por Claude Code y VS Code se asigna al tipo local de agente de programación.
Variables de entorno y secretos del servidor MCP
Nota:
Si el servidor MCP requiere secretos o variables de entorno, estos elementos deben configurarse en el entorno Copilot en cada repositorio donde se utilizará el agente personalizado. Para obtener más información sobre cómo configurar variables de entorno, consulte Personalización del entorno de desarrollo para el agente de codificación GitHub Copilot.
La configuración de MCP de Agente personalizado admite la misma variable de entorno y funcionalidades de reemplazo de secretos que las configuraciones de MCP de nivel de repositorio existentes. De forma similar a las configuraciones de nivel de repositorio, los secretos y las variables se pueden obtener desde el entorno "copilot" en la configuración del repositorio. La sintaxis para hacer referencia a estos valores se ha ampliado para admitir patrones comunes usados en GitHub Actions y Claude Code.
Tanto la configuración JSON de MCP de nivel de repositorio como la configuración YAML de agente personalizado admiten la siguiente sintaxis:
-
`$COPILOT_MCP_ENV_VAR_VALUE` - Variable de entorno y encabezado -
`${COPILOT_MCP_ENV_VAR_VALUE}` - Variable de entorno y encabezado (sintaxis de Claude Code) -
`${COPILOT_MCP_ENV_VAR_VALUE:-default}` - Variable de entorno y encabezado con el valor predeterminado
La configuración de agente personalizado YAML admite los siguientes patrones de sintaxis adicionales:
-
`${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}` - Variable de entorno y encabezado -
`${{ vars.COPILOT_MCP_ENV_VAR_VALUE }}` - Variable de entorno y encabezado
Ejemplo de configuraciones de perfil de agente
En los ejemplos siguientes se muestra lo que un perfil de agente podría parecer para las tareas comunes de realizar pruebas o planificar la implementación de un proyecto. Para obtener más inspiración, consulte los ejemplos de Agentes personalizados en la biblioteca de personalización. También puede encontrar ejemplos más específicos en la colección de comunidad awesome-copilot .
Especialista en pruebas
En este ejemplo se habilitan todas las herramientas omitiendo la tools propiedad .
--- 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.
Planificador de implementación
En este ejemplo solo se habilita un subconjunto de herramientas.
--- 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.
Procesamiento de agentes personalizados
Nombres de Agentes personalizados
En el caso de conflictos de nomenclatura, la configuración de nivel más bajo invalida las configuraciones de nivel superior. Esto significa que un agente de nivel de repositorio tendría prioridad sobre un agente de nivel de organización y el agente de nivel de organización invalidaría un agente de nivel empresarial.
Control de versiones
El control de versiones de Agente personalizado se basa en SHA de confirmación de Git para el archivo del perfil de agente. Esto le permite crear ramas o etiquetas con diferentes versiones de agentes personalizados, según sea necesario. Al asignar un agente personalizado a una tarea, se creará una instancia de perfil de agente utilizando la versión más reciente del perfil de agente para ese repositorio y rama. Cuando el agente crea una solicitud de incorporación de cambios, las interacciones dentro de la solicitud usan la misma versión del agente personalizado para garantizar la coherencia.
Procesamiento de herramientas
La tools lista filtra el conjunto de herramientas que están disponibles para el agente, ya sea integrado o de origen de los servidores MCP. Al configurar herramientas en el perfil de agente, el funcionamiento dependerá de lo que se especifique.
- Si no se especifica ninguna herramienta, se habilitan todas las herramientas disponibles.
- Una lista de herramientas vacía (
tools: []) deshabilita todas las herramientas - Una lista específica (
tools: [...]) solo habilita esas herramientas
Configuraciones de servidor MCP
Para configuraciones del servidor MCP, hay un orden de procesamiento específico que garantiza un comportamiento de sobrescritura adecuado: las configuraciones de MCP predeterminadas (como MCP de GitHub) se procesan primero, seguidas de la configuración de MCP de agente personalizado y, por último, las configuraciones de MCP especificadas en los ajustes del repositorio. Esto permite que cada nivel invalide la configuración del nivel anterior según corresponda.
Lectura adicional
-
[AUTOTITLE](/copilot/how-tos/copilot-cli) -
[AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference)