Personalización de flujos de trabajo de agente con enlaces

Los ganchos permiten ampliar y personalizar el comportamiento de los agentes ejecutando comandos de shell personalizados en puntos clave durante la ejecución del agente. Para obtener información general conceptual sobre los enlaces, incluidos los detalles de los desencadenadores de enlace disponibles, consulte Acerca de los ganchos para GitHub Copilot.

Creación de un enlace en un repositorio GitHub

1. Cree un nuevo NAME.json archivo (donde NAME describe el propósito del archivo) en la .github/hooks/ carpeta del repositorio.

   Importante

   El archivo de configuración de enlaces debe estar presente en la rama predeterminada del repositorio que va a usar agente en la nube de Copilot.

2. En el editor de texto, copie y pegue la siguiente plantilla de enlace. Elimine los ganchos que no planee usar del hooks array.

   JSON

   {
     "version": 1,
     "hooks": {
       "sessionStart": [...],
       "sessionEnd": [...],
       "userPromptSubmitted": [...],
       "preToolUse": [...],
       "postToolUse": [...],
       "errorOccurred": [...]
     }
   }
   

3. Configure la sintaxis de hook en las claves bash y powershell, o hacer referencia directamente a los archivos de script que ha creado.

   Nota:

   Incluya una clave de bash (con un script para Linux y macOS) y una clave de powershell (para un script para Windows) para permitir que los enlaces se ejecuten en los tres sistemas operativos. Copilot usa la clave adecuada en función del sistema operativo del usuario.

   • En este ejemplo, se ejecuta un script que registra la fecha de inicio de la sesión en un archivo de registro mediante el gancho sessionStart.

     JSON

     "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
       }
     ],
     

   • En este ejemplo se llama a un script externo log-prompt :

     JSON

     "userPromptSubmitted": [
       {
         "type": "command",
         "bash": "./scripts/log-prompt.sh",
         "powershell": "./scripts/log-prompt.ps1",
         "cwd": "scripts",
         "env": {
           "LOG_LEVEL": "INFO"
         }
       }
     ],
     

     Para obtener una referencia completa sobre el JSON de entrada de las sesiones del agente junto con scripts de ejemplo, consulte Referencia de enlaces de GitHub Copilot.

4. Confirme el archivo en el repositorio y combítelo en la rama predeterminada. Los enlaces se ejecutarán ahora durante las sesiones de los agentes.

Solución de problemas

Si tiene problemas al usar enlaces, use la tabla siguiente para solucionar problemas.

Cuestión	Acción
Los ganchos no se están ejecutando	Compruebe que el archivo JSON está en el .github/hooks/ directorio . Compruebe si hay sintaxis JSON válida (por ejemplo, jq . hooks.json). Asegúrese de que version: 1 está especificado en su archivo hooks.json. Compruebe que el script al que llama desde el enlace es ejecutable (chmod +x script.sh) Compruebe que el script tiene un shebang adecuado (por ejemplo, #!/bin/bash).
Los hooks se están agotando en tiempo de espera	El tiempo de expiración predeterminado es de 30 segundos. Aumente timeoutSec en la configuración si es necesario. Optimice el rendimiento del script evitando operaciones innecesarias.
Salida JSON no válida	Asegúrese de que la salida está en una sola línea. En Unix, use jq -c para compactar y validar la salida JSON. En Windows, use el comando ConvertTo-Json -Compress en PowerShell para hacer lo mismo.

Depuración

Puede depurar enlaces mediante los métodos siguientes:

• Habilite el registro detallado en el script para inspeccionar los datos de entrada y trazar la ejecución del script.

  Shell

  #!/bin/bash
  set -x  # Enable bash debug mode
  INPUT=$(cat)
  echo "DEBUG: Received input" >&2
  echo "$INPUT" >&2
  # ... rest of script
  

• Pruebe los hooks localmente canalizando los datos de prueba en su hook para validar su comportamiento:

  Shell

  # Create test input
  echo '{"timestamp":1704614400000,"cwd":"/tmp","toolName":"bash","toolArgs":"{\"command\":\"ls\"}"}' | ./my-hook.sh
  
  # Check exit code
  echo $?
  
  # Validate output is valid JSON
  ./my-hook.sh | jq .
  

Lectura adicional

• Referencia de enlaces de GitHub Copilot
• Acerca de GitHub Copilot agente en la nube
• Acerca de GitHub Copilot CLI
• Configuración del entorno de desarrollo