Acerca de los ganchos

Los enlaces permiten ejecutar comandos de shell personalizados en puntos estratégicos del flujo de trabajo de un agente, como cuando se inicia o finaliza una sesión del agente, o antes y después de que se escriba un mensaje o se llame a una herramienta.

Los enlaces reciben información detallada sobre las acciones del agente a través de la entrada JSON, lo que habilita la automatización con reconocimiento del contexto. Por ejemplo, puede usar ganchos para:

Aprobar o denegar ejecuciones de herramientas mediante programación.
Use características de seguridad integradas, como el examen de secretos, para evitar pérdidas de credenciales.

Implemente reglas de validación personalizadas y registro de auditoría para el cumplimiento.

        Copilot los agentes admiten ganchos almacenados en archivos JSON en tu repositorio en `.github/hooks/*.json`.

Los ganchos están disponibles para usar con:

agente en la nube de Copilot en GitHub
CLI de GitHub Copilot en el terminal

Tipos de enlaces

Están disponibles los siguientes tipos de hooks:

sessionStart: se ejecuta cuando comienza una nueva sesión del agente o al reanudar una sesión existente. Se puede usar para inicializar entornos, registrar el inicio de sesiones para auditar, validar el estado del proyecto y configurar recursos temporales.
sessionEnd: se ejecuta cuando la sesión del agente concluye o se termina. Se puede usar para limpiar recursos temporales, generar y archivar registros e informes de sesión, o enviar notificaciones sobre la finalización de la sesión.
userPromptSubmitted: se ejecuta cuando el usuario envía un mensaje al agente. Se puede usar para registrar las solicitudes de usuario para la auditoría y el análisis de uso.
preToolUse: ejecutado antes de que el agente use cualquier herramienta (como bash, edit, view). Este es el enlace más eficaz, ya que puede aprobar o denegar ejecuciones de herramientas. Use este enlace para bloquear comandos peligrosos, aplicar directivas de seguridad y estándares de codificación, requerir aprobación para operaciones confidenciales o el uso de herramientas de registro para el cumplimiento.
postToolUse: se ejecuta después de que una herramienta complete la ejecución (ya sea correcta o con errores). Se puede usar para registrar los resultados de la ejecución, realizar un seguimiento de las estadísticas de uso, generar seguimientos de auditoría, supervisar las métricas de rendimiento y enviar alertas de error.
agentStop: se ejecuta cuando el agente principal ha terminado de responder a la solicitud.
subagentStop: se ejecuta cuando se completa un subagente, antes de devolver los resultados al agente primario.
errorOccurred: se ejecuta cuando se produce un error durante la ejecución del agente. Se puede usar para registrar errores para depurar, enviar notificaciones, realizar un seguimiento de los patrones de error y generar informes.

Para ver una referencia completa de tipos de enlace con casos de uso de ejemplo, procedimientos recomendados y patrones avanzados, consulte Configuración de hooks.

Formato de configuración de gancho

Configura los hooks usando un formato JSON especial. El JSON debe contener un version campo con un valor de 1 y un hooks objeto que contenga matrices de definiciones de enlace.

JSON

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}

El objeto de enlace puede contener las siguientes claves:

Propiedad	Obligatorio	Descripción
`type`	Sí	Debe ser `"command"`
`bash`	Sí (en sistemas Unix)	Ruta de acceso al script de Bash que se va a ejecutar
`powershell`	Sí (en Windows)	Ruta de acceso al script de PowerShell que se va a ejecutar
`cwd`	No	Directorio de trabajo para el script (relativo a la raíz del repositorio)
`env`	No	Variables de entorno adicionales que se combinan con el entorno existente
`timeoutSec`	No	Tiempo máximo de ejecución en segundos (valor predeterminado: 30)

Archivo de configuración de enlace de ejemplo

Este es un archivo de configuración de ejemplo que reside en ~/.github/hooks/project-hooks.json dentro de un repositorio.

JSON

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo \"Session started: $(date)\" >> logs/session.log",
        "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
        "cwd": ".",
        "timeoutSec": 10
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo \"Session started: $(date)\" >> logs/session.log",
        "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
        "cwd": ".",
        "timeoutSec": 10
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}

Consideraciones sobre el rendimiento

Los ganchos operan sincrónicamente y bloquean la ejecución del agente. Para garantizar una experiencia con capacidad de respuesta, tenga en cuenta las siguientes consideraciones:

Minimizar el tiempo de ejecución: mantenga el tiempo de ejecución del enlace en menos de 5 segundos cuando sea posible.
Optimizar el registro: use el registro asincrónico, como anexar a archivos, en lugar de E/S sincrónica.
Usar el procesamiento en segundo plano: para operaciones costosas, considere la posibilidad de procesar en segundo plano.
Resultados de caché: almacene en caché cálculos costosos cuando sea posible.

Consideraciones de seguridad

Para garantizar que la seguridad se mantiene al usar hooks, tenga en cuenta las siguientes consideraciones:

Valide y corrija siempre la entrada procesada por enlaces. La entrada que no es de confianza podría provocar un comportamiento inesperado.
Utilice el escape adecuado del shell al construir comandos. Esto evita vulnerabilidades de inyección de comandos.
Nunca registre datos confidenciales, como tokens o contraseñas.
Asegúrese de que los scripts de gancho y los logs tengan los permisos adecuados.
Tenga cuidado con los enlaces que realizan llamadas de red externas. Estos pueden introducir latencia, errores o exponer datos a terceros.
Establezca los tiempos de espera adecuados para evitar el agotamiento de recursos. Los enlaces de ejecución prolongada pueden bloquear la ejecución del agente y degradar el rendimiento.

Pasos siguientes

Para empezar a crear enlaces, consulte Personalización de flujos de trabajo de agente con enlaces.

Acerca de los ganchos

¿Quién puede utilizar esta característica?

En este artículo