Personnaliser des flux de travail d’agent avec des hooks

Les hooks vous permettent d’étendre et de personnaliser le comportement de GitHub Copilot agents en exécutant des commandes shell personnalisées aux points clés pendant l’exécution des agents. Pour obtenir une vue d’ensemble conceptuelle des hooks, y compris les détails des déclencheurs de hook disponibles, consultez À propos des crochets pour GitHub Copilot.

Création d’un hook dans un référentiel sur GitHub

Dans votre éditeur de texte, copiez et collez le modèle de hook suivant. Supprimez les éléments que vous ne prévoyez pas d’utiliser dans le tableau hooks.

JSON

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

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

Configurez la syntaxe de votre hook sous les clés bash et powershell, ou référencez directement les fichiers de script que vous avez créés.

Remarque

Incluez à la fois une clé bash (avec un script pour Linux et macOS) et une clé powershell (pour un script pour Windows) afin d’autoriser les hooks à s’exécuter sur les trois systèmes d’exploitation. Copilot utilise la clé appropriée en fonction du système d’exploitation de l’utilisateur.

Cet exemple exécute un script qui génère la date de début de la session dans un fichier journal à l’aide du sessionStart hook :

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

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

Cet exemple appelle un script externe log-prompt :

JSON

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

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

Pour obtenir une référence complète sur l’entrée JSON à partir de sessions d’agent, ainsi que des exemples de scripts, consultez Références sur les hooks GitHub Copilot.

Validez le fichier dans le référentiel et fusionnez-le dans la branche par défaut. Vos hooks s’exécuteront désormais pendant les sessions de l’agent.

Résolution des problèmes

Si vous rencontrez des problèmes à l’aide de crochets, utilisez le tableau suivant pour résoudre les problèmes.

Problème	Action
Les hooks ne s’exécutent pas	Vérifiez que le fichier JSON se trouve dans le `.github/hooks/` répertoire. Recherchez la syntaxe JSON valide (par exemple). `jq . hooks.json` **

Assurez-vous que version: 1 est spécifié dans le fichier hooks.json.

Vérifiez que le script que vous appelez à partir de votre hook est exécutable (chmod +x script.sh)

Vérifiez que le script a un shebang approprié (par exemple, #!/bin/bash)

| | Les crochets expirent |

Le délai d’expiration par défaut est de 30 secondes. Augmentez timeoutSec dans la configuration si nécessaire.
Optimisez les performances des scripts en évitant les opérations inutiles.

| | Sortie JSON non valide |

Vérifiez que la sortie se trouve sur une seule ligne.
Sur Unix, utilisez jq -c pour compacter et valider la sortie JSON.
Sur Windows, utilisez la commande ConvertTo-Json -Compress dans PowerShell pour effectuer la même opération.

Débogage

Vous pouvez déboguer des hooks à l’aide des méthodes suivantes :

Activez la journalisation détaillée dans le script pour inspecter les données d’entrée et tracer l'exécution du script.

Shell

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

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

Testez les hooks localement en redirigeant l’entrée de test dans votre hook pour valider son comportement :

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 .

# 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 .

Personnaliser des flux de travail d’agent avec des hooks

Dans cet article

Création d’un hook dans un référentiel sur GitHub

Résolution des problèmes

Débogage

Lectures complémentaires