Azure Pipelines 代理程式

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

您至少需要一個代理程式，才能使用 Azure Pipelines 建置程式代碼或部署軟體。隨著您的程式碼庫和團隊的成長，您需要多個代理程式。

當您的管線執行時，系統會開始一或多個作業。運算代理是一種運算基礎架構，已安裝代理程式軟體並可一次執行一個作業。

Azure Pipelines 提供數種不同類型的代理程式。

代理程式類型	描述	可用性
Microsoft 裝載的代理程式 \(英文\)	由 Microsoft 裝載和管理的代理程式。	Azure DevOps Services
自我裝載式代理程式	您設定和管理的代理程式，這些代理程式裝載在虛擬機器（VM）上。	Azure DevOps Services、Azure DevOps Server
管理的 DevOps 資源池代理程式	管理的 DevOps 集區是一項完全受控的服務。為代理程式提供支援的虛擬機器或容器位於 Microsoft Azure 訂用帳戶中，而不是您自己的 Azure 訂用帳戶中。	Azure DevOps Services
Azure 虛擬機器規模集代理	一種使用 Azure 虛擬機器擴展集的自行管理代理程式，可以自動擴充以滿足需求。如果您正在考慮使用具自動擴充功能的自我管理代理程式集區，我們建議您考慮使用受控的 DevOps 集區。如需詳細資訊，請參閱比較受控 DevOps 集區與 Azure 虛擬機器擴展集代理程式和受控 DevOps 集區概觀。	Azure DevOps Services

您可以直接在代理程式的主機上或容器中執行工作。

微軟託管代理程式

如果您的管線位於 Azure Pipelines 中，您可以使用 Microsoft 裝載的代理程式方便地執行作業。使用 Microsoft 裝載的代理程式時，維護和升級會自動發生。

您總是擁有您在管道中指定的最新版本的 VM 映像。每次執行流水線時，您都會為流水線中的每個作業取得全新的虛擬機器。虛擬機器會在一個任務後捨棄。工作對虛擬機器檔案系統所做的任何變更（例如檢出程式碼）在下一個工作上都無法使用。

Microsoft裝載的代理程式可以直接在 VM 或容器上執行作業。

Azure Pipelines 提供預先定義的代理程式集區 (名為 Azure Pipelines) 搭配 Microsoft 裝載的代理程式。

對於許多團隊來說，此程序是執行作業的最簡單方式。您可以先嘗試一下，看看它是否適用於您的組建或部署。如果不是，您可以使用虛擬機器規模設定集代理程式或自我裝載代理程式。

提示

您可以免費試用Microsoft裝載的代理程式。

深入瞭解Microsoft裝載的代理程式。

自行架設的代理程式

自我裝載代理程式是您設定為執行工作和管理自己的代理程式。您可以在 Azure Pipelines 或 Azure DevOps Server 中使用自我裝載代理程式。自我裝載代理程式可讓您進一步控制安裝建置和部署所需的相依軟體。此外，機器層級的快取和組態會在每次執行間持續保留，這有助於提高速度。

雖然每部電腦可以安裝多個代理程式，但我們強烈建議您每部電腦只安裝一個代理程式。當您安裝兩個或多個代理程式時，可能會對效能和管線結果產生負面影響。

提示

安裝自我裝載代理程式之前，您可能會想要查看Microsoft裝載的代理程式集區是否適合您。在許多情況下，Microsoft 裝載的代理程式集區是最簡單的入門方式。試試看。

您可以在 Linux、macOS 和 Windows 電腦上安裝代理程式。您也可以在 Docker 容器上安裝代理程式。如需安裝自我裝載式代理程式的詳細資訊，請參閱：

在 macOS 上，您需要清除下載歸檔中的特殊屬性，以避免每次執行 ./config.sh 時針對 TAR 檔案中的每個程序集顯示 macOS Gatekeeper 保護提示。下列命令會清除檔案上的擴充屬性：

xattr -c vsts-agent-osx-x64-V.v.v.tar.gz  ## replace V.v.v with the version in the filename downloaded.
 
# then unpack the gzip tar file normally:

tar xvfz vsts-agent-osx-x64-V.v.v.tar.gz

在電腦上安裝代理程式之後，您可以在該電腦上安裝工作所需的任何其他軟體。

注意

代理程式具有廣泛的向後相容性。任何版本的代理程式都應該與任何 Azure DevOps 版本相容，只要 Azure DevOps 不需要較高版本的代理程式即可。

我們僅支援最新版本的代理程式，因為這是唯一保證具有所有最新修補程式和錯誤修正的版本。

Node.js Runner 版本

代理程式隨附數個版本的 Node.js 程式庫，以支援使用不同 Node.js 處理常式的目標工作。

所有官方 Azure DevOps 工作都會使用 Node.js 20 程式庫作為通用處理常式。不過，客戶可能仍會使用已停用的 Node.js 6、Node.js 10 或 Node.js 16 程式庫的自訂工作。為了支援與已終止支援的節點的回溯相容性，我們提供下列自助服務方法，讓您可以手動安裝指定的 Node.js 執行器：

手動安裝 Node.js 6 執行程序或 Node.js 10 執行程序。如需詳細資訊，請參閱 Node.js 執行器支援。
請在需要使用過時的 Node.js 6 或 Node.js 10 程式庫的管線中使用 NodeTaskRunnerInstaller@0 任務。
安裝包含 Node.js 6 和 Node.js 10 程式庫的代理程式套件。

Azure Pipelines 提供兩個版本的代理程式套件：
- vsts-agent-\：支援 Node.js 6 和 Node.js 10 程式庫的套件。
- pipelines-agent-\：不支援 Node.js 6 和 Node.js 10 程式庫的套件。未來，此版本的套件會成為預設代理程式套件。
如果您的工作不需要 Node.js 6 或 Node.js 10 程式庫，而且您不想在代理程式電腦上安裝 Node.js 6 或 Node.js 10 程式庫，您可以從本文件的替代代理程式下載下安裝代理程式。

Azure 虛擬機器規模設置代理程式

Azure 虛擬機器規模集代理是一種自行託管代理形式，可以自動調節以符合您的需求。這種彈性可降低您不斷執行專用代理程式的需求。與 Microsoft 托管的代理程式不同，您可以自行決定執行代理程式的電腦大小和映像。

Azure Pipelines 會為您管理代理的擴展。指定下列因素：

虛擬機器規模設定集
維持待命狀態的代理數目
規模設定中虛擬機器的最大數目上限

如需詳細資訊，請參閱 Azure 虛擬機器擴展集代理程式。

管理的DevOps集區代理

受控DevOps集區可讓開發小組快速且輕鬆地啟動專為小組特定需求量身打造的 Azure DevOps 代理程式集區。

管理式DevOps集區

實作安全最佳實務。
提供平衡成本和效能的方法。
提供最常見案例的路徑。
大幅減少建立和維護自訂集區所需的時間。

管理的 DevOps 集區是 Azure 虛擬機器擴展集代理集區的演進。它透過提高自訂集區的可擴展性和可靠性，進一步簡化了自訂集區的建立。管理的 DevOps 集區是一項完全受控的服務。為代理程式提供支援的虛擬機器或容器位於 Microsoft Azure 訂用帳戶中，而不是您自己的 Azure 訂用帳戶中，類似於 Azure 虛擬機器擴展集代理程式集區。如需詳細資訊，請參閱受控 DevOps 集區文件。

平行作業

平行作業的概念代表您可以在組織中同時執行的工作數目。如果您的組織有單一平行作業，您可以在組織中一次執行單一作業。任何其他並行工作都會排入佇列，直到第一個工作完成為止。若要同時執行兩個作業，需要兩個平行作業。在 Azure Pipelines 中，您可以在 Microsoft 裝載的基礎結構或自己的 (自我裝載式) 基礎結構上執行平行作業。

預設情況下，Microsoft 在每個至少包含一項平行作業的組織中提供免費服務層。視您需要執行的並行管線數目而定，您可能需要更多平行作業，才能同時使用多個 Microsoft 裝載的或自我裝載式代理程式。如需平行作業和不同免費層服務的詳細資訊，請參閱 Azure Pipelines 中的平行作業。

您可能需要更多平行作業，才能同時使用多個代理程式：

Azure DevOps Server 中的平行作業

重要

從 Azure DevOps Server 2019 開始，您不需要為版本中的自我裝載並行作業付費。您只受限於您擁有的代理程式數目。

Capabilities

每個自我裝載的代理程式都有一組功能，指出它可以做什麼。功能是名稱/值組，其為：

代理程式軟體探索到的功能，稱為 系統功能。
您定義的功能稱為 使用者功能。

代理軟體會自動判斷各種系統功能。這些功能包括機器名稱、作業系統類型以及機器上安裝的某些軟體的版本。此外，機器中定義的環境變數會自動出現在系統功能清單中。

當您將環境變數儲存為功能時，儲存的功能值會用來在代理程式執行時設定環境變數。此外，當您在代理程式執行時對環境變數進行任何變更時，任何工作都不會挑選和使用它們。如果您不想將變更的敏感性環境變數儲存為功能，您可以指示代理程式忽略它們。設定 VSO_AGENT_IGNORE 環境變數，以及要忽略的逗號分隔變數清單。例如， PATH 如果您要安裝軟體，您可能會想要忽略的重要變數。

當您撰寫管線時，您可以指定代理程式的特定需求。系統只會將工作傳送給具有符合管線中指定需求的功能的代理程式。因此，代理程式功能可讓您將作業導向特定代理程式。

需求和功能專為搭配自行架設的代理程式使用而設計，以便讓作業能夠匹配符合需求的代理程式。當您使用由 Microsoft 託管的代理程式時，您可以選取符合作業需求的代理程式映像檔。雖然可以將功能新增至Microsoft託管的代理程式，但對於Microsoft託管的代理程式，您不需要使用這些功能。

若要將需求新增至 YAML 組建管線，請將這 demands: 一行新增至 pool 區段。

pool:
  name: Default
  demands: SpecialSoftware # exists check for SpecialSoftware

您可以檢查功能是否存在，或與功能的值進行比較。如需詳細資訊，請參閱 YAML 架構 - 需求。

名稱	Condition	價值
`SpecialSoftware`	Exists	n/a
`Agent.OS`	等於	Linux

設定代理程式功能

Azure Pipelines UI
Azure DevOps CLI

您可以檢視代理程式詳細資料，包括版本和系統功能，並管理其使用者功能。移至 [代理程式集區 ]，然後選取所需代理程式 的功能索引標籤 。

在您的網頁瀏覽器中，移至 代理程式集區：
1. 登入您的組織 (https://dev.azure.com/{yourorganization})。
2. 選取 [Azure DevOps>組織設定]。
3. 選取 代理程式集區。
1. 登入您的專案集合（http://your-server/DefaultCollection）。
2. 選取 [Azure DevOps>集合設定]。
3. 選取 代理程式集區。
移至 [功能] 索引標籤：
1. 從 [ 代理程式集區] 索引卷標中，選取所需的代理程式集區。
2. 選取 [ 代理程式 ]，然後選擇所需的代理程式。
3. 選擇功能標籤頁。
  
  注意
  
  Microsoft裝載的代理程式不會顯示系統功能。如需Microsoft裝載代理程式上安裝的軟體清單，請參閱使用Microsoft裝載的代理程式。
1. 從 [ 代理程式集區 ] 索引卷標中，選取所需的集區。
2. 選取 [ 代理程式 ]，然後選擇所需的代理程式。
3. 選擇功能標籤頁。
若要向代理程式註冊新功能，請選取 新增功能。

您可以檢視代理程式詳細資料，包括版本和功能。使用下列 az pipelines agent Azure CLI 方法。

列出代理程序 | 顯示代理程序詳細數據

注意

如果這是您第一次使用 az pipelines 命令，請參閱開始使用 Azure DevOps CLI。

列出代理

您可以使用命令 az pipelines agent list 列出您的代理程式。

az pipelines agent list --pool-id
                        [--agent-name]
                        [--demands]
                        [--detect {false, true}]
                        [--include-assigned-request {false, true}]
                        [--include-capabilities {false, true}]
                        [--include-last-completed-request {false, true}]
                        [--org]
                        [--subscription]

參數

pool-id：（必要）包含代理程式的代理池。
agent-name：根據客服專員名稱進行篩選。
demands：按客服專員可以滿足的需求進行篩選。逗號分隔的清單。
detect：自動檢測組織。接受的值是 false 和 true。
include-assigned-request：決定是否包含客服專員目前工作的詳細資料。接受的值是 false 和 true。
include-capabilities：決定是否在回應中包含客服專員的功能。接受的值是 false 和 true。
include-last-completed-request：決定是否包含客服專員最近完成工作的詳細資訊。接受的值是 false 和 true。
org 或 organization：Azure DevOps 組織 URL。您可以使用 az devops configure -d organization=ORG_URL 來設定預設組織。如果未設定為預設值或透過 git config 取得，則需要此參數。範例： https://dev.azure.com/MyOrganizationName/。
subscription：訂閱的名稱或識別碼。您可以使用 az account set -s NAME_OR_ID 來設定預設的訂閱帳戶。

範例

下列範例會以表格格式列出集區 ID: 4 中的所有代理程式。若要擷取集區的 ID，請使用 az pipelines pool list。此範例使用下列預設組態： az devops configure --defaults organization=https://dev.azure.com/fabrikam-tailspin project=FabrikamFiber。

az pipelines agent list --pool-id 4 --output table

ID    Name          Is Enabled    Status    Version
----  ------------  ------------  --------  ---------
3     Hosted Agent  True          offline   2.155.1

顯示代理詳細信息

您可以使用命令 az pipelines agent show 擷取代理程式詳細資料。

az pipelines agent show --agent-id
                        --pool-id
                        [--detect {false, true}]
                        [--include-assigned-request {false, true}]
                        [--include-capabilities {false, true}]
                        [--include-last-completed-request {false, true}]
                        [--org]
                        [--subscription]

參數

agent-id 或 id：（必要）要取得相關資訊的客服專員 ID。
pool-id：（必要）包含代理程式的代理池。
detect：自動檢測組織。接受的值是 false 和 true。
include-assigned-request：決定是否包含客服專員目前工作的詳細資料。接受的值是 false 和 true。
include-capabilities：決定是否在回應中包含客服專員的功能。接受的值是 false 和 true。
include-last-completed-request：決定是否包含客服專員最近完成工作的詳細資訊。接受的值是 false 和 true。

您可以使用 Windows 驗證來執行工作，以存取外部服務。代理程式在與代理程式交互時，必須以具有管線或變數群組中該服務存取權的帳戶運行。

代理程式與 Azure Pipelines 之間交換之訊息承載會使用非對稱加密來保護。每個代理程式都有公開-私密金鑰組，且公開金鑰會在註冊期間與伺服器交換。伺服器會使用公開金鑰來加密工作的承載，然後再將工作傳送至代理程式。代理程式會使用其私密金鑰來解密工作內容。 gentCloudRequest": null,


  <Some properties omitted for space>

  "status": "offline",
  "statusChangedOn": null,
  "systemCapabilities": {
    "ANDROID_HOME": "",
    "ANDROID_NDK_HOME": "",
    "Agent.Name": "Hosted Agent",
    "Agent.Version": "2.160.1",

    <Some capabilities omitted for space>

    "sh": "",
    "subversion": "",
    "svn": "",
    "To run tasks using Windows authentication to access an external service, the agent must run under an account with access to that service.

如果您正在執行像 Selenium 這樣的 UI 測試，或需要使用瀏覽器的 Coded UI 測試，則瀏覽器會在代理帳戶的環境中開啟。

在 Windows 上，建議您使用網路服務或本機服務等服務帳戶。這些帳戶具有不受限制的權限和不會過期的密碼。隨著時間的推移，此過程減少了代理管理的需求。

這些認證與您向 Azure Pipelines 或 Azure DevOps Server 註冊代理程式時所使用的認證不同。

Azure DevOps Server 不支援 Azure DevOps CLI 命令。

提示

在自我裝載代理程式上安裝新軟體之後，您必須重新啟動代理程式，才能顯示新功能。如需詳細資訊，請參閱重新啟動 Windows 代理程式、重新啟動 Linux 代理程式和重新啟動 Mac 代理程式。

通訊

與 Azure Pipelines 通訊

與 Azure DevOps Server 通訊

代理程式會與 Azure Pipelines 或 Azure DevOps Server 通訊。它會決定需要執行的工作，並報告記錄和工作狀態。代理人一律會起始此通訊。

根據您設定代理程式的方式，從代理程式往 Azure Pipelines 或 Azure DevOps Server 的所有訊息都會經由 HTTPS 或 HTTPS 傳送。此提取模型可讓您將代理程式設定為不同的拓撲，如下列範例所示。

以下是代理程式與 Azure Pipelines 或 Azure DevOps Server 之間的常見通訊模式：

用戶藉由將代理程式新增至代理程式集區，向 Azure Pipelines 或 Azure DevOps Server 註冊代理程式。若要在該代理程式集區中註冊代理程式，您必須具有代理程式集區系統管理員角色。 代理程式集區系統管理員角色只有在註冊時才需要，而且不會保存在代理程式上。它不會用於代理程式與 Azure Pipelines 或 Azure DevOps Server 之間的任何進一步通訊。

註冊完成後，代理程式會下載 a listener OAuth token 並使用它來接聽工作佇列。
代理程式使用 HTTP 長輪詢來監聽，查看是否有新的作業請求已張貼在 Azure Pipelines 或 Azure DevOps Server 的作業佇列中。當工作可用時，代理程式會下載工作以及 job-specific OAuth token。 Azure Pipelines 或 Azure DevOps Server 會為管線中指定的範圍身分識別產生短效權杖。

代理會使用權杖來存取或修改該作業內 Azure Pipelines 或 Azure DevOps Server 上的資源。例如，它使用權杖來存取原始程式碼或上傳測試結果。
代理程式會在任務完成後捨棄任務特定的 OAuth 權杖，然後使用接聽程式 OAuth 權杖檢查是否有新的任務請求。

代理程式與 Azure Pipelines 或 Azure DevOps Server 之間交換之訊息承載會使用非對稱加密來保護。

每個代理程式都有公開-私密金鑰組，且公開金鑰會在註冊期間與伺服器交換。伺服器會使用公開金鑰來加密工作的承載，然後再將工作傳送至代理程式。代理程式會使用其私密金鑰來解密工作內容。

此方法會在與代理程式交換時保護儲存在管線或變數群組中的秘密。

注意

代理程式支援UTF-8用戶端編碼輸出。但是，如果您的系統不使用 UTF-8 編碼，您可能會遇到一些日誌輸出問題。例如，日誌可能包含系統編碼無法辨識的字元，因此它們可能看起來是亂碼或缺少符號。

進行通訊以部署至目標伺服器

當您使用代理程式將成品部署至伺服器組時，代理程式必須具備對這些伺服器的「直接視線」連線。根據預設，Microsoft 裝載的代理程式集區會連線到 Azure 中執行的 Azure 網站和伺服器。

如果您的 Azure 資源在 Azure 虛擬網路中執行，您可以取得部署 Microsoft 裝載代理程式的代理程式 IP 範圍。然後，您可以設定 Azure 虛擬網路的防火牆規則，以允許代理程式存取。

如果您的內部部署環境無法連線到Microsoft裝載的代理程式集區，這通常是因為中繼防火牆所致，您必須在內部部署計算機上手動設定自我裝載代理程式。代理程式必須連線到目標內部部署環境，並存取因特網，才能連線到 Azure Pipelines 或 Azure DevOps Server。此過程如以下原理圖所示：

驗證

若要註冊代理程式，您必須是代理程式集區中系統管理員角色的成員。代理程式集區管理員的身分識別只有在註冊時才需要，而且不會保存在代理程式上。它不會用於代理程式與 Azure Pipelines 或 Azure DevOps Server 之間的任何後續通訊。若要設定代理程式，您也必須是伺服器上的本機管理員。

當您註冊代理程式時，請從下列驗證類型中選取。代理程式設定程序會提示您輸入每種驗證類型所需的特定附加資訊。如需詳細資訊，請參閱自我裝載代理程式驗證選項。

個人存取權杖。
替代：使用基本驗證連線到 Azure DevOps Server。當您選取 [替代] 時，系統會提示您輸入認證。

此外，Windows 代理程式在 Azure DevOps Server 上有下列兩個驗證選項。

協商：使用 Windows 驗證機制（例如，新技術 LAN 管理員（NTLM）或 Kerberos）以登入使用者以外的身份連線到 Azure DevOps Server。選取 [ 交涉] 之後，系統會提示您輸入認證。
整合：（預設）透過 Windows 驗證配置，使用已登入使用者的認證，將 Windows 代理程式連線到 Azure DevOps Server （例如 NTLM 或 Kerberos）。選取此方法之後，系統不會提示您輸入認證。

重要

您必須設定伺服器以支援驗證方法，以使用替代、交涉或整合驗證。

您用來註冊代理程式的驗證方法只會在代理程式註冊期間使用。若要深入瞭解代理程式在註冊后如何與 Azure Pipelines 通訊，請參閱與 Azure Pipelines 或 Azure DevOps Server 通訊。

互動與服務的比較

您可以將自我託管的代理程式作為服務或互動式進程來運行。

設定代理程式之後，建議您先以互動模式試用，以確保其運作正常。然後，對於生產用途，我們建議您以下列其中一種模式執行代理程式，使其可靠地保持執行中狀態。這些模式也可確保在電腦重新啟動時自動啟動代理程式。

作為服務：您可以使用作業系統的服務管理員來管理代理程式的生命週期。當您將代理程式作為服務執行時，自動升級代理程式的體驗會更好。
作為啟用自動登入的互動式程式：在某些情況下，您可能需要以互動方式執行代理程式以供生產使用（例如，執行 UI 測試）。當您將代理程式配置為在此模式下執行時，螢幕保護程式會停用。某些網域原則可能會阻止您啟用自動登入或停用螢幕保護程式。在這種情況下，您可能需要尋求網域原則的豁免，或在不適用網域原則的工作組計算機上執行代理程式。

注意

啟用自動登入或停用螢幕保護程式時存在安全風險。其他使用者可能能夠存取電腦，並使用自動登入的帳戶。如果您將代理程式設定為以這種方式執行，則必須確保電腦受到實體保護（例如，位於安全設施中）。

如果您使用遠端桌面平台存取執行代理程式並自動登入的電腦，關閉遠端桌面平台會導致電腦鎖定。在此代理程式上執行的任何 UI 測試都可能失敗。若要避免此問題，請使用命令 tscon 中斷與遠端桌面平台的連線。例如：

%windir%\System32\tscon.exe 1 /dest:console

代理人帳戶

無論您是以服務或互動方式執行代理程式，都可以選擇用來執行代理程式的計算機帳戶。代理程式帳戶的選擇完全取決於在建置和部署作業中執行之工作的需求。

例如，若要使用 Windows 驗證來存取外部服務來執行工作，代理程式必須使用具有該服務存取權的帳戶來執行。但是，如果您正在執行需要瀏覽器的 UI 測試，例如 Selenium 或 Coded UI 測試，瀏覽器會在代理程式帳戶的上下文中開啟。

在 Windows 上，建議您使用網路服務或本機服務等服務帳戶。這些帳戶權限受到限制，且其密碼不會過期，因此隨著時間的推移，代理程式需要較少的管理。

這些認證與您向 Azure Pipelines 或 Azure DevOps Server 註冊代理程式時所使用的認證不同。

代理程式版本與升級

我們會每隔幾周在 Azure Pipelines 中更新代理程序軟體。我們會以格式 {major}.{minor}指出代理程式版本。例如，如果代理程式版本是 2.1，則主要版本是 2 ，而次要版本為 1。

我們會讓 Microsoft 裝載的代理程式保持最新狀態。如果較新版本的代理程式僅在次要版本中有所不同，Azure Pipelines 可以自動更新自我託管的代理程式。預設設定已啟用。您可以在 代理程式集區 中設定此設定，方法是選取您的代理程式，然後選取 [設定]。當平台功能或管線中的其中一個工作需要較新版本的代理程式時，會要求升級。

如果您以互動方式執行自我裝載代理程式，或有較 新的主要 代理程式版本可供使用，則您可能必須手動升級代理程式。您可以從組織下的 代理程式集區 索引標籤升級代理程式。沒有相容的代理程式，管線就無法執行。

更新自託管代理程式

移至 [專案設定>] [代理程式集區]。
選取您的代理程式集區，然後選取 [更新所有代理程式]。

您也可以從...選單中選取更新代理程式，以個別更新代理程式。
選取 [ 更新 ] 以確認。
更新要求會針對集區中的每一個代理程式排入佇列，並在任何目前執行中的工作完成時執行。升級通常只需要幾分鐘。此時間量足以下載最新版本的代理程式軟體（約 200 MB）、解壓縮，然後使用新版本重新啟動代理程式。您可以在 [代理程式] 索引標籤上監視代理程式的狀態。

我們會隨著每次 Azure DevOps Server 更新來更新代理程式軟體。我們會以格式 {major}.{minor}指出代理程式版本。例如，如果代理程式版本是 2.1，則主要版本為 2，次要版本為 1。

當您的 Azure DevOps Server 擁有較新版本的代理程式，而且該新代理程式僅在次要版本上有所不同時，通常可以自動完成升級。當您在管線中使用的平台功能或其中一個工作需要較新版本的代理程式時，會要求升級。從 Azure DevOps Server 2019 開始，您不需要等候新的伺服器版本。您可以將新版本的代理程式上傳至應用層，而該版本會作為升級提供。

如果您以互動方式執行代理程式，或代理程式的較新主要版本可用，則可能必須手動升級代理程式。您可以從專案集合下的 [代理程式集區] 索引標籤輕鬆升級代理程式。沒有相容的代理程式，管線就無法執行。

您可以檢視代理程式的版本。移至 [代理程式集區 ]，然後選取所需代理程式 的功能索引標籤 ，如設定代理程式功能中所述。

若要以程式設計方式觸發代理程式更新，您可以使用 代理程式更新 API ，如如何以程式設計方式觸發特定代理程式集區的代理程式更新一節所述。

對於無法存取網際網路的伺服器，請手動將代理程式 ZIP 檔案複製到下列資料夾，以用作本機檔案。建立 Agents 資料夾（如果不存在）：

Windows：%ProgramData%\Microsoft\Azure DevOps\Agents
Linux：usr/share/Microsoft/Azure DevOps/Agents
macOS：usr/share/Microsoft/Azure DevOps/Agents

代理程式目錄結構

當管線工作在代理程式上執行時，會建立目錄結構來儲存原始程式碼、二進位檔和成品。

代理程式的主目錄是安裝代理程序的目錄。目錄通常位於：

Microsoft 裝載的代理程式： C:\agents\<agent version> 在 Windows、 /Users/runner/runners/<agent version> macOS 和 /home/vsts/agents/<agent version> Linux 上。
自行管理代理程式： C:\agent 在 Windows 上、Users/<username>/agent 在 macOS 上及 ~/agent 在 Linux 上。

代理程式的工作目錄包含儲存來源和作業輸出的工作區。工作目錄通常位於：

Microsoft 裝載的代理程式： C:\a 在 Windows、 /Users/runner/work macOS 和/home/vsts/work Linux 上。
自我裝載代理程式： C:\agent\_work 在 Windows、 ~/agent/work macOS 和 /home/agent/_work Linux 上。

工作目錄結構為：


    - /work directory
        - /1 build directory/pipeline workspace
            - /s source/working directory
            - /b binaries directory
            - /a artifacts staging directory
            - /TestResults Test results directory

目錄	描述	例子	預先定義的變數
代理主目錄	代理程式的安裝位置。	Microsoft 裝載的代理程式： Windows：`C:\agents\3.248.0` Linux：`/home/vsts/agents/3.248.0` macOS：`/Users/runner/runners/3.248.0` 自託管代理程式： Windows：`C:\agent` Linux：`home/agent` macOS：`~/agent`	`Agent.HomeDirectory`
工作目錄	代理程式儲存原始程式碼、二進位檔和成品的位置。	Microsoft 裝載的代理程式： Windows：`C:\a` Linux：`/home/vsts/work` macOS：`/Users/runner/work` 自託管代理程式： Windows：`C:\agent\_work` Linux：`/home/agent/_work` macOS：`~/agent/work`	`Agent.WorkFolder` `Agent.RootDirectory` `System.WorkFolder`
建置目錄或工作區	管線作業的執行位置。	Microsoft 裝載的代理程式： Windows：`C:\a\1` Linux：`/home/vsts/work/1` macOS：`/Users/runner/work/1` 自託管代理程式： Windows：`C:\agent\_work\1` Linux：`/home/agent/_work/1` macOS：`~/agent/work/1`	`Agent.BuildDirectory` `Pipeline.Workspace`
`s` - 來源或工作目錄	包含從存放庫取出的原始程式碼。如果您的工作中有多個`checkout`步驟，那麼原始程式碼會被檢出到以儲存庫命名的目錄中，作為`s`的子資料夾。	Microsoft 裝載的代理程式： Windows：`C:\a\1\s` Linux：`/home/vsts/work/1/s` macOS：`/Users/runner/work/1/s` 自託管代理程式： Windows：`C:\agent\_work\1\s` Linux：`/home/agent/_work/1/s` macOS：`~/agent/work/1/s`	`Build.SourcesDirectory` `Build.RepositoryLocalPath` `System.DefaultWorkingDirectory`
`b` - 二進位檔目錄	包含建置輸出。	Microsoft 裝載的代理程式： Windows：`C:\a\1\b` Linux：`/home/vsts/work/1/b` macOS：`/Users/runner/work/1/b` 自託管代理程式： Windows：`C:\agent\_work\1\b` Linux：`/home/agent/_work/1/b` macOS：`~/agent/work/1/b`	`Build.BinariesDirectory`
`a` - 構件預備目錄	包含組建工件。會在自我託管代理程式每次執行之間清理。	Microsoft 裝載的代理程式： Windows：`C:\a\1\a` Linux：`/home/vsts/work/1/a` macOS：`/Users/runner/work/1/a` 自託管代理程式： Windows：`C:\agent\_work\1\a` Linux：`/home/agent/_work/1/a` macOS：`~/agent/work/1/a`	`Build.StagingDirectory` `Build.ArtifactStagingDirectory` `System.ArtifactsDirectory`
`TestResults` 目錄	包含測試結果。會在自我託管代理程式每次執行之間清理。	Microsoft 裝載的代理程式： Windows：`C:\a\1\TestResults` Linux：`/home/vsts/work/1/TestResults` macOS：`/Users/runner/work/1/TestResults` 自託管代理程式： Windows：`C:\agent\_work\1\TestResults` Linux：`/home/agent/_work/1/TestResults` macOS：`~/agent/work/1/TestResults`	`Common.TestResultsDirectory`

在 Microsoft 裝載的代理程式上，每次執行都會使用不同的代理程式，因此不會在執行之間保留工作目錄。在自我管理代理程式上，依預設，只會在執行之間清除構件暫置目錄及測試結果目錄。如需工作區清除選項的詳細資訊，請參閱工作區。

如需預先定義變數的詳細資訊，請參閱預先定義的變數。

FAQ

如何確保我擁有最新的代理程式版本？

移至 代理集區 標籤頁：
1. 登入您的組織 (https://dev.azure.com/{yourorganization})。
2. 選取 [Azure DevOps>組織設定]。
3. 選取 代理程式集區。
1. 登入您的專案集合（http://your-server/DefaultCollection）。
2. 選取 [Azure DevOps>集合設定]。
3. 選取 代理程式集區。
選取包含代理程式的集區。
請確定代理程式已啟用。
移至功能索引標籤：
1. 從 [ 代理程式集區] 索引卷標中，選取所需的代理程式集區。
2. 選取 [ 代理程式 ]，然後選擇所需的代理程式。
3. 選擇功能標籤頁。
  
  注意
  
  Microsoft裝載的代理程式不會顯示系統功能。如需Microsoft裝載代理程式上安裝的軟體清單，請參閱使用Microsoft裝載的代理程式。
1. 從 [ 代理程式集區 ] 索引卷標中，選取所需的集區。
2. 選取 [ 代理程式 ]，然後選擇所需的代理程式。
3. 選擇功能標籤頁。
尋找 Agent.Version 功能。您可以將此值與 Azure Pipelines 代理程式頁面上最新發佈的代理程式版本進行比較。
當每個代理程式執行需要較新版本代理程式的工作時，就會自動更新它本身。如果您想要手動更新某些代理程式，請以滑鼠右鍵按一下集區，然後選取 [更新所有代理程式]。

我可以更新屬於 Azure DevOps Server 集區一部分的代理程式嗎？

是。從 Azure DevOps Server 2019 開始，您可以將伺服器設定為在本機磁碟上尋找代理程式套件檔案。此配置會覆蓋伺服器在發行時提供的預設版本。當伺服器無法存取因特網時，也會套用此案例。

從具有因特網存取的電腦，從 Azure Pipelines 代理程式 GitHub 版本頁面下載最新版本的代理程式套件檔案（.zip 或 .tar.gz 形式）。
使用您選擇的方法（，將下載的套件檔案傳輸至每個 Azure DevOps Server 應用程式層（例如 USB 磁碟驅動器、網路傳輸等等）。將代理程式檔案放在資料夾下 %ProgramData%\Microsoft\Azure DevOps\Agents 。如果沒有標示為 「代理程式」的資料夾，請建立一個。
一切準備就緒! 您的 Azure DevOps Server 現在會在更新代理程式時使用本機檔案。當每個代理程式執行需要較新版本代理程式的工作時，就會自動更新它本身。但如果您想要手動更新某些代理程式，請以滑鼠右鍵按兩下集區，然後選擇 [ 更新所有代理程式]。

自行託管的代理程式是否具有比 Microsoft 託管的代理程式更好的效能優勢？

在許多情況下，是。若您使用自我裝載代理程式，您可以執行累加建置。例如，如果您定義未清除存放庫且不會執行全新組建的管線，您的組建通常會更快執行。除非您使用快取等功能，否則您無法使用 Microsoft 裝載的代理程式取得這些優點，因為代理程式會在管線完成之後終結。

Microsoft 裝載的代理程式可能需要較長時間才能啟動您的組建。雖然通常只需要幾秒鐘的時間，您的作業就會指派給 Microsoft 裝載的代理程式，但有時可能需要幾分鐘的時間才能配置代理程式，視我們系統上的負載而定。

可以在同一部電腦上安裝多個自我裝載代理程式嗎？

是。此方法可能適用於執行不耗用許多共用資源之作業的代理程式。例如，您可以嘗試執行大部分協調部署之版本的代理程式，而且不會在代理程式本身執行太多工作。

您可能會發現在其他情況下，您無法在同一部計算機上執行多個代理程式來獲得太多效率。例如，對於執行耗用大量磁碟空間和輸入/輸出資源的組建的代理程式來說，可能不值得這樣做。

如果平行建置作業使用相同的單一工具部署（例如 npm 套件），您也可能會遇到問題。一個組建可能會在另一個組建使用依賴項時更新依賴項，這可能會導致不可靠的結果和錯誤。

取消管線作業時，客服人員會做什麼？

針對由 Microsoft 裝載的代理程式，代理程式會被終止並返回至 Azure Pipelines 集區。

針對自我託管的代理程式：

取消管線時，代理程式會將一系列命令傳送至執行目前步驟的進程。
第一個命令的傳送逾時為 7.5 秒。
如果進程未終止，則會傳送第二個命令，逾時時間為 2.5 秒。
如果程序未終止，代理程式會指令終止它。
如果程序忽略前兩次終止請求，則會被強制終止。

從初始請求到終止的時間約為 10 秒。

發出給處理程序以取消管線的命令會因代理程式作業系統而異：

macOS 和 Linux：傳送的命令依次為 SIGINT、SIGTERM、SIGKILL。
Windows：傳送至進程的命令是 Ctrl+C，後面跟 Ctrl+Break著，後面跟著 Process.Kill。

如何以程式設計方式觸發特定代理程式集區的代理程式更新？

您可以使用下列 API 來觸發集區的代理程式更新：

POST https://dev.azure.com/{organization}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0

POST https://{server url}/tfs/{collection}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0

注意

如需詳細資訊，請參閱 API 和 Azure DevOps Server 版本對應。

URI 參數

名稱	在	必須的	類型	描述
`agentId`	查詢	`False`	字串	要更新的代理程式。如果未指定，則會針對所有代理程式觸發更新。
`organization`	路徑	`True`	字串	Azure DevOps 組織的名稱。
`poolId`	路徑	`True`	整數 int32	要使用的代理程式集區。
`api-version`	查詢	`False`	字串	要使用的 API 版本。若要使用此版本的 API，應將值設定為 `6.0`。

若要觸發代理程式更新，要求內文應為空。

Azure Pipelines 代理程式是 GitHub 上的開放原始碼。

如需代理程式的詳細資訊，請參閱使用 Azure DevOps 建置應用程式學習路徑中的下列模組：

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-08