Creación y uso de agentes personalizados para GitHub Copilot CLI

Cree agentes especializados con experiencia personalizada para tareas de desarrollo específicas.

En este artículo

Introducción

Custom agents le permiten adaptar la experiencia de Copilot a tareas específicas.

Cuando se le solicita a Copilot que realice una tarea, puede optar por usar uno de tus custom agents, si Copilot determina que la pericia del agente es adecuada para la tarea.

Cuando el agente principal delega el trabajo en un custom agent, ese trabajo se lleva a cabo mediante un subagente con su propia ventana de contexto. Esto permite al especialista centrarse en su tarea asignada sin sobrecargar el contexto del agente principal. También puede seleccionar un custom agent para la sesión directamente.

Para más información, consulta Agentes personalizados.

Crear un custom agent

Cada custom agent se define mediante un archivo Markdown con extensiones .agent.md. Puede crear estos archivos usted mismo o agregarlos desde la CLI, como se describe en los pasos siguientes.

  1. En modo interactivo, escriba /agent.

  2. Presione N para crear un nuevo agente.

  3. Elija entre las opciones para crear el custom agent en el repositorio o en su directorio personal.

    • Project (.github/agents/)

    • Usuario (~/.copilot/agents/)

    Nota:

    Si personal y repositorio custom agents tienen el mismo identificador, se usa el agente personal. Para un agente en la raíz de un directorio agents, el ID es el nombre del archivo sin la extensión .agent.md o .md. El campo opcional name no afecta a la desduplicación. Los agentes con el mismo name pero con ID diferentes se cargan ambos, pero si un valor de --agent coincide con más de un ID o name, la CLI usa la coincidencia de mayor prioridad.

  4. Elija si quiere que Copilot, cree el archivo custom agent o créelo usted mismo.

Opción 1: Usar Copilot

Escriba los detalles del agente que desea crear. Describa la experiencia del agente y cuándo se debe usar el agente. Copilot tomará la descripción que introduce y la usará para escribir un perfil de agente para usted.

Por ejemplo, podría ingresar:

I am a security expert. I check code files thoroughly for potential security issues. Use me whenever a security review/check/audit is requested for one or more code files, or when the word "seccheck" is used in a prompt in reference to code files.

I will identify potential problems, such as code that:

- Exposes secrets or credentials
- Allows cross-site scripting
- Allows SQL injection
- Contains vulnerable dependencies
- Allows authentication to be bypassed

If any problems are identified, create a single GitHub issue in this repository on GitHub.com with details of problems, giving full details of each issue, including, but not limited to, risk level and recommended fix.

Una vez Copilot finalizada la generación del perfil inicial del agente, se muestran las siguientes opciones:

  • Continuar
  • Revisión del contenido
  • Volver a intentarlo
  • Salir

Si decide revisar el contenido, el archivo del agente se abre en el editor predeterminado. Puede revisar y realizar cambios, si es necesario, antes de continuar con el proceso de creación del agente en la CLI.

Para completar el proceso de creación, elija Continuar.

Opción 2: Creación manual del perfil del agente

Al elegir crear el archivo del agente usted mismo, se le guiará a través de una serie de avisos para rellenar la información necesaria para crear el perfil del agente.

  1. Escriba un nombre para el agente. El nombre que escriba es el nombre que se muestra al enumerar los agentes disponibles. Una versión de esto se usará como nombre del archivo del agente; por ejemplo, si escribe "Experto en seguridad", el archivo del agente se denominará security-expert.agent.md.

    Sugerencia

    Para facilitar el uso de un elemento custom agent mediante programación, se recomienda elegir un nombre que consta solo de letras minúsculas y guiones.

  2. Escriba una descripción que indique qué experiencia tiene este agente y cuándo se debe usar.

  3. Escriba instrucciones sobre cómo debe comportarse el agente, incluidas las instrucciones específicas, las acciones que debe realizar o las restricciones que debe seguir.

  4. Elija las herramientas custom agent a las que debe tener acceso.

    De forma predeterminada, custom agents tiene acceso a todas las herramientas. Si restringe el acceso de un agente, se agrega una tools especificación al archivo del agente.

  5. Reinicie la CLI para cargar el nuevo custom agent.

Uso de un custom agent

Custom agents se puede usar de las siguientes maneras:

  • Comando Slash

    Escriba /agent en modo interactivo y elija de la lista de custom agents disponibles. A continuación, escriba un mensaje que se pasará al agente seleccionado.

    Nota:

    Los agentes predeterminados de la CLI no se incluyen en esta lista. Para obtener más información sobre los agentes predeterminados, consulte Agentes personalizados.

  • Instrucción explícita

    Indica Copilot que use un agente específico. Por ejemplo:

    Use the security-auditor agent on all files in the /src/app directory

  • Por inferencia

    Utilice una solicitud que desencadene el uso de un agente particular basándose en la descripción del archivo del agente. Por ejemplo:

    Check all TypeScript files in or under the src directory for potential security problems

    o (donde "seccheck" se define como una palabra de desencadenador en el perfil del agente):

    seccheck /src/app/validator.go

Copilot deducirá automáticamente el agente que desea usar.

  • Programáticamente

    Especifique el custom agent que desea usar con la opción de línea de comandos. Por ejemplo:

    copilot --agent security-auditor --prompt "Check /src/app/validator.go"

    En este ejemplo, security-auditor es el identificador de .custom agent El identificador se deriva del nombre de archivo, sin la .md extensión o .agent.md . En este caso, la ruta de acceso al archivo es agents/security-auditor.md o agents/security-auditor.agent.md. Si el archivo está en un subdirectorio de agents, el nombre del subdirectorio se incluye en el identificador, por el separador de directorios reemplazado por --. Por lo tanto, un archivo de agente en agents/security/security-auditor.agent.md tendría el identificador security--security-auditor. Como alternativa, puede usar el valor del name campo en lugar del identificador, encerrándolo entre comillas. Por ejemplo: --agent "Security Auditor".

Delegar tareas centradas en un modelo específico

Puede configurar un custom agent para usar un modelo específico.

Esto puede ser especialmente útil cuando desea delegar tareas pequeñas y bien definidas en un custom agent que usa un modelo hospedado localmente, mientras se usa un modelo basado en la nube para su sesión principal. Este enfoque le permite, por ejemplo, delegar un cambio de archivo único o una corrección de prueba centrada a un custom agent que usa un modelo local y, a continuación, hacer que el agente principal revise el resultado.

En primer lugar, agregue un modelo hospedado localmente a la CLI. Consulte Adición de modelos LLM a GitHub Copilot CLI.

  1. Cree ~/.copilot/agents/local-coder.agent.md con el siguiente contenido:

    ---
name: local-coder
description: >
  Use for small, well-defined coding tasks, such as a
  single-file change or a focused test fix.
model: LOCAL-PROVIDER/LOCAL-MODEL
model-policy: required
tools: ["read", "grep", "glob", "edit", "execute"]
strict-tools-list: true
include-custom-instructions: true
---

Complete only the requested task. Inspect the relevant
code, make the smallest correct change, and run focused
checks. Report what changed and any remaining issues.

  2. Reemplace LOCAL-PROVIDER/LOCAL-MODEL por el identificador calificado por el proveedor de su modelo local, no por su nombre para mostrar. Para un modelo en providers.json, combine los valores id y provider de la entrada del modelo, separados por una barra diagonal. Por ejemplo, "provider": "local" y "id": "qwen3:8b" le proporcionan local/qwen3:8b.

model-policy: required requiere el modelo configurado en lugar de tratarlo como una preferencia.

strict-tools-list: true limita el agente a los grupos de herramientas enumerados sin agregar las herramientas predeterminadas habituales.

include-custom-instructions: true mantiene las instrucciones del repositorio en vigor para el subagente.

  1. Reinicie la CLI para cargar el agente. En una sesión mediante un modelo de nube, delegue explícitamente una tarea delimitada:

    Use the local-coder agent to add an empty-input test for
parseConfig in src/config.test.ts. Do not change other
files. Then review the result in the main session.

    El modelo local ejecuta la tarea delegada, pero el agente principal sigue recibiendo el resultado. Esto no hace que toda la sesión sea local o sin conexión.

Aplicar las instrucciones personalizadas del repositorio a custom agent

Los archivos de instrucciones personalizados, como .github/copilot-instructions.md, AGENTS.mdy CLAUDE.md, indican Copilot cómo trabajar en el repositorio. Para más información, consulta Agregar instrucciones personalizadas del repositorio para GitHub Copilot.

Cuando Copilot ejecuta tu custom agent como subagente —para encargarse de parte de una tarea más amplia—, el subagente no sigue de forma predeterminada las instrucciones personalizadas de tu repositorio. Esto mantiene el subagente centrado en la tarea específica que se dio.

Si desea que un subagent siga las convenciones del repositorio (por ejemplo, un agente que revisa o edita el código), agregue include-custom-instructions: true a la frontmatter del archivo del agente:

---
name: RepoAwareReviewer
description: Reviews a change against this repository's conventions
tools: ["*"]
include-custom-instructions: true
---

Review the change and flag anything that violates the repository's conventions.

Nota:

Esta configuración solo afecta al agente cuando se ejecuta como un subagente. Un custom agent que selecciones tú mismo—con --agent, /agent o por inferencia—ya sigue las instrucciones personalizadas de tu repositorio, por lo que la configuración no tiene ningún efecto en ese caso.

Para obtener más información, incluida la interacción de esta configuración con la --no-custom-instructions opción, consulte Referencia de comandos de la CLI de GitHub Copilot.

Lectura adicional