Configuración de agentes personalizados

En este artículo de referencia se proporciona información detallada de configuración para agentes personalizados. Para obtener información general sobre cómo crear agentes personalizados, vea Creación de agentes personalizados para Agente en la nube de Copilot.

Propiedades del frontmatter de YAML

En la tabla siguiente se describen las propiedades que puede configurar para perfiles de agente en GitHub.com, en CLI de Copilot 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.

          **Cadena necesaria**     | Descripción del propósito y las capacidades de agente personalizado |

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 agente personalizadotools propiedad controla qué herramientas están disponibles para el agente, incluidas las de los servidores MCP.

Tendrá acceso a las herramientas del servidor MCP que se han configurado tanto en su configuración de agente personalizado como en el repositorio de perfil de agente. Para obtener más información sobre cómo configurar servidores MCP para el agente en la nube en un repositorio, consulte Extensión del agente de GitHub Copilot en la nube 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 la perfil de agente 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](#tool-aliases) 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 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 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 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 | Agente en la nube mapeo | 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 | "Agente personalizado" herramientas | Permite invocar un elemento diferente agente personalizado para realizar una tarea. | | web | WebSearch, WebFetch | Actualmente no es aplicable a agente de nube. | Permite capturar contenido de direcciones URL y realizar una búsqueda web | | todo | TodoWrite | Actualmente no es aplicable a agente de nube. | Crea y administra listas de tareas estructuradas. No se admite en agente de nube hoy, pero es compatible con VS Code. |

Nombres de herramientas para servidores MCP "listos para usar"

Los siguientes servidores MCP están disponibles de fábrica para Agente en la nube de Copilot y se pueden hacer referencia a ellos mediante el espaciado de nombres:

          `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 perfil de agente 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 en un perfil de agente es una representación YAML del formato de configuración JSON usado para configurar servidores MCP para Agente en la nube de 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 en la nube de Copilot que son relevantes para agentes personalizados. Para obtener más información sobre el formato de configuración JSON, consulte Extensión del agente de GitHub Copilot en la nube con el Protocolo de Contexto de Modelo (MCP).

Tipo de servidor MCP

Por motivos de compatibilidad, el stdio tipo usado por Claude Code y VS Code se asigna al agente de nubetipo de local .

Variables de entorno y secretos del servidor MCP

          Agente personalizado 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 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 DE JSON de MCP de nivel de repositorio como la agente personalizado 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 agente personalizado 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 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

          Agentes personalizados 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

          Agente personalizado El control de versiones se basa en SHAs de confirmación de Git para el perfil de agente archivo. 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 instanciará agente personalizado utilizando la versión más reciente de perfil de agente para ese repositorio y rama. Cuando el agente crea una solicitud de incorporación de cambios, las interacciones dentro del pull request usan la misma versión de agente personalizado para 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 perfil de agente, 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 agente personalizado, 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

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

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