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

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

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

 

 

 This will open the agent pool for the project collection.

 

 

STEP 2 - Download the agent

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

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

 

Extract the zip file.

This will give below content inside the Agent folder.

STEP 3 - Configure the Agent

1. To configure the agent right click on RunAgent.cmd and run as an administrator as shown.
   
   
   
   
2. This will create a _diag folder and settings.json file under the agent folder.
   
   
   
   
3. If you open the settings.json file, it contains the information about your AgentName, PoolId, PoolName etc.
   
   
   
   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.

 

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
   
   
   
   
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.
   
   
   
   
3. TFS Server Name
   Now, enter your TFS server Name and press enter. For ex: http://yourTFSserverName:8080/tfs/
   
   
   
   
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. ]
   
   
   
   
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.
   
   
   
   
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.  
   
   
   
   
7. Enter Administrative credentials for agent service
   Provide credentials for the service. These credentials must have administrator rights.
   
   
   
   
8. Agent as a service installed successfully.

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

And the settings.json file also updated. 

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)

 OR

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

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,

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,

Step 3 - Run the unconfigure command

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

Step 4 - Service uninstalled

Service Uninstalled successfully as shown below,

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.