{"meta":{"title":"Acerca de los ganchos para GitHub Copilot","intro":"Amplíe y personalice GitHub Copilot el comportamiento del agente ejecutando comandos de shell personalizados en puntos clave durante la ejecución del agente.","product":"GitHub Copilot","breadcrumbs":[{"href":"/es/copilot","title":"GitHub Copilot"},{"href":"/es/copilot/concepts","title":"Conceptos"},{"href":"/es/copilot/concepts/agents","title":"Agentes"},{"href":"/es/copilot/concepts/agents/hooks","title":"Hooks"}],"documentType":"article"},"body":"# Acerca de los ganchos para GitHub Copilot\n\nAmplíe y personalice GitHub Copilot el comportamiento del agente ejecutando comandos de shell personalizados en puntos clave durante la ejecución del agente.\n\n## ¿Qué son los ganchos?\n\nLos enlaces son una manera de 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, cuando se escribe un mensaje o cuando se llama a una herramienta.\n\nLos 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:\n\n* Aprobar o denegar ejecuciones de herramientas mediante programación.\n* Use características de seguridad integradas, como el examen de secretos, para evitar pérdidas de credenciales.\n* Implemente reglas de validación personalizadas y registro de auditoría para el cumplimiento.\n\nLos ganchos están disponibles para usar con:\n\n* **agente en la nube de Copilot** en GitHub.\n* **CLI de GitHub Copilot** en tu terminal.\n\nLos enlaces se definen en archivos JSON, almacenados en el repositorio en `.github/hooks/*.json`. Se aplican siempre que se utilicen agentes de Copilot en el repositorio.               CLI de Copilot también admite enlaces personales que se almacenan en su directorio de inicio en `~/.copilot/hooks/*.json`. Se aplican cada vez que se usa CLI de Copilot.\n\n## Tipos de enlaces\n\nEstán disponibles los siguientes tipos de hooks:\n\n* **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.\n* **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.\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.\n* **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.\n* **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.\n* **agentStop**: se ejecuta cuando el agente principal ha terminado de responder a la solicitud.\n* **subagentStop**: se ejecuta cuando se completa un subagente, antes de devolver los resultados al agente primario.\n* **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.\n\nPara ver una referencia completa de tipos de enlace con casos de uso de ejemplo, procedimientos recomendados y patrones avanzados, consulte [Referencia de enlaces de GitHub Copilot](/es/copilot/reference/hooks-reference).\n\n## Formato de configuración de gancho\n\nConfigura 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.\n\n```json copy\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"sessionStart\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"string (optional)\",\n        \"powershell\": \"string (optional)\",\n        \"cwd\": \"string (optional)\",\n        \"env\": { \"KEY\": \"value\" },\n        \"timeoutSec\": 30\n      }\n    ],\n  }\n}\n```\n\nEl objeto de enlace puede contener las siguientes claves:\n\n| Propiedad    | Obligatorio           | Description                                                               |\n| ------------ | --------------------- | ------------------------------------------------------------------------- |\n| `type`       | Sí                    | Debe ser `\"command\"`                                                      |\n| `bash`       | Sí (en sistemas Unix) | Ruta de acceso al script de Bash que se va a ejecutar                     |\n| `powershell` | Sí (en Windows)       | Ruta de acceso al script de PowerShell que se va a ejecutar               |\n| `cwd`        | No                    | Directorio de trabajo para el script (relativo a la raíz del repositorio) |\n| `env`        | No                    | Variables de entorno adicionales que se combinan con el entorno existente |\n| `timeoutSec` | No                    | Tiempo máximo de ejecución en segundos (valor predeterminado: 30)         |\n\n## Archivo de configuración de enlace de ejemplo\n\nEste es un archivo de configuración de ejemplo que reside en `~/.github/hooks/project-hooks.json` dentro de un repositorio.\n\n```json copy\n{\n  \"version\": 1,\n  \"hooks\": {\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    \"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    \"preToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/security-check.sh\",\n        \"powershell\": \"./scripts/security-check.ps1\",\n        \"cwd\": \"scripts\",\n        \"timeoutSec\": 15\n      },\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/log-tool-use.sh\",\n        \"powershell\": \"./scripts/log-tool-use.ps1\",\n        \"cwd\": \"scripts\"\n      }\n    ],\n    \"postToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"cat >> logs/tool-results.jsonl\",\n        \"powershell\": \"$input | Add-Content -Path logs/tool-results.jsonl\"\n      }\n    ],\n    \"sessionEnd\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/cleanup.sh\",\n        \"powershell\": \"./scripts/cleanup.ps1\",\n        \"cwd\": \"scripts\",\n        \"timeoutSec\": 60\n      }\n    ]\n  }\n}\n```\n\n## Consideraciones sobre el rendimiento\n\nLos 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:\n\n* **Minimizar el tiempo de ejecución**: mantenga el tiempo de ejecución del enlace en menos de 5 segundos cuando sea posible.\n* **Optimizar el registro**: use el registro asincrónico, como anexar a archivos, en lugar de E/S sincrónica.\n* **Usar el procesamiento en segundo plano**: para operaciones costosas, considere la posibilidad de procesar en segundo plano.\n* **Resultados de caché: almacene en caché** cálculos costosos cuando sea posible.\n\n## Consideraciones de seguridad\n\nPara garantizar que la seguridad se mantiene al usar enlaces, tenga en cuenta las siguientes consideraciones:\n\n* **Valide y corrija siempre la entrada procesada por enlaces**. La entrada que no es de confianza podría provocar un comportamiento inesperado.\n* ```\n            **Utilice el escape adecuado del shell al construir comandos**. Esto evita vulnerabilidades de inyección de comandos.\n  ```\n* **Nunca registre datos confidenciales, como tokens o contraseñas**.\n* **Asegúrese de que los scripts de gancho y los logs tengan los permisos adecuados**.\n* **Tenga cuidado con los enlaces que realizan llamadas de red externas**. Estos pueden introducir latencia, errores o exponer datos a terceros.\n* **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.\n\n## Pasos siguientes\n\nPara empezar a crear hooks, consulte:\n\n* [Personalización de flujos de trabajo de agente con enlaces](/es/copilot/how-tos/use-copilot-agents/cloud-agent/use-hooks) para agente en la nube de Copilot\n* [Uso de enlaces con CLI de GitHub Copilot](/es/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) para CLI de GitHub Copilot"}