{"meta":{"title":"Personalizar fluxos de trabalho do agente com ganchos","intro":"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.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/how-tos","title":"Instruções"},{"href":"/pt/copilot/how-tos/copilot-on-github","title":"Copilot em GitHub"},{"href":"/pt/copilot/how-tos/copilot-on-github/customize-copilot","title":"Personalizar Copilot"},{"href":"/pt/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent","title":"Personalizar cloud agent"},{"href":"/pt/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks","title":"Usar ganchos"}],"documentType":"article"},"body":"# Personalizar fluxos de trabalho do agente com ganchos\n\nExecute 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.\n\nOs 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).\n\n## Criando um gancho em um repositório em GitHub\n\n1. Crie um novo `NAME.json` arquivo (em que `NAME` descreve a finalidade do arquivo) na `.github/hooks/` pasta do repositório.\n\n > \\[!IMPORTANT]\n > O arquivo de configuração de ganchos **deve estar presente** no branch padrão do repositório para ser usado por Copilot cloud agent.\n\n2. 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.\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"sessionStart\": [...],\n \"sessionEnd\": [...],\n \"userPromptSubmitted\": [...],\n \"preToolUse\": [...],\n \"postToolUse\": [...],\n \"errorOccurred\": [...]\n }\n }\n ```\n\n3. Configure a sintaxe do gancho nos campos das chaves `bash` e `powershell`, ou referencie diretamente os arquivos de script que você criou.\n\n > \\[!NOTE]\n > 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.\n > Copilot usa a chave apropriada com base no sistema operacional do usuário.\n\n * Este exemplo executa um script que gera a data de início da sessão para um arquivo de log usando o `sessionStart` gancho:\n\n ```json copy\n \"sessionStart\": [\n {\n \"type\": \"command\",\n \"bash\": \"echo \\\"Session started: $(date)\\\" >> logs/session.log\",\n \"powershell\": \"Add-Content -Path logs/session.log -Value \\\"Session started: $(Get-Date)\\\"\",\n \"cwd\": \".\",\n \"timeoutSec\": 10\n }\n ],\n ```\n\n * Este exemplo chama um script externo `log-prompt`:\n\n ```json copy\n \"userPromptSubmitted\": [\n {\n \"type\": \"command\",\n \"bash\": \"./scripts/log-prompt.sh\",\n \"powershell\": \"./scripts/log-prompt.ps1\",\n \"cwd\": \"scripts\",\n \"env\": {\n \"LOG_LEVEL\": \"INFO\"\n }\n }\n ],\n ```\n\n 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).\n\n4. 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.\n\n## Solução de problemas\n\nSe você encontrar problemas ao usar hooks, utilize a tabela a seguir para solucioná-los.\n\n| Questão | Ação |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Os ganchos não estão sendo executados | |\n| Ganchos estão atingindo o tempo limite | |\n| Saída JSON inválida | |\n\n## Resolução de Erros\n\nVocê pode depurar ganchos usando os seguintes métodos:\n\n* **Habilite o log detalhado** no script para inspecionar os dados de entrada e rastrear a execução do script.\n\n ```shell copy\n #!/bin/bash\n set -x # Enable bash debug mode\n INPUT=$(cat)\n echo \"DEBUG: Received input\" >&2\n echo \"$INPUT\" >&2\n # ... rest of script\n ```\n\n* **Teste ganchos localmente** canalizando a entrada de teste para o seu gancho para validar seu comportamento.\n\n ```shell copy\n # Create test input\n echo '{\"timestamp\":1704614400000,\"cwd\":\"/tmp\",\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"ls\\\"}\"}' | ./my-hook.sh\n\n # Check exit code\n echo $?\n\n # Validate output is valid JSON\n ./my-hook.sh | jq .\n ```\n\n## Leitura adicional\n\n* [Referência de ganchos do GitHub Copilot](/pt/copilot/reference/hooks-reference)\n* [Sobre o agente de nuvem do GitHub Copilot](/pt/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [Sobre GitHub Copilot CLI](/pt/copilot/concepts/agents/copilot-cli/about-copilot-cli)\n* [Configurar o ambiente de desenvolvimento](/pt/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)"}