# Personalizar fluxos de trabalho do agente com ganchos

Execute verificações automatizadas (como linting, formatação e verificações de segurança) em pontos-chave durante a execução do agente para aplicar padrões de qualidade.

Os ganchos permitem estender e personalizar o comportamento dos agentes executando comandos de shell personalizados em pontos-chave durante a execução do GitHub Copilot agente. Para obter uma visão geral conceitual dos ganchos, incluindo detalhes dos gatilhos disponíveis para os ganchos, consulte [Sobre ganchos para GitHub Copilot](/pt/copilot/concepts/agents/hooks).

## Criando um gancho em um repositório em GitHub

1. Crie um novo `NAME.json` arquivo (em que `NAME` descreve a finalidade do arquivo) na `.github/hooks/` pasta do repositório.

   > \[!IMPORTANT]
   > O arquivo de configuração de ganchos **deve estar presente** no branch padrão do repositório para ser usado por Copilot cloud agent.

2. No editor de texto, copie e cole o modelo de gancho a seguir. Remova os ganchos que você não planeja usar da `hooks` matriz.

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

3. Configure a sintaxe do gancho nos campos das chaves `bash` e `powershell`, ou referencie diretamente os arquivos de script que você criou.

   > \[!NOTE]
   > Inclua uma chave `bash` (com um script para Linux e macOS) e uma chave `powershell` (para um script para Windows) para permitir que os ganchos sejam executados em todos os três sistemas operacionais.
   > Copilot usa a chave apropriada com base no sistema operacional do usuário.

   * Este exemplo executa um script que gera a data de início da sessão para um arquivo de log usando o `sessionStart` gancho:

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

   * Este exemplo chama um script externo `log-prompt`:

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

     Para obter uma referência completa do JSON de entrada das sessões de agente, juntamente com scripts de exemplo, consulte [Referência de ganchos do GitHub Copilot](/pt/copilot/reference/hooks-reference).

4. Confirme o arquivo no repositório e faça a mesclagem na ramificação padrão. Agora, os ganchos serão executados durante as sessões do agente.

## Solução de problemas

Se você encontrar problemas ao usar hooks, utilize a tabela a seguir para solucioná-los.

| Questão                                | Ação                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Os ganchos não estão sendo executados  | <ul><li>Verifique se o arquivo JSON está no `.github/hooks/` diretório.</li><li>Verifique se há uma sintaxe JSON válida (por exemplo, `jq .  hooks.json`).</li><li>Verifique se `version: 1` está especificado em seu `hooks.json` arquivo.</li><li>Verifique se o script chamado pelo gancho é executável (`chmod +x script.sh`)</li><li>Verifique se o script tem um shebang adequado (por exemplo, `#!/bin/bash`)</li></ul> |
| Ganchos estão atingindo o tempo limite | <ul><li>O tempo limite padrão é 30 segundos. Aumente `timeoutSec` na configuração, se necessário.</li><li>Otimize o desempenho do script evitando operações desnecessárias.</li></ul>                                                                                                                                                                                                                                          |
| Saída JSON inválida                    | <ul><li>Verifique se a saída está em uma única linha.</li><li>No Unix, use `jq -c` para compactar e validar a saída JSON.</li><li>Em Windows, use o comando `ConvertTo-Json -Compress` no PowerShell para fazer o mesmo.</li></ul>                                                                                                                                                                                             |

## Resolução de Erros

Você pode depurar ganchos usando os seguintes métodos:

* **Habilite o log detalhado** no script para inspecionar os dados de entrada e rastrear a execução do script.

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

* **Teste ganchos localmente** canalizando a entrada de teste para o seu gancho para validar seu comportamento.

  ```shell copy
  # 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 .
  ```

## Leitura adicional

* [Referência de ganchos do GitHub Copilot](/pt/copilot/reference/hooks-reference)
* [Sobre o agente de nuvem do GitHub Copilot](/pt/copilot/concepts/agents/cloud-agent/about-cloud-agent)
* [Sobre GitHub Copilot CLI](/pt/copilot/concepts/agents/copilot-cli/about-copilot-cli)
* [Configurar o ambiente de desenvolvimento](/pt/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)