Configuración de agentes personalizados

En este artículo de referencia se proporciona información detallada de configuración para custom agents. Para obtener información general sobre cómo crear custom agents, vea Creación de agentes personalizados para Copilot cloud agent.

Propiedades del frontmatter de YAML

En la tabla siguiente se describen las propiedades que puede configurar para agent profiles en GitHub.com, en Copilot CLI y en los IDE admitidos (a menos 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.

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.

Tools

La custom agenttools propiedad controla qué herramientas están disponibles para el agente, incluidas las de los servidores MCP.

custom agent tendrá acceso a las herramientas del servidor MCP que se han configurado tanto en su configuración de agent profile como en el repositorio. Para obtener más información sobre cómo configurar servidores MCP de repositorio compartido en GitHub, vea Configuración de servidores MCP para el repositorio.

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 la agent profile y/o en 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 herramientas a continuación.
  • Tenga en cuenta que si el repositorio tiene configurados servidores MCP, puede elegir que solo haya herramientas específicas de esos servidores disponibles para custom agent. 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 VS Code pueden usar el nombre de la extensión como proxy, como azure.some-extension/some-tool.
• Deshabilitar todas las herramientas: use una lista vacía (tools: []) para deshabilitar todas las herramientas del agente.

Todos los nombres de herramientas no reconocidos se omiten, lo que permite especificar herramientas específicas del producto en un agent profile sin causar problemas.

Alias de herramientas

Los siguientes alias de herramienta están disponibles para custom agents. Todos los alias no distinguen mayúsculas de minúsculas:

Nombres de herramientas para servidores MCP "listos para usar"

Los siguientes servidores MCP están disponibles de fábrica para Copilot cloud agent y se puede hacer referencia a ellos mediante el espaciado de nombres:

Detalles de configuración del servidor MCP

En el ejemplo agent profile siguiente 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 de un agent profile es una representación en YAML del formato de configuración JSON que se utiliza para configurar servidores MCP para repositorios en GitHub.

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 los repositorios en GitHub los que son relevantes para custom agents. Para obtener más información sobre el formato de configuración JSON, consulte Configuración de servidores MCP para el repositorio.

Tipo de servidor MCP

Por motivos de compatibilidad, el tipo stdio usado por Claude Code y VS Code se asigna al tipo de cloud agentlocal .

Variables de entorno y secretos del servidor MCP

Custom agent La configuración de MCP 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 pueden provenir de los secretos y variables de agentes para Copilot cloud agent, configurados a nivel de organización o de 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 DE JSON de MCP de nivel de repositorio como la custom agent configuración de YAML admiten los siguientes patrones de 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 custom agent configuración de 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

Configuraciones de ejemplo agent profile

En los ejemplos siguientes se muestra lo que un agent profile 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 Custom agents 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 custom agents

Custom agents Nombres

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 Custom agent se basa en SHA de confirmación de Git para el archivo agent profile. Esto le permite crear ramas o etiquetas con diferentes versiones de custom agents según sea necesario. Al asignar un custom agent a una tarea, se instanciará custom agent utilizando la versión más reciente de agent profile para ese repositorio y rama. Cuando el agente crea una solicitud de incorporación de cambios, las interacciones dentro de la solicitud de incorporación de cambios usan la misma versión de custom agent por 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 agent profile, el comportamiento depende de lo que 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

En el caso de las configuraciones del servidor MCP, hay un orden de procesamiento específico que garantiza un comportamiento de sobreposición adecuado: las configuraciones de MCP predeterminadas (como el MCP GitHub) se procesan primero, seguidas por la configuración de MCP custom agent, y por último, las configuraciones de MCP especificadas a través de los ajustes del repositorio. Esto permite que cada nivel invalide la configuración del nivel anterior según corresponda.

Lectura adicional

• GitHub Copilot CLI
• Referencia de comandos de la CLI de GitHub Copilot