In Focus

How To Install, Configure And Unconfigure Build Agent In TFS 2015

In this article, I’ll explain how to configure the agent as a service. To run a build or release definition we need at least one agent. So let’s start.

What is an Agent?

An agent can be defined as an installable software that runs one build or deployment job at a time.

Where we can install an Agent

You can install the agent on Linux, macOS, or Windows machines. You can also install an agent on a Linux Docker container as well.

How to see the agent on TFS 2015

You can view the version of an agent by navigating to the Agent pools hub and selecting the Capabilities tab for the desired agent.

TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool

Server

STEP 1 - Open TFS server

To configure the agent in an agent pool you should have administrator rights.

Here, I am using TFS 2015 so to open agent pool, enter the URL as specified:

TFS 2015: http://TfsServerName:8080/tfs/_admin/_AgentPool

 

Server

 

 This will open the agent pool for the project collection.
 
 Server
STEP 2 - Download the agent

Click on the download agent link on the left side to download the zip file.

Server

It will ask you to save/open the zip file. Save the agent.zip file.

Server

 

Extract the zip file.

Server

This will give below content inside the Agent folder.
Server

STEP 3 - Configure the Agent
  1. To configure the agent right click on RunAgent.cmd and run as an administrator as shown.

    Server

  2. This will create a _diag folder and settings.json file under the agent folder.

    Server

  3. If you open the settings.json file, it contains the information about your AgentName, PoolId, PoolName etc.

    Server

    NOTE
    ServerUrl, PoolId, AgentId will generate after configuring the agent with the TFS server.

  4. Now, right click on the ConfigureAgent.cmd and run as administrator.
Server 
STEP 4: Enter Details 

cmd.exe opened in administrator mode with prompts.
  1. It will prompt about the replacement of server registration and update the local agent settings. Press N

    Server

  2. Agent Name
    Enter Name for this agent [if you would like to change]. By Default, it’s taking your system name as a prefix by the word Agent as your agent name. Press enter for default one.

    Server

  3. TFS Server Name
    Now, enter your TFS server Name and press enter. For ex: http://yourTFSserverName:8080/tfs/

    Server

  4. App pool Name
    Configure the agent under ‘Default’ Agent Pool and hit enter. [I'll explain another article for the detailed descriptions of Agent pools, Agent Queues, and agents. ]

    Server

  5. Agent’s working folder
    By Default, it will create a Folder _work in the same location where you are configuring your agent. If you would like to make any other folder as Agent’s working directory, then provide the path here. Later this working folder is used to download the source code and run the builds. I selected the Default one and hit enter.

    Server

  6. Run Agent as Service
    Now this is an important point here, I want to run the agent as a Windows Service, so press ‘Y’ and hit enter.  

    Server

  7. Enter Administrative credentials for agent service
    Provide credentials for the service. These credentials must have administrator rights.

    Server

  8. Agent as a service installed successfully.

We can see the _work folder under Agent as shown below,

Server

And the settings.json file also updated. 

Server

NOTE
ServerUrl, PoolId, AgentId, WindowsServiceName and WindowsServiceDisplayName generated successfully as shown in the settings.json file above.

Agent service
Under services, you can see the agent service is running as VSO Agent (tfs01.Agent-YourComputerName)

Server

 OR

We can see on the TFS portal under Agent Pools as shown,

Server

Agent has two sets of capabilities, which indicates what the agent can do. Capabilities are name-value pairs.
  • User capabilities – those defined by users
  • System capabilities - automatically discovered by the agent software
On selecting a particular agent and by clicking on Capabilities you can see on the right side as shown above.

How to Un-Configure agent

Step 1

Open a command prompt as administrator mode,

Server
Step 2 - Locate the Agent folder


Go to the folder where the build agent and the ConfigureAgent.cmd file exists. Copy the path as selected,

Server

Server

Step 3 - Run the unconfigure command

Run the command - .\agent\vsoagent.exe /unconfigure

Server

Step 4 - Service uninstalled

Service Uninstalled successfully as shown below,

Server
Summary

Hence, in this tutorial we saw what agents are and how to install, configure and unconfigure the agent as a service.

NOTE
To configure the agent in the Agent pool one must have administrator rights.