Creación de agentes de GitHub Copilot personalizados en Visual Studio Code

8 minutos

Los agentes personalizados son asistentes de IA especializados que se configuran para determinados roles o flujos de trabajo en Visual Studio Code. Cada agente encapsula un conjunto de instrucciones y permisos de herramientas que dirigen el comportamiento de GitHub Copilot para que actúe como un tipo específico de experto. Al seleccionar un agente personalizado en GitHub Copilot Chat, la inteligencia artificial adopta el rol del agente, sigue sus directrices y usa solo las herramientas que asignó.

¿Qué son los agentes de GitHub Copilot personalizados?

Un agente personalizado es una configuración personalizada que transforma GitHub Copilot Chat en un asistente específico del rol. En lugar de confiar en el comportamiento de uso general, un agente personalizado funciona según las instrucciones y restricciones que defina. Por ejemplo, puede crear un agente "Revisor de seguridad" que analice el código de las vulnerabilidades, un agente de "Escritor de pruebas" que se centre en la generación de pruebas unitarias o un agente "Planner" que genere planes de implementación sin modificar ningún archivo.

Los agentes personalizados se introdujeron como una característica avanzada en Visual Studio Code (disponible a partir de la versión 1.106 de Visual Studio Code, anteriormente conocida como "modos de chat personalizados"). Proporcionan a los desarrolladores un control específico sobre cómo funciona la inteligencia artificial en diferentes contextos de desarrollo. Cada agente aparece en la lista desplegable Agentes de Chat de Copilot de GitHub, donde puede seleccionarlo para cambiar el modo de la inteligencia artificial en cualquier momento.

Los agentes personalizados se pueden almacenar en dos ubicaciones:

Agentes del área de trabajo: se almacenan en la .github/agents/ carpeta del repositorio. Estos agentes se comparten con su equipo a través del control de versiones, lo que garantiza que todos los usuarios del proyecto tengan acceso a los mismos asistentes especializados.
Agentes de perfil de usuario: almacenados en la carpeta de mensajes del perfil de usuario de Visual Studio Code. Estos agentes son personales y están disponibles en todas las áreas de trabajo, útiles para los agentes que reflejan sus preferencias de flujo de trabajo individuales.

Examen del funcionamiento de los agentes personalizados

Un agente personalizado es un archivo Markdown con una .agent.md extensión. Visual Studio Code detecta automáticamente cualquier archivo .agent.md en la carpeta de .github/agents/ del área de trabajo (o en el perfil de usuario) y los carga como agentes disponibles en la interfaz de Chat de GitHub Copilot.

Cada archivo de agente consta de dos partes:

Un encabezado de frontmatter de YAML: en esta sección se especifican metadatos que incluyen el nombre del agente, una descripción que aparece en la interfaz de chat, las herramientas que puede usar, una preferencia de modelo opcional y configuraciones de entrega para conectarse a otros agentes.
Un cuerpo de Markdown: esta sección contiene las instrucciones y el contexto del agente. El contenido se antepone a cada solicitud de usuario cada vez que el agente está activo, lo que guía a GitHub Copilot en cómo interpreta y responde a las solicitudes. Estas instrucciones se escriben en el mismo estilo de lenguaje natural que se usa para los archivos de instrucciones personalizados.

Campos de metadatos del agente

La frontmatter de YAML admite los siguientes campos para configurar el comportamiento del agente:

Campo	Description
`description`	Una descripción breve que se muestra como texto de marcador de posición en la entrada de chat cuando se selecciona el agente.
`name`	Un nombre opcional para mostrar. Si se omite, se usa el nombre de archivo (sin `.agent.md`).
`tools`	Matriz de herramientas que puede usar el agente, como `['read', 'edit', 'search']`. Omitir este campo proporciona acceso a todas las herramientas disponibles.
`model`	Un modelo de IA preferido. Puede ser una cadena de identificador de modelo único o un conjunto de identificadores de modelo para alternativa (por ejemplo, `['o4-mini', 'gpt-4.1']`).
`agents`	Matriz de nombres de agente que este agente puede invocar como subagentes.
`handoffs`	Matriz de configuraciones de entrega que definen las transiciones a otros agentes (que se tratan en la unidad siguiente).
`argument-hint`	Texto de sugerencia que se muestra en la entrada de chat, que describe lo que el usuario debe escribir como entrada para el agente.
`user-invokable`	Valor booleano que controla si el agente aparece en la lista desplegable de agentes. Establézcalo en `false` para crear agentes a los que otros agentes solo pueden llamar como subagentes. Tiene como valor predeterminado `true`.
`disable-model-invocation`	Cuando se establece en `true`, el agente no envía mensajes al modelo de lenguaje. Resulta útil para los agentes que realizan acciones únicamente a través de herramientas.
`target`	Especifica el entorno de ejecución para el agente: `client` (se ejecuta en Visual Studio Code, el valor predeterminado) o `cloud` (se ejecuta en la nube).
`mcp-servers`	Objeto al que se definen los servidores MCP (Protocolo de contexto de modelo) a los que el agente debe tener acceso. Los servidores MCP amplían las funcionalidades del agente mediante la conexión a herramientas externas y orígenes de datos.

En el ejemplo siguiente se muestra la estructura de un archivo de agente personalizado mediante varios de estos campos:

---
description: Reviews code for security vulnerabilities and suggests improvements
tools: ['search', 'read']
---
# Security Reviewer

You are a senior security engineer. When the user provides code or asks you to review files, analyze the code for common security vulnerabilities including:

- SQL injection
- Cross-site scripting (XSS)
- Authentication and authorization flaws
- Insecure data handling
- Hardcoded credentials or secrets

Provide your findings as a structured list with severity levels (Critical, High, Medium, Low). For each finding, explain the vulnerability, show the affected code, and suggest a secure alternative.

Do not modify any files. Your role is advisory only.

Cuando un desarrollador selecciona este agente en GitHub Copilot Chat, todas las interacciones usan estas instrucciones. El agente "sabe" debe centrarse en el análisis de seguridad y no intentará editar archivos porque sus instrucciones y conjuntos de herramientas lo restringen a operaciones de solo lectura.

Definición de funcionalidades del agente con herramientas

El tools campo de la frontmatter de YAML controla las acciones que puede realizar el agente. Las herramientas determinan si el agente puede leer archivos, editar código, buscar en el código base, ejecutar comandos de terminal o acceder a otras funcionalidades. Al adaptar la lista de herramientas, asegúrese de que cada agente solo realiza acciones relevantes para su rol.

Entre las herramientas comunes se incluyen:

Herramienta	Description
`read`	Leer contenido del archivo del área de trabajo
`edit`	Modificación de archivos en el área de trabajo
`search`	Búsqueda entre archivos del área de trabajo
`fetch`	Recuperar contenido de direcciones URL
`terminal`	Ejecución de comandos en el terminal
`agent`	Invocación de otros agentes como subagentes

Si omite el tools campo por completo, el agente tiene como valor predeterminado tener acceso a todas las herramientas estándar. Sin embargo, enumerar explícitamente las herramientas es un procedimiento recomendado porque crea límites claros para el comportamiento del agente. Un agente de planeación que no debe modificar el código debe especificar solo ['search', 'read', 'fetch'], mientras que un agente de implementación que necesita escribir código incluiría ['search', 'read', 'edit', 'terminal'].

Nota:

Si una herramienta que aparece en la configuración del agente no está disponible en el entorno actual, se omite silenciosamente. Esto significa que puede definir agentes con herramientas que solo estén disponibles en determinadas configuraciones sin causar errores.

Subagentes

El agents campo de la frontmatter de YAML permite que un agente invoque otros agentes como subagentes. Un subagent es un agente al que otro agente llama para controlar una subtarea y, a continuación, incorpora el resultado en su propia respuesta. Este comportamiento es diferente de una transferencia, que transfiere el control al usuario; ocurre una llamada de subagente dentro del procesamiento del agente y devuelve el resultado al agente que realiza la llamada automáticamente.

Por ejemplo, un agente "Desarrollador potencial" podría invocar un subagente "Revisor de seguridad" para comprobar un fragmento de código, recibir los resultados y, a continuación, incorporar esos hallazgos en su respuesta final, todo ello dentro de una única interacción.

Para configurar subagentes, enumere los nombres de subagentes en el agents campo:

---
description: Lead developer agent that coordinates with specialists
tools: ['search', 'read', 'edit']
agents: ['security-reviewer', 'test-writer']
---

Los agentes que están diseñados solo para su uso como subagentes pueden establecerse user-invokable: false para que no aparezcan en la lista desplegable agentes, manteniendo la interfaz limpia.

Nota:

Para usar subagentes, incluya la herramienta agent en la lista del agente que está llamando tools (o bien omita el campo tools por completo para habilitar todas las herramientas). La agent herramienta permite que un agente llame a otro mediante programación durante su respuesta.

Agentes de nivel de organización

Para los equipos que mantienen agentes compartidos entre varios repositorios, GitHub admite agentes de nivel de organización. Estos agentes se configuran en el nivel de organización de GitHub y aparecen automáticamente junto con el área de trabajo y los agentes de perfil de usuario en Visual Studio Code cuando haya iniciado sesión en una cuenta de GitHub con acceso a la organización.

Los agentes de nivel de organización garantizan la coherencia entre los equipos. Por ejemplo, un equipo de seguridad puede publicar un agente compartido "Revisor de seguridad" que todos los repositorios de la organización pueden usar, lo que garantiza que los mismos criterios de revisión de seguridad se aplican en todas partes sin necesidad de que cada repositorio defina su propio agente.

Compatibilidad con el formato del agente

Visual Studio Code reconoce los archivos de agente en el .agent.md formato como configuración principal. Además, Visual Studio Code admite archivos de agente de estilo Claude que siguen el formato del agente de Claude Code. Si ya tiene configuraciones de agente de Claude Code, funcionan en el chat de GitHub Copilot de Visual Studio Code sin modificaciones. Esta compatibilidad cruzada simplifica la migración para los equipos que usan varias herramientas de inteligencia artificial.

Agentes integrados frente a personalizados

Visual Studio Code incluye varios agentes integrados que proporcionan configuraciones de uso general para el chat. Estos agentes incluyen el agente predeterminado "GitHub Copilot" y los agentes especializados para tareas comunes. Los agentes personalizados amplían este sistema al permitirle definir sus propios roles con instrucciones específicas del proyecto y configuraciones de herramientas.

Los agentes personalizados aparecen en el menú desplegable de agentes de chat de Copilot de GitHub junto con los agentes integrados. Puede cambiar entre cualquier agente en cualquier momento para cambiar el funcionamiento de la inteligencia artificial. Esta flexibilidad le permite moverse entre diferentes modos de trabajo( planificación, codificación, revisión, pruebas) sin salir de la interfaz de Chat de Copilot de GitHub.

La ventaja clave de los agentes personalizados sobre los agentes integrados es la especificidad. Un agente de revisión de código integrado aplica procedimientos recomendados generales, mientras que el agente personalizado "Revisor de código" puede aplicar la lista de comprobación de revisión específica del equipo, hacer referencia a las decisiones arquitectónicas del proyecto y centrarse en los patrones y antipatrones que más importan en el código base.

Pasos para crear un agente personalizado

Siga estos pasos para crear un agente personalizado en Visual Studio Code:

Abra el menú agentes: en el panel Chat de Copilot de GitHub, abra la lista desplegable agentes (que normalmente muestra el nombre del agente actual). Seleccione Configurar agentes personalizados y, a continuación, elija Crear nuevo agente personalizado. Como alternativa, ejecute el Chat: New Custom Agent comando desde la paleta de comandos (Ctrl+Mayús+P).
Elija el ámbito: seleccione dónde almacenar el archivo del agente. Elija Área de trabajo para crear el archivo en .github/agents/ (que esté disponible para el equipo a través del control de versiones) o elija Perfil de usuario para que sea personal y disponible en todas las áreas de trabajo.
Asigne al agente el nombre: escriba un nombre de archivo descriptivo para el agente. Este nombre aparece como el nombre predeterminado en la lista desplegable de agentes. Use un nombre que indique claramente el rol del agente, como planner, code-reviewero test-writer.
Definir los metadatos del agente: en el frontmatter de YAML del archivo recién creado .agent.md , configure las propiedades del agente. Establezca un description (este texto aparece como marcador de posición en la entrada de chat cuando se selecciona el agente), especifique a qué tools debe tener acceso el agente, y opcionalmente establezca un model preferido o configure handoffs para otros agentes.
Escriba las instrucciones del agente: en el cuerpo del archivo debajo del frontmatter de YAML, proporcione las instrucciones personalizadas para el agente. Estas instrucciones definen el rol, la experiencia y las directrices de comportamiento del agente. Escríbalos en Markdown con un lenguaje claro y específico que indique a la inteligencia artificial cómo abordar las tareas, en qué centrarse y en qué restricciones se deben seguir.
Guardar y activar: guarde el archivo. El agente personalizado aparece inmediatamente en la lista desplegable de agentes de chat de GitHub Copilot (suponiendo que user-invokable sea true, lo cual es el valor predeterminado). Seleccione el agente para empezar a usarlo.

Sugerencia

Puede escribir /agents en Chat de Copilot de GitHub como acceso directo rápido para ver y cambiar entre todos los agentes disponibles, incluidos los agentes integrados, el área de trabajo, el perfil de usuario y los agentes de nivel de organización.

Aptitudes del agente

Las habilidades del agente son un concepto relacionado pero distinto de los agentes personalizados. Aunque los agentes definen un rol con instrucciones y herramientas, las aptitudes del agente (definidas en SKILL.md archivos) describen funcionalidades específicas o áreas de experiencia que un agente puede aprovechar. Las aptitudes proporcionan metadatos estructurados sobre lo que un agente sabe y puede hacer. Visual Studio Code admite habilidades como parte de su sistema de personalización más amplio. Las aptitudes se definen normalmente en el área de trabajo y las detecta automáticamente GitHub Copilot para mejorar las respuestas del agente con conocimientos especializados.

Ejemplos de agentes personalizados

En los ejemplos siguientes se muestra cómo definir agentes para roles de desarrollo comunes.

Agente de "Planner"

Un agente de Planner se centra en analizar los requisitos y generar planes de implementación sin modificar ningún código. Usa solo herramientas de solo lectura e incluye una entrega a un agente de implementación para cuando el plan está listo para ejecutarse.

---
description: Generates high-level implementation plans without writing code
tools: ['search', 'read', 'fetch']
handoffs:
  - label: Start Implementation
    agent: implementer
    prompt: Now implement the plan outlined above.
    send: false
---
# Planner

You are a senior software architect. When the user describes a feature or change, analyze the request and generate a detailed implementation plan.

Your plan should include:
1. A summary of the feature requirements.
2. A list of files that need to be created or modified.
3. Step-by-step implementation tasks in logical order.
4. Any potential risks or considerations.

Do not write or modify any code. Focus on planning only. Ask clarifying questions if the requirements are ambiguous.

Agente "Revisor de código"

Un agente de revisor de código examina el código de los problemas de calidad, las vulnerabilidades de seguridad y el cumplimiento de los procedimientos recomendados. Usa herramientas de lectura y búsqueda, pero no edita archivos directamente.

---
description: Reviews code for bugs, security issues, and style compliance
tools: ['search', 'read']
---
# Code Reviewer

You are an experienced code reviewer. When the user asks you to review code, examine it for:

- Bugs and logical errors
- Security vulnerabilities (SQL injection, XSS, authentication flaws)
- Performance issues
- Naming convention violations
- Missing error handling
- Code duplication

Present your findings as a structured review with severity levels. For each issue, explain the problem, show the affected code, and suggest an improvement. End with an overall assessment of code quality.

Estos ejemplos se pueden adaptar para satisfacer las necesidades específicas de su equipo. El principio clave es definir instrucciones claras que centren al agente en una tarea específica y configuren la lista de herramientas para que coincidan con las responsabilidades del agente.

Resumen

Los agentes personalizados de Visual Studio Code permiten definir roles de IA especializados con instrucciones personalizadas y permisos de herramientas. Al crear .agent.md archivos en el área de trabajo o el perfil de usuario, puede crear agentes para roles de desarrollo específicos: planificación, implementación, revisión, prueba, etc. Cada agente funciona dentro de los límites que defina, usando solo las herramientas que permita y siga las instrucciones que proporcione. Las características avanzadas, como los subagentes, los agentes de nivel de organización y la integración del servidor MCP amplían lo que pueden lograr los agentes. Estas funcionalidades proporcionan un control preciso sobre cómo se comporta GitHub Copilot en distintas fases del flujo de trabajo de desarrollo.

Comentarios

¿Le ha resultado útil esta página?